---
title: "MCP Description - mcpdesc"
description: "MCP Description is a portable, machine-readable format for what an MCP server offers — Think OpenAPI, but for the Model Context Protocol."
source: "https://mcpdesc.org/format/"
---

# 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 ](/docs/specification/0.7.0/)[Try it in the Editor ](/live-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 →](/docs/getting-started/#run-your-first-dump)