MCP Description (mcpdesc)

MCP Description (mcpdesc) is an open, portable, machine-readable format for describing a Model Context Protocol server in a single source of truth — its info, transports, security, capabilities, tools, resources, resource templates, and prompts. It is to MCP servers what OpenAPI is to HTTP APIs and AsyncAPI is to event-driven ones: a declarative contract you can generate docs from, lint, validate, diff, mock, and check a running server against. It gives the MCP ecosystem the descriptive layer it was missing.

• Single source of truth - One document declares the whole server surface — tools, resources, prompts, transports, and security together.
• Familiar tooling model - Because it mirrors the OpenAPI/AsyncAPI approach, existing habits around generation, linting, and validation carry straight over.
• Conformance checking - A server can be tested against its declared description, catching drift between what is documented and what actually ships.
• Portable and open - The format is not tied to a single vendor or client, so descriptions travel across the ecosystem.

In practice mcpdesc gives API and platform teams the same governance leverage over MCP servers that OpenAPI gave them over HTTP APIs — you can diff versions, mock a server before it exists, and lint it against house rules in CI. As agents proliferate and every provider races to ship an MCP server, a machine-readable description is what lets those servers be discovered, documented, and governed at scale rather than one hand-written README at a time. It pairs naturally with project-level wiring like mcp.json, which says what an agent connects to while mcpdesc says what each of those connections exposes.