MCPSpec: Giving MCP Servers the Documentation Layer They Deserve

MCP is the protocol making agentic AI real. 97 million monthly SDK downloads. Over 10,000 active public servers. 232% growth in server count over the past six months. Adopted by Anthropic, OpenAI, Google, Microsoft, and 146 member organizations through the Linux Foundation's Agentic AI Foundation. This is no longer an experiment. It's infrastructure.

And yet, if you want to understand what a given MCP server actually exposes, you're reading READMEs, parsing source code, or calling tools/list yourself and staring at raw JSON. There's no standardized, portable, machine-readable spec format. No interactive documentation you can hand to a team and say "here's what this server does."

REST APIs got OpenAPI. GraphQL got schema introspection. MCP deserves the same.

MCPSpec gives any MCP server human-readable docs and a machine-readable spec with one line of code. Open source. TypeScript and Python. Available today.

What MCPSpec Does

The fastest way to understand MCPSpec is to see it. TypeScript:

import { mcpspec } from "@mcpspec-dev/typescript";
 
const app = mcpspec(server, {
  info: { title: "My MCP Server", version: "1.0.0" },
});
 
app.listen(3000);

Python:

from mcpspec_dev import McpSpec
 
spec = McpSpec(server, info={"title": "My Server", "version": "1.0.0"})
app = spec.create_app()

That's it. Your MCP server now has three new endpoints.

/docs serves interactive, human-readable documentation. Dark theme. Collapsible groups for tools, resources, and prompts. Copy-to-clipboard on every schema. The kind of docs page you'd expect from a well-maintained REST API, generated automatically from your MCP server's actual capabilities.

/mcpspec.yaml produces a machine-readable specification in a standardized format (version 0.1.0). This is the file that unlocks tooling: registries, code generators, contract tests, governance dashboards. Think of it as the openapi.yaml equivalent for MCP.

/mcp proxies through to the actual MCP server, so clients can still connect normally.

Here's what matters about how this works. MCPSpec uses auto-introspection. It connects to your MCP server at the protocol level and calls tools/list, resources/list, and prompts/list to discover everything the server exposes. It never executes tools, reads resources, or accesses content. Introspection only. This means it works with any MCP server regardless of how it was built or which SDK it uses.

You get security controls out of the box. Exclude sensitive tools from documentation with pattern matching. Include only specific capabilities. Override descriptions for public-facing docs that need different language than internal tool descriptions.

CLI tooling for stdio-based servers is on the roadmap. The goal: point it at a stdio server, get a mcpspec.yaml, commit it to your repo. Documentation as code, even without HTTP.

The OpenAPI Parallel

Before OpenAPI, REST APIs worked fine. Developers built them, documented them in READMEs, tested them with curl, and integrated them by reading source code. It worked. Millions of APIs were built that way. Nobody was in crisis.

But it didn't scale.

OpenAPI didn't fix a broken system. It gave a working system a standard that unlocked composability. Once you had a machine-readable spec describing an API, suddenly you could auto-generate clients, build interactive docs, run automated contract tests, and discover APIs through searchable registries. None of those capabilities required changes to the underlying APIs. They just required a standardized way to describe them.

MCP is in the same place today, except the pace is 100x faster. REST took a decade to reach the point where OpenAPI became essential. MCP hit 10,000 servers in under two years. The protocol is well-designed and battle-tested. tools/list does its job. Servers expose their capabilities correctly. The ecosystem is thriving. But at this pace, the need for a standardized, portable spec format is not a nice-to-have. It's urgent. Every MCP server describes itself in its own way, in its own format, or not at all.

MCPSpec is that layer. Not replacing anything MCP already does well. Adding the documentation and discoverability infrastructure that the ecosystem is ready for.

Why Protocol-Level, Not SDK-Level

A design decision worth explaining. MCPSpec does not parse your source code, read decorators, or depend on any specific MCP SDK. It connects to your server via in-memory transport and queries it the same way any MCP client would.

This matters for three reasons.

First, it works with every MCP server. TypeScript SDK, Python SDK, custom implementation, it doesn't matter. If your server speaks MCP, MCPSpec can document it.

Second, it's resilient to SDK changes. When the Python SDK ships a new version or the TypeScript SDK refactors its internals, MCPSpec doesn't break. It depends on the protocol, not the implementation.

Third, the dependency footprint stays minimal. The TypeScript package uses raw Node.js http and js-yaml. No Express. No Fastify. No heavyweight framework. The Python package uses Starlette. Lightweight by design.

Caching is lazy. MCPSpec introspects your server on the first request, then caches the result. No startup penalty. No polling loop. Just fast responses after the initial discovery.

What This Unlocks

A machine-readable spec format for MCP servers is a foundation, not a feature. Here's what becomes possible once it exists.

Agent-readable discovery. Today, an AI agent can't evaluate an MCP server's capabilities without connecting, authenticating, and calling tools/list at runtime. With a public mcpspec.yaml or /docs endpoint, agents (and the developers building them) can see exactly what a server offers before going through auth flows. Registries become searchable. Developers browse interactive docs before installing anything. Agents can make informed decisions about which servers to connect to, without credentials.

Client tooling. Auto-generated clients from specs. If you know the exact tools a server exposes, their parameters, and their return types, you can generate type-safe client code. The same pattern that OpenAPI code generators enabled for REST.

Contract testing. Schema drift detection and breaking change alerts. When a server removes a tool or changes a parameter type, automated tests catch it before your agents fail in production. This is table stakes for any protocol used in enterprise environments where context integration determines success or failure.

Enterprise governance. Audit what servers expose before deploying them. Security teams can review a mcpspec.yaml file to understand exactly what capabilities an MCP server provides, what data it can access, and what actions it can take. No code review required. No running the server in a sandbox and manually testing every tool.

Ecosystem maturity. Every protocol that achieves enterprise adoption develops a spec-and-tooling layer. REST got OpenAPI, which spawned thousands of tools. GraphQL got schema introspection, which powered an entire developer experience ecosystem. MCP is entering its enterprise adoption phase. The tooling layer needs to grow with it.

Why Open Source, Why Now

MCP crossed a threshold in December 2025 when Anthropic donated it to the Linux Foundation's Agentic AI Foundation. 146 member organizations. Community governance. The protocol is no longer one company's project. It belongs to the ecosystem.

That transition from company-led to community-led is exactly when infrastructure tooling needs to emerge. Spec formats, documentation standards, and discovery mechanisms work only when the community adopts them. They can't be proprietary.

I built MCPSpec solving real problems while building MCP servers. The pattern was the same every time: build the server, manually write docs, manually maintain a description of what it exposes, watch those docs drift from reality. The same problem OpenAPI solved for REST APIs.

The project is available on npm, PyPI, and GitHub. MIT licensed.

The ask is simple. Try it on one of your MCP servers. If it's useful, tell me what to build next. If something's missing, open an issue. A spec format only becomes a standard when people use it and shape it.

The Bigger Picture

MCP is the protocol connecting AI agents to the real world. It solved the M-times-N integration problem. It gave agents runtime tool discovery. It earned adoption from every major AI platform. Now it's entering the phase where enterprises need to govern, audit, and scale their MCP deployments.

Every protocol that reaches this phase needs a documentation standard. REST got OpenAPI and that single spec format spawned an entire ecosystem of code generators, testing frameworks, API gateways, and developer portals. GraphQL got schema introspection and that powered GraphiQL, Apollo, and hundreds of developer tools. MCP deserves the same.

MCPSpec is my contribution to making that happen. One spec format. Human-readable docs. Machine-readable discovery. One line of code.

Let's build the tooling layer MCP deserves.