MCP Description Specification — Overview

Introduction

The MCP Description Specification defines a standard, machine-readable document that describes the capabilities of a Model Context Protocol (MCP) server.

An MCP Description provides a structured declaration of the tools, resources, prompts, transports, and capabilities offered by an MCP server, enabling clients, agents, developer tools, and platforms to discover and interact with MCP services in a consistent and interoperable way.

The specification borrows design principles from OpenAPI — the successful standard for describing HTTP APIs — while using MCP-native structures directly for tools, resources, and prompts.

This enables developers familiar with the API ecosystem to adopt the format quickly while preserving MCP-native semantics. Runtime observations can produce an Effective Protocol View, but tooling must not infer unobserved revisions, primitives, or authorization policy.

Problem Statement

The MCP ecosystem supports runtime discovery and capability inspection.

While this mechanism works for dynamic interactions, it presents several limitations:

1. Lack of a portable server description

MCP defines runtime discovery rather than a portable, offline server-surface document. Without a separate description artifact:

tools cannot inspect capabilities without connecting to the server
offline tooling is difficult
documentation generation requires a live connection or implementation-specific metadata

2. Limited interoperability between platforms

Different MCP tools and platforms often implement their own ways of representing MCP server capabilities, leading to:

inconsistent documentation formats
limited compatibility between MCP tooling ecosystems
difficulty sharing MCP server metadata

3. No protocol-defined portable description for MCP servers

Unlike REST APIs (OpenAPI) or event systems (AsyncAPI), the MCP protocol does not define a portable static description document that can represent an MCP server independently of a running instance.

This makes it difficult to support:

governance
automated validation
description-driven development
static documentation
offline discovery

Goals of the MCP Description Specification

The MCP Description specification addresses these limitations by defining a portable description format for MCP servers.

The specification enables:

Standardized server descriptions

An MCP Description document provides a consistent structure for declaring:

server metadata
transport configuration
available tools
resources and resource templates
prompts
server capabilities
flat document-wide tag catalogue

Offline discoverability

MCP servers can publish a description document without requiring a client to connect to the server.

This enables:

documentation portals
agent registries
package repositories
static validation

Tooling interoperability

A standard description format enables consistent tooling across the MCP ecosystem, including:

documentation generators
testing frameworks
agent discovery tools
IDE integrations
governance platforms

Description-driven development

Teams can define and validate MCP server capabilities before deployment, enabling workflows similar to API-first development used in modern API platforms.

Relationship to the MCP Protocol

The MCP Description specification does not replace the MCP protocol.

Instead, it complements the protocol by providing a static description format for server capabilities.

MCP Protocol	MCP Description
runtime communication	static declaration
discovery and runtime metadata	server metadata and protocol coverage
tool invocation	tool definitions
resource fetching	resource definitions

In other words:

MCP Protocol = runtime behavior
MCP Description = static server-surface description

Design Principles

The MCP Description specification follows several core design principles.

1. Alignment with existing API ecosystem standards

The specification adopts structures familiar to API developers, including concepts inspired by OpenAPI:

info object for server metadata
named securitySchemes and reusable requirements
reusable schema structures
declarative capability descriptions

This reduces the learning curve and enables reuse of existing tooling patterns.

2. MCP-native structures

While borrowing patterns from OpenAPI, the specification uses MCP protocol structures directly for capability declarations:

Tools use MCP’s inputSchema / outputSchema format (not OpenAPI’s Operation Object)
Resources use MCP’s uri / mimeType pattern
Prompts use MCP’s arguments array format
Capabilities preserve durable MCP server semantics across protocol revisions

A runtime observation can populate MCP-native declarations for the protocol revision and authorization context actually observed.

3. Explicit capability declarations

The document explicitly describes server capabilities such as:

tools
resources
prompts
transports

This ensures clients can understand an MCP server surface without executing protocol calls.

4. Support for vendor extensions

The specification allows vendor-specific extensions using the x- prefix convention.

This allows vendors and platforms to attach additional metadata without modifying the core specification.

5. Strict core schema

The core specification defines a strict schema to ensure:

predictable structure
strong validation
consistent tooling behavior

At the same time, vendor extensions remain flexible.

6. Separation of description and observation

The specification distinguishes between:

Concept	Example
described surface	tools, resources, prompts, tags
runtime observation	latency, CORS support
vendor metadata	platform-specific extensions (`x-...`)

This separation ensures that MCP Description documents remain stable and portable. Runtime observation data and platform-specific metadata belong in vendor extensions, not the core specification.

Typical Use Cases

The MCP Description specification enables several common scenarios in the MCP ecosystem.

MCP server documentation

Platforms can generate human-readable documentation describing MCP servers.

Agent discovery

AI agents can use MCP Description documents to identify available tools and resources before connecting to servers.

MCP registries

Organizations can maintain registries of MCP servers similar to API catalogs.

Description validation

CI pipelines can validate MCP server capabilities against a schema.

Governance

Organizations can enforce standards for MCP server design.

Vendor Extensions

The specification allows vendors to attach additional metadata through specification extensions.

Extensions follow the naming convention:

x-{organization}-{feature}

Example:

x-example-runtime-observations

These extensions may include:

runtime observations
generation metadata
platform-specific annotations
governance attributes

The core specification does not define the structure of these extensions, allowing vendors to evolve them independently.

Benefits for the MCP Ecosystem

Adopting a standardized MCP Description format provides several ecosystem-wide benefits.

Improved interoperability

Tools and platforms can exchange MCP server descriptions using a common format.

Better developer and AI experience

Developers and agents can inspect an MCP server capabilities without connecting to the server.

Stronger tooling ecosystem

Standardized descriptions enable richer tooling, including:

MCP documentation generators
agent discovery platforms
IDE integrations

Governance and compliance

Organizations can define validation rules for MCP servers using a standard schema.

Ecosystem growth

A standard description format makes it easier for new tools and platforms to integrate with MCP servers.

Summary

MCP Description 0.8.0 provides a portable, machine-readable description format for MCP servers, enabling consistent discovery, documentation, validation, and integration across the MCP ecosystem.

By standardizing how MCP servers declare their capabilities — using MCP-native structures and OpenAPI-inspired design patterns — the specification helps establish a foundation for a mature and interoperable MCP tooling ecosystem, similar to the role that OpenAPI plays in the HTTP API ecosystem.