MCP Analysis

A specification-grounded validator that separates MCP protocol conformance from agent usability and optional Headless design checks—then ranks the work by the coverage it recovers.

Ship an MCP agents can actually operate.

MCP Analysis is a specification-grounded validator and engineering guide for Model Context Protocol surfaces. It separates protocol compliance from design opinion, finds the places where agents must guess, and gives developers a backward-compatible path to improve the surface.

WHY THIS EXISTS

A technically valid MCP can still be difficult—or dangerous—for an agent to use. Vague tool names, ambiguous parameters, hidden mutation behavior, incomplete result contracts, and unbounded responses all push important decisions onto the model.

MCP Analysis makes those gaps visible. Every applicable check has a denominator, catalog completeness is stated instead of assumed, and the remaining work is ranked by the coverage it recovers.

THREE VALIDATION LAYERS

MCP specification conformance
Validate initialization, tool schemas, logging, pagination, errors, and observable requirements of MCP 2025-11-25.
Agent usability
Find unclear routing, vague inputs, unsafe mutations, missing result contracts, and responses that can overwhelm context.
Optional Headless readiness
Assess capability guidance, version transparency, MCP-delivered skills, operating scope, bidirectional feedback, and MCP Apps presentation. These checks are configurable policy—not universal protocol requirements.

FROM EVIDENCE TO AN ACTIONABLE REPORT

Collect a live stdio or Streamable HTTP surface, or load a saved evidence bundle. Run the generic checks or apply an optional profile. Save the complete JSON assessment, work the ranked next steps, then render a print-ready developer report with before-and-after coverage.

Every report answers three questions:

• How much passed?
• Did the assessment see the whole catalog?
• What should the developer fix first?

RUN IT

Python 3.10+ is the only command-line runtime dependency. A desktop application is also available for macOS and discovers MCP servers already configured in Claude, Cursor, and Windsurf.

Quick start:

python3 mcp_validate.py --dump examples/headless_surface.json --profile profiles/headless.json

EXPLORE THE PROJECT

Project website
https://coretez.github.io/mcp_analysis/

Source repository
https://github.com/coretez/mcp_analysis

Usage guide
https://github.com/coretez/mcp_analysis/blob/main/DOCUMENTATION.md

Headless thesis
https://blogs.fluencysecurity.com/what-makes-an-mcp-headless/

MCP Analysis is publicly viewable, proprietary source-available software from Fluency Corp. Internal non-production evaluation is permitted under the repository license; production, commercial, hosted-service, and redistribution rights require a separate written license.

WATCH THE PROJECT

Start with the 56-second overview, then go deeper on what it means to convert an application into a genuinely headless MCP surface.