MCP Description - 'mcpdesc'

A portable, machine-readable format for describing 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 design-first 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.

Protocol vs. Description

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

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 or JSON. Either way, an mcpdesc document includes 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"]
      }
    }
  ]
}

Generate an MCP description from a live server

Point the mcpcontract CLI at any MCP server to produce an mcpdesc document you can open in the editor:

mcpcontract dump \
  --transport streamable-http \
  --url "https://your-mcp-server/mcp" \
  --output server.mcpdesc.json

Read the docs →