MCP Design Specification · v1.0

Design your MCP server before you write a line of code.

MCPDS is to MCP servers what OpenAPI is to REST APIs - a single declarative *.mcp.yaml that describes a Model Context Protocol server in a tool-independent, human-readable format.

Read the specification → Explore the tools

$ npm install @mcpds/spec

weather.mcp.yaml

# yaml-language-server: $schema=.../@mcpds/spec
mcpds: "1.0"
server:
  name: weather-mcp
  version: 1.0.0
  description: Weather data for AI agents
transports:
  - type: stdio
auth:
  type: none
tools:
  - name: get_forecast
    description: Return a 7-day forecast
    input:
      type: object
      properties:
        city: { type: string }

Tool-independent

One spec, many tools - scaffolders, docs, registries and clients all read the same file.

Human-readable

Plain YAML you can author, review and diff - no proprietary format, no lock-in.

Source of truth

Drive scaffolding, documentation, client config and registry entries from the contract.

The standard & its ecosystem

Start exploring

View the full spec →

Specification

The MCPDS 1.0 schema, section by section - identity, transports, auth, tools and more.

8 sections→

Tools

MCP Designer, the @mcpds/spec package and the JSON Schema that power the workflow.

3 tools→

Webinars

Live courses and on-demand workshops focused entirely on building MCP servers.

4 courses→

Blog

Release notes, guides and engineering deep-dives on design-first MCP development.

Latest writing→

BUILT ON MCPDS

MCP Designer - the visual editor for `.mcp.yaml`

Design every MCPDS section visually, validate live and get clean YAML on disk. Runs entirely on your machine - no account, no cloud, no telemetry.

See the tools → mcpdesigner.app