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. Every check is counted—so a result has a denominator, and the work is ranked by the coverage it recovers.
- 3
- distinct validation layers
- 90
- rules, each with its own denominator
- 2
- ways to run: desktop app or CLI
$ assess surface.json
3,367 of 4,033 checks passed83.5% · 56 rules applied · catalog complete
SPECIFICATIONPASS
AGENT USABILITYWARN
EXTENSIONSPASS
NEXT STEPS · RANKED BY IMPACT
+4.24 Teach the agent when to choose the tool.
+3.40 Make read and write behavior explicit.
+2.11 Connect required inputs to the outcome.
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 WHAT’S NEW
Findings now come
with a denominator.
The latest release turns the validator from a list of complaints into a measurement. It records every evaluation, states whether the whole catalog was seen, ranks the remaining work by the coverage it recovers—and ships as a desktop application.
Validator
Every check is counted
Rules used to report only what they faulted, so a finding count had no denominator. Each of the 90 rules now records the targets it examined, and the headline reads checks passed over checks applicable.
Guidance
Next steps ranked by impact
Work is ordered by the coverage each item recovers, with the pass rate it would produce. Blocking failures collapse into one leading step, so a handful of single-finding failures cannot crowd out the change that moves the number.
Desktop
An application, not just a command
An Electron interface over the same engine. It lists the MCP servers already installed on the machine—read from the Claude, Cursor, and Windsurf configs—so a first run needs no paths at all.
Evidence
Catalog completeness is stated, not assumed
A run now says outright whether it collected every tool: complete, truncated, or unverified. A partial catalog no longer reads as a clean one.
Evidence
Capture once, analyze many times
--save-surface writes the collected evidence to a bundle that re-analyzes offline with identical findings. Use it for baselines, for CI, and for sharing a surface with someone who cannot reach the server.
Security
Credentials never enter the command line
Bearer tokens are read from MCP_BEARER_TOKEN, passed only to the analysis subprocess, and redacted from anything printed, saved, or shown in an error.
Report
Rebuilt as a print document
Monochrome ink hierarchy, paginated pages, and colour reserved for significant callouts. It leads with next steps and carries a baseline delta that moves when coverage does, even when finding counts do not.
Docs
A usage guide worth reading
Sources versus rule sets, how to read coverage, and how to choose what to fix first—plus install and packaging guides, and a test suite grown from 24 checks to 60.
06 RUN IT
From live surface
to useful report.
Python 3.10+ is the only runtime requirement, on the command line or in the desktop app. Start with live evidence when possible, save the surface so the run can be repeated, then render the developer report.
Collect
Pick a server the app already found, start a stdio or HTTP server, or load a captured surface bundle.
Assess
Run generic checks or apply the Headless or Fluency policy profile.
Improve
Work the ranked next steps, making 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 ↗