Copy page

Guides

Documenting MCP Servers

The Dev Portal renders a dedicated Model Context Protocol (MCP) setup UI for any OpenAPI operation that includes the x-mcp-server extension. The card replaces the standard request/response view with the MCP endpoint URL, a copy button, and tabbed installation instructions for Claude, ChatGPT, Cursor, VS Code, and a generic config.

When to use this guide

Use this guide when you want to surface an MCP server in your Dev Portal that you are not building with Zuplo's MCP Server Handler. Common scenarios:

• You proxy a third-party MCP server through a Zuplo route (for example, with a URL forward or custom handler) and want to publish setup instructions for it.
• You hand-author an OpenAPI spec for an MCP server hosted outside Zuplo.
• You catalog multiple MCP servers — some yours, some external — in a single Dev Portal.

In every case, this guide covers only the documentation side: how the Dev Portal renders the MCP card. Authentication, rate limiting, and any other gateway behavior is configured on the underlying route as usual.

Adding the extension

Add x-mcp-server to the operation that represents the MCP endpoint. MCP servers typically use POST, but the extension works on any HTTP method.

openapi.json
{
  "paths": {
    "/mcp": {
      "post": {
        "summary": "Acme Docs MCP",
        "description": "MCP endpoint for searching Acme's documentation.",
        "operationId": "acmeDocsMcp",
        "x-mcp-server": {
          "name": "acme-docs",
          "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"
          }
        }
      }
    }
  }
}

For a quick setup with no metadata, use the shorthand "x-mcp-server": true. The operation summary is then used as the server name.

Extension properties

Each entry in tools accepts:

MCP URL resolution

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

For example:

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 is https://api.example.com/mcp/docs. Make sure the server URL points to wherever the MCP server actually accepts requests — for proxied servers, that is typically your Zuplo gateway URL.

Complete example

This minimal but complete OpenAPI spec produces an MCP endpoint page in the Dev Portal:

mcp-api.json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Acme Docs MCP",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.example.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/mcp": {
      "post": {
        "tags": ["MCP"],
        "summary": "Acme Docs MCP",
        "description": "MCP endpoint for searching Acme's documentation.",
        "operationId": "acmeDocsMcp",
        "x-mcp-server": {
          "name": "acme-docs",
          "version": "1.0.0",
          "tools": [
            {
              "name": "search_docs",
              "description": "Search the documentation"
            }
          ]
        },
        "responses": {
          "200": {
            "description": "MCP response"
          }
        }
      }
    }
  }
}

Reference the spec from your Dev Portal config (see API Reference for the 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;

Generated UI

When the Dev Portal detects x-mcp-server on an operation, the page renders:

• MCP Endpoint card — the full URL with a copy button.
• AI Tool Configuration tabs with setup instructions for:
  • Claude — add via the Connectors UI or the claude mcp add CLI command.
  • ChatGPT — app setup via Settings → Apps → Advanced Settings.
  • Cursor — mcp.json configuration (global or project-level).
  • VS Code — .vscode/mcp.json with native HTTP transport 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 because they use a different interaction model.

Related

• x-mcp-server extension reference — the underlying OpenAPI extension.
• MCP Server Handler — build an MCP server on Zuplo (and skip this guide entirely).
• MCP Server overview — concepts, capabilities, and the Zuplo-native build path.