Documenting MCP Servers

Zudoku can render a dedicated MCP endpoint UI for any OpenAPI operation that has the x-mcp-server extension. When detected, the operation page replaces the standard request/response view with an MCP card showing the endpoint URL, a copy button, and tabbed installation instructions for Claude, ChatGPT, Cursor, VS Code, and a generic config.

Adding the extension

Add the x-mcp-server extension to an operation in your OpenAPI spec. While MCP servers typically use POST, the extension works on any HTTP method:

openapi.json (paths section)
{
  "paths": {
    "/mcp": {
      "post": {
        "summary": "My MCP Server",
        "description": "MCP endpoint for querying documentation.",
        "operationId": "mcpEndpoint",
        "x-mcp-server": {
          "name": "my-mcp-server",
          "version": "1.0.0",
          "tools": [
            {
              "name": "search_docs",
              "description": "Search the documentation"
            },
            {
              "name": "get_page",
              "description": "Retrieve a specific documentation page"
            }
          ]
        },
        "responses": {
          "200": {
            "description": "MCP response"
          }
        }
      }
    }
  }
}

The UI will display beneath the operation heading, showing the full MCP URL derived from the server URL and the operation path.

You can also use the shorthand "x-mcp-server": true to enable the MCP UI without specifying any metadata. In this case, the operation's summary is used as the server name.

Extension properties

Each tool in the tools array has:

MCP URL resolution

The displayed MCP URL is constructed from the server URL of the API and the path of the operation. The server URL comes from the OpenAPI servers array (or the operation-level servers override if present).

For example, with this configuration:

Code
{
  "servers": [{ "url": "https://api.example.com" }],
  "paths": {
    "/mcp/docs": {
      "post": {
        "x-mcp-server": { "name": "docs-mcp" },
        "responses": { "200": { "description": "OK" } }
      }
    }
  }
}

The displayed MCP URL will be https://api.example.com/mcp/docs.

Complete example

This is a minimal but complete OpenAPI spec that produces an MCP endpoint page:

mcp-api.json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Documentation MCP Server",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.example.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/mcp": {
      "post": {
        "tags": ["MCP"],
        "summary": "Documentation MCP Server",
        "description": "MCP endpoint powered by Inkeep for searching and querying documentation.",
        "operationId": "mcpEndpoint",
        "x-mcp-server": {
          "name": "example-docs",
          "version": "1.0.0",
          "tools": [
            {
              "name": "search_docs",
              "description": "Search the documentation"
            }
          ]
        },
        "responses": {
          "200": {
            "description": "MCP response"
          }
        }
      }
    }
  }
}

Then reference this spec in your Zudoku config (see API Reference for full apis configuration):

zudoku.config.tsx
import type { ZudokuConfig } from "zudoku";

const config: ZudokuConfig = {
  apis: [
    {
      type: "file",
      input: "./mcp-api.json",
      path: "mcp",
    },
  ],
  navigation: [
    {
      type: "link",
      label: "MCP Server",
      to: "/mcp",
      icon: "bot",
    },
  ],
};

export default config;

You can see a live example of this in the Cosmo Cargo demo.

Generated UI

When Zudoku detects the x-mcp-server extension on an operation, the page shows:

• MCP Endpoint card with the full URL and a copy button
• AI Tool Configuration tabs with setup instructions for:
  • Claude — claude_desktop_config.json using native HTTP transport
  • ChatGPT — connector setup via Settings
  • Cursor — mcp.json configuration (global or project-level)
  • VS Code — .vscode/mcp.json for GitHub Copilot
  • Generic — standard mcp.json format compatible with most MCP clients

The standard method badge, request body, parameters, and sidecar panels are hidden for MCP endpoints since they use a different interaction model.

Using with Zuplo

If you are using Zuplo to host your API, the x-mcp-server extension is automatically added to POST operations that use the mcpServerHandler. No manual schema changes are needed. See the Zuplo MCP documentation for details.