MCP Description

A portable, machine-readable format for what an MCP server offers — its tools, resources, prompts, transports, and security — declared in a single static document. Think OpenAPI, but for the Model Context Protocol.

Read the specification Try it in the Editor

Specification version 0.7.0 · Draft.

What it is

The MCP ecosystem relies on runtime discovery through protocol initialization and capability inspection. That works well for dynamic interactions, but it limits offline tooling, cross-platform interoperability, and contract-driven workflows. An MCP Description addresses this by declaring a server's capabilities as a static, curated document you can version, share, and validate — independently of any running server.

The toolkit works on this format

Every tool in the MCP Toolkit suite reads and writes MCP Descriptions: mcpcontract captures them from live servers and compares releases, the editor authors and previews them, mcpmock serves them as mock servers, and mcptest validates servers against them.

Why it matters

Standardized descriptions

A consistent structure for declaring server metadata, transports, tools, resources, prompts, and capabilities.

Offline discoverability

Platforms can index and display server capabilities without establishing a runtime connection.

Tooling interoperability

Documentation generators, testing frameworks, discovery tools, and IDE integrations can operate on a common format.

Contract-driven development

Teams can define and validate MCP server capabilities before deployment.

Protocol vs. Description

An MCP Description does not replace the MCP protocol — it complements it. The protocol defines runtime behavior; a description defines the server contract.

MCP Protocol	MCP Description
Runtime communication	Static declaration
Initialize handshake	Server metadata
Tool invocation	Tool definitions
Resource fetching	Resource definitions

A minimal example

An MCP Description can be written in YAML orJSON — both express the same document. The file extension is not significant; by convention many authors use .mcpdesc.yaml or.mcpdesc.json. Either way, it must declare the specification version, server info, at least one transport, and at least one capability — tools, resources, resource templates, or prompts.

mcpdesc: "0.7.0"
info:
  name: chess-rating-server
  version: 1.0.0
transports:
  - type: stdio
    command: chess-rating
    args: [serve]
tools:
  - name: get_player_rating
    description: Get the current Elo rating for a chess player
    inputSchema:
      type: object
      properties:
        player_id:
          type: string
          description: Player identifier
      required: [player_id]

{
  "mcpdesc": "0.7.0",
  "info": {
    "name": "chess-rating-server",
    "version": "1.0.0"
  },
  "transports": [
    { "type": "stdio", "command": "chess-rating", "args": ["serve"] }
  ],
  "tools": [
    {
      "name": "get_player_rating",
      "description": "Get the current Elo rating for a chess player",
      "inputSchema": {
        "type": "object",
        "properties": {
          "player_id": { "type": "string", "description": "Player identifier" }
        },
        "required": ["player_id"]
      }
    }
  ]
}