Generating mcp.json

An mcp.json file captures an MCP server's tools, resources, and prompts in a static, versionable format. Sourcey reads this file to generate documentation.

From a running server

mcp-parser connects to an MCP server, calls the introspection endpoints, and writes the snapshot to disk.

npm install mcp-parser

stdio

mcp-parser snapshot --stdio "node my-server.js" -o mcp.json

SSE

mcp-parser snapshot --sse http://localhost:3000/sse -o mcp.json

Streamable HTTP

mcp-parser snapshot --http http://localhost:3000/mcp -o mcp.json

Authentication

Pass headers for servers that require auth:

mcp-parser snapshot --http https://api.example.com/mcp \
  --header "Authorization:Bearer your-token" \
  -o mcp.json

By hand

You can write mcp.json directly. The format mirrors the MCP protocol's own type definitions. Here's a minimal example:

{
  "mcpSpec": "0.2.0",
  "server": { "name": "my-server", "version": "1.0.0" },
  "description": "What this server does.",
  "tools": [
    {
      "name": "my_tool",
      "description": "What this tool does.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string", "description": "Search query" }
        },
        "required": ["query"]
      }
    }
  ]
}

See mcp-schema for the full type definitions and JSON Schema.

Validating

Check an mcp.json for structural errors and best-practice warnings:

mcp-parser validate ./mcp.json

Valid — no issues found.

Validation checks for required fields, duplicate names, missing descriptions, and invalid schemas.

Generating llms.txt

Generate an llms.txt index for AI agent discovery:

mcp-parser generate ./mcp.json --format llms-txt -o llms.txt

For a complete markdown reference:

mcp-parser generate ./mcp.json --format llms-full-txt -o llms-full.txt

Note

sourcey build also emits llms.txt and llms-full.txt automatically as part of the site build. The mcp-parser CLI is useful when you want these files without building a full docs site.