TypeScript types and JSON Schema for Model Context Protocol server specifications.

Define, validate, and share static snapshots of MCP servers.

This package describes two distinct documents:

Both have been called mcp.json. Use a filename such as api.snapshot.json for snapshots when working with an Agent Plugin. The standard plugin configuration requires $schema and mcpServers; it does not contain introspection results.

import { agentPluginsMcpSchema, AGENT_PLUGINS_MCP_SCHEMA_URL } from "mcp-schema/agent-plugins";
import type { AgentPluginsMcpConfig } from "mcp-schema/agent-plugins";
import { Ajv2020 } from "ajv/dist/2020.js";

const config: AgentPluginsMcpConfig = {
  $schema: "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  mcpServers: {
    api: { type: "streamable-http", url: "https://example.com/mcp" },
    local: { type: "stdio", command: "./bin/server", cwd: "${PLUGIN_ROOT}" },
  },
};
const validate = new Ajv2020().compile(agentPluginsMcpSchema);
console.log(validate(config), AGENT_PLUGINS_MCP_SCHEMA_URL);

These exports are also available from the main entrypoint. The official schema is bundled locally, and its TypeScript types are generated from those exact schema bytes. It is a closed union of stdio, streamable-http, and legacy sse. The normative specification additionally defines URL/header semantics, filesystem containment, variable expansion, and failure boundaries that a JSON Schema alone cannot enforce. mcp-parser implements those configuration checks and named-server snapshotting.

The published canonical schema is the authority in src/agent-plugins/mcp.schema.json. Its generated runtime export and types must pass npm run check:agent-plugins in CI. Run npm run check:agent-plugins -- --upstream to compare with the canonical online schema and detect a newer release on the published specification page. The Agent Plugins upstream workflow runs that check every Monday at 03:17 UTC and can also be dispatched manually. A new release or schema change fails the check for review. After adopting a published specification release, review its normative semantic changes in mcp-parser, update the canonical bytes, regenerate with npm run generate:agent-plugins, and test both packages together. A working draft is not automatically a supported release. No schema is downloaded at runtime. Agent Plugins schema material is Apache-2.0 licensed; its license and attribution are distributed with the package.

An mcp.json document is a static description of an MCP server's surface, not a wire protocol. This package is therefore revision-independent: it records which protocol revision a snapshot came from without being tied to any one of them.

mcpVersion holds the revision the server answered with, and mcpVersions holds the set it reports it supports. Both are validated as YYYY-MM-DD shapes rather than against a list of known revisions, so a document produced against a revision newer than this package still validates.

Types cover tools (with inputSchema, outputSchema, and annotations), resources, resource templates, prompts, icons, server capabilities, and all three transports (stdio, Streamable HTTP, and the specification-deprecated HTTP+SSE).

Deliberately out of scope: JSON-RPC envelopes, content types, sessions, and the client features the specification deprecated in 2026-07-28 (roots, sampling, logging). A snapshot describes what a server offers, not a conversation with it.

npm install mcp-schema

import type { McpSpec, McpTool, McpResource } from "mcp-schema";

const spec: McpSpec = {
  mcpSpec: "0.3.1",
  mcpVersion: "2025-11-25",
  server: { name: "weather-server", version: "1.0.0" },
  description: "Real-time weather data for any city.",
  tools: [
    {
      name: "get_weather",
      description: "Get current weather for a location",
      inputSchema: {
        type: "object",
        properties: {
          city: { type: "string", description: "City name" },
        },
        required: ["city"],
      },
      outputSchema: {
        type: "object",
        properties: {
          temperature: { type: "number" },
          conditions: { type: "string" },
        },
      },
      annotations: { readOnlyHint: true },
    },
  ],
  resources: [
    {
      uri: "weather://cities",
      name: "Supported Cities",
      description: "List of cities with weather data",
      mimeType: "application/json",
    },
  ],
};

import { mcpSpecSchema } from "mcp-schema/schema";

// Use with any JSON Schema validator
import Ajv from "ajv";

const ajv = new Ajv();
const validate = ajv.compile(mcpSpecSchema);

const valid = validate(spec);
if (!valid) {
  console.error(validate.errors);
}

An MCP spec (mcp.json) is a static snapshot of an MCP server's capabilities; its tools, resources, and prompts. Think of it as openapi.json for MCP servers.

MCP servers describe themselves at runtime via tools/list, resources/list, and prompts/list. An MCP spec captures that information in a versionable, shareable file that can be used for documentation, validation, and code generation.

The root document:

{
  "name": "search_docs",
  "description": "Search documentation by query",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "limit": { "type": "number", "default": 10 }
    },
    "required": ["query"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "results": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "title": { "type": "string" },
            "url": { "type": "string" }
          }
        }
      }
    }
  },
  "annotations": {
    "readOnlyHint": true,
    "openWorldHint": true
  }
}

{
  "uri": "docs://index",
  "name": "Documentation Index",
  "description": "Top-level index of all documentation pages",
  "mimeType": "application/json"
}

{
  "uriTemplate": "docs://pages/{slug}",
  "name": "Documentation Page",
  "description": "A single documentation page by slug",
  "mimeType": "text/markdown"
}

{
  "name": "summarize_page",
  "description": "Summarize a documentation page",
  "arguments": [
    { "name": "url", "description": "Page URL to summarize", "required": true },
    { "name": "style", "description": "Summary style (brief, detailed)", "required": false }
  ]
}

• MCP Specification (current revision)
• Specification repo (includes JSON Schema for each protocol version)
• TypeScript SDK (@modelcontextprotocol/sdk)
• Python SDK (mcp on PyPI)

• mcp-parser: snapshot live MCP servers, parse and validate mcp.json, and generate markdown/docs outputs
• sourcey: generate documentation from MCP specs, OpenAPI, and markdown

MIT