{mcpdesc}

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 specificationTry it in the Editor

0.8.0 · Stable. 0.7.0 remains available.

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 ProtocolMCP Description
Runtime communicationStatic declaration
Initialize handshakeServer metadata
Tool invocationTool definitions
Resource fetchingResource 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"

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 →