---
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.8.0/)[Try it in the Editor ](/live-editor)

0.8.0 · Stable. [0.7.0 remains available.](/docs/specification/0.7.0/)

## 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, a v0.8 document identifies the format version, server `info`, and the MCP protocol revisions it describes. Transports and primitive collections are included when the document declares them.

```
$schema: https://mcpdesc.org/schema/mcp-description/0.8.0.json
mcpdesc: "0.8.0"
info:
  name: chess-rating-server
  title: Chess Rating MCP Server
  version: 1.0.0
protocolVersions:
  - "2026-07-28"
```

```
{
  "$schema": "https://mcpdesc.org/schema/mcp-description/0.8.0.json",
  "mcpdesc": "0.8.0",
  "info": {
    "name": "chess-rating-server",
    "title": "Chess Rating MCP Server",
    "version": "1.0.0"
  },
  "protocolVersions": ["2026-07-28"]
}
```

## 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-server.example/mcp" \
  --protocol auto \
  --format yaml \
  --output server.mcpdesc.yaml
```

[Read the docs →](/docs/getting-started/#run-your-first-dump)