MCPDS — MCP Design Specification

A tool-agnostic, declarative format for describing Model Context Protocol servers.

MCPDS is to MCP servers what OpenAPI is to REST APIs. Today MCP servers exist only as code — there's no shared way to design, review, document, or generate them across languages and tools. MCPDS defines a single human-readable document (*.mcp.yaml) that any tool can read, validate, and build on.

This repository is the home of the MCPDS standard and the @mcpds/spec npm package, which ships the schema and TypeScript types for use in tools built on top of MCPDS.

MCP Designer — the official visual editor for .mcp.yaml files — is built on top of this standard. See mcpdesign.org.

Repository contents

Path	Description
schemas/mcpds-1.0.0.md	Human-readable specification (latest)
schemas/mcpds-1.0.schema.json	JSON Schema for validating .mcp.yaml files
src/types.ts	TypeScript types (McpdsDocument, etc.)
src/schema/mcpds-schema.ts	JSON Schema object (TypeScript source of truth)
examples/	Sample .mcp.yaml documents

Example

A minimal .mcp.yaml describing a server, its transport, and one tool:

mcpds: "1.0"

server:
  name: cz.restapi/mcp
  title: REST API Design Guide
  description: Provides documentation for REST API design.
  version: 1.0.0
  websiteUrl: https://www.restapi.cz
  authors:
    - name: Miroslav Holec
      url: https://holec.ai
  license: MIT

transports:
  - type: streamable-http
    url: https://www.restapi.cz/mcp
    headers:
      - name: x-api-key
        description: Authentication using an API key (token).
        isRequired: true
        isSecret: true
  - type: stdio

tools:
  - name: fetch
    title: Fetch Documentation
    description: Returns relevant snippets for a given prompt via semantic search.
    inputSchema:
      type: object
      properties:
        phrase:
          type: string
          description: Search phrase.
          minLength: 3
          maxLength: 20
      required: [phrase]

More complete examples live in examples/ — see example.mcp.yaml (full-feature reference with auth, resources and prompts).

Using the package

npm install @mcpds/spec

import { mcpdsSchema, type McpdsDocument } from "@mcpds/spec";

Subpath exports:

import schema from "@mcpds/spec/schema";

CLI

The package can be run directly with npx @mcpds/spec for quick package and schema version checks:

npx @mcpds/spec --help
npx @mcpds/spec --version

From this repository checkout, use the local npm binary after building:

npm run build
npm exec -- mcpds-spec --help

When installed globally, it exposes the mcpds-spec binary:

npm install -g @mcpds/spec
mcpds-spec --help

AI Skills

Install the MCPDS skill for Claude Code, Cursor, and GitHub Copilot with one command.

Globally, for all projects:

npx skills add mcpdesignorg/mcpds -g -a claude-code -a cursor -a github-copilot -y

For this project only:

npx skills add mcpdesignorg/mcpds -a claude-code -a cursor -a github-copilot -y

Update or remove the skill:

npx skills update mcpds
npx skills remove mcpds

JSON Schema

The schema is defined in TypeScript first, but made available as JSON Schema as well, for wider compatibility. The .json file is generated from the TypeScript source via tools/generate-schema.mjs.

If you want to validate or generate .mcp.yaml files, reference the bundled JSON Schema directly:

# yaml-language-server: $schema=https://unpkg.com/@mcpds/spec/schemas/mcpds-1.0.schema.json

Or resolve it from the package in code:

import schema from "@mcpds/spec/schema";
// schema.$id === "https://mcpds.org/schema/1.0"

Versioning

The package version tracks the MCPDS schema version. A major version bump signals a breaking change to the schema structure.

Contributing

See CONTRIBUTING.md.

License

MIT — created by Miroslav Holec (@mirekholec)