RAW SURFACEParts bin
search_events(query: string)- Agent invents query syntax
- Agent guesses thresholds
- Empty results look healthy
{ "sources": [] }
MCP surface engineering
Ship an MCP
agents can actually operate.
MCP Analysis separates protocol compliance from design opinion, finds the places where agents must guess, and gives developers a backward-compatible path to improve the surface.
- 3
- distinct validation layers
- 4
- parts to every recommendation
- 1
- developer-ready HTML report
$ assess surface.json
SPECIFICATIONPASS
AGENT USABILITYWARN
EXTENSIONSPASS
MENTOR GUIDANCE
01 Add a read-only preview before consequential writes.
02 Make cursor inputs optional; preserve first-page behavior.
03 Capture error results and verify their schemas.
01 THE PROBLEM
An MCP is not
just your API.
An API gives an agent the parts. A genuinely headless MCP gives it the assembled machine.
Fluency’s headless thesis argues that useful application logic traditionally lives in the interface: which fields matter, what sequence is safe, how absence should be interpreted, and when an action must be refused. An agent needs that knowledge at the MCP boundary—not hidden in a screen it never sees.
Explore “What makes an MCP Headless?” ↗HEADLESS SURFACEAssembled machine
evaluate_datasource_health(scope)- Workflow is built in
- Judgment is versioned
- Absence becomes explicit
severity critical · coverage 0 of 14
02 WHAT IT ASSESSES
Three layers.
No blurred lines.
The protocol is authoritative. Quality rules are engineering judgment. Headless conventions are optional policy. The report keeps them separate so teams know exactly what failed—and why.
01
Specification
Protocol truth
Validate initialization, tools, schemas, logging, pagination, errors, and the observable requirements of MCP 2025-11-25.
02
Quality
Agent usability
Find vague parameters, ambiguous routing, unsafe mutations, missing result contracts, and responses that can overwhelm context.
03
Extensions
Headless readiness
Assess capability guidance, version transparency, MCP-delivered skills, bidirectional feedback, operating scope, and MCP Apps UI.
InitializeTool schemasLoggingPaginationSkill loadingMCP Apps
03 MORE THAN A LINTER
Find the gap.
Teach the fix.
The assessment does not stop at “warning.” Its mentoring layer turns every actionable rule into an engineering conversation.
Read the workflow ↗Why it matters
Connect every warning to the failure mode an agent or developer will actually experience.
What to change
Recommend a concrete contract, description, pagination, safety, or presentation improvement.
Keep it compatible
Favor additive fields, optional inputs, aliases, and migration windows over abrupt breaking changes.
Prove the fix
Name the runtime evidence and focused tests needed before the finding can be considered closed.
04 WATCH THE METHOD
An MCP is not
your API.
See how to convert an application into a headless surface by moving workflow knowledge, product judgment, and trust controls to the agent-facing boundary.
Watch on YouTube ↗05 RUN IT
From live surface
to useful report.
Python 3.10+ is the only runtime requirement for the validator. Start with live evidence when possible, save the full JSON, then render the developer report.
Collect
Initialize a stdio or HTTP server, or load a captured surface bundle.
Assess
Run generic checks or apply the Headless or Fluency policy profile.
Improve
Use mentor guidance to make additive, testable contract changes.
Compare
Rerun the same evidence path and render the before/after HTML report.
Quick startstdio · headless profile · JSON
$ python3 mcp_validate.py \
--stdio "uv --directory /path/to/mcp run server" \
--profile profiles/headless.json \
--json reports/assessment.jsonPUBLICLY VIEWABLEOpen to inspect.
Open to inspect.
Owned by Fluency Corp.
MCP Analysis is proprietary source-available software. Internal non-production evaluation is permitted. Production, commercial, hosted-service, and redistribution rights require a separate written license.
Read the Fluency Commercial Source License ↗