internal-swagger-mcp

Let AI agents query your internal Swagger platform's API docs via MCP.

This server talks to the internal Swagger management platform's private share endpoint (/flow/swagger/share?uid=...), not a public OpenAPI URL.

Tools

| Tool | Purpose | |------|---------| | swagger_list_sources | List all configured services and their cache status | | swagger_search_api | Search APIs by keyword (filterable by method / service) | | swagger_get_api_detail | View an API's full parameters and mock example | | swagger_refresh_cache | Force-refresh the doc cache (default TTL is 30 minutes) |

Connecting MCP clients

Requires Node.js ≥ 18. Swagger sources are always supplied by the client — this server holds no configuration. Pass them in stdio mode via the SWAGGER_SOURCES env var or --sources-file, and in HTTP mode via the X-Swagger-Sources header per request. Use project scope for every client's MCP config so each repo pins its own sources and the config can be committed to git. In the snippets below, <SOURCE> looks like http://your-server/...#/swaggerManage?uid=xxx; if swagger_list_sources works inside the client, the integration is up.

Start in HTTP mode (for deploying on a shared internal host):

npx -y internal-swagger-mcp --http   # defaults to port 3000; override with --port or PORT

Claude Code

Official docs — using --scope project writes to the project root's .mcp.json.

Local (stdio):

claude mcp add swagger --scope project --env SWAGGER_SOURCES='["<SOURCE>"]' -- npx -y internal-swagger-mcp

Remote (HTTP):

claude mcp add --transport http swagger --scope project http://<internal-IP>:3000/mcp --header 'X-Swagger-Sources: ["<SOURCE>"]'

opencode

Official docs — place this in opencode.json at the project root.

Local (stdio):

{
  "mcp": {
    "swagger": {
      "type": "local",
      "command": ["npx", "-y", "internal-swagger-mcp"],
      "environment": {
        "SWAGGER_SOURCES": "[\"<SOURCE>\"]"
      }
    }
  }
}

Remote (HTTP):

{
  "mcp": {
    "swagger": {
      "type": "remote",
      "url": "http://<internal-IP>:3000/mcp",
      "headers": {
        "X-Swagger-Sources": "[\"<SOURCE>\"]"
      }
    }
  }
}

Cursor

Official docs — place this in .cursor/mcp.json at the project root.

Local (stdio):

{
  "mcpServers": {
    "swagger": {
      "command": "npx",
      "args": ["-y", "internal-swagger-mcp"],
      "env": {
        "SWAGGER_SOURCES": "[\"<SOURCE>\"]"
      }
    }
  }
}

Remote (HTTP):

{
  "mcpServers": {
    "swagger": {
      "url": "http://<internal-IP>:3000/mcp",
      "headers": {
        "X-Swagger-Sources": "[\"<SOURCE>\"]"
      }
    }
  }
}

Sources file

When the source list belongs to the project, pass --sources-file <path> instead of pasting the same JSON-as-string into every client's env. Use a path relative to the project root (e.g. ./swagger-sources.json) — it resolves from process.cwd(), which is the project root under project-scoped configs in Claude Code, Cursor, opencode, etc. — so the MCP config can be committed and shared as-is.

swagger-sources.json (each entry is a <SOURCE> URL as defined above):

[
  "<SOURCE_1>",
  "<SOURCE_2>"
]

Each client config then becomes a thin wrapper around the same command:

Claude Code:

claude mcp add swagger --scope project -- npx -y internal-swagger-mcp --sources-file ./swagger-sources.json

opencode (opencode.json):

{
  "mcp": {
    "swagger": {
      "type": "local",
      "command": ["npx", "-y", "internal-swagger-mcp", "--sources-file", "./swagger-sources.json"]
    }
  }
}

Cursor (.cursor/mcp.json) — and other clients using the mcpServers shape:

{
  "mcpServers": {
    "swagger": {
      "command": "npx",
      "args": ["-y", "internal-swagger-mcp", "--sources-file", "./swagger-sources.json"]
    }
  }
}

The file is read once at startup; the source list is fixed for the server's lifetime (clients relaunch on config change anyway). When both --sources-file and SWAGGER_SOURCES are provided, the file wins. The flag is rejected in --http mode because HTTP sources are inherently per-request.

HTTP deployment security

The server binds to 0.0.0.0 by default for easy intranet sharing, and prints a warning if started bare. In production, set at least one of the following:

| Environment variable | Effect | |------|--------| | MCP_BIND_HOST | Bind address; set to 127.0.0.1 to restrict access to the local host (default 0.0.0.0) | | MCP_BEARER_TOKEN | Require an Authorization: Bearer <token> header on every request | | MCP_ALLOWED_ORIGINS | Comma-separated Origin allowlist (DNS-rebinding protection) |

When MCP_ALLOWED_ORIGINS is set, requests without an Origin header are rejected — except for requests carrying a valid MCP_BEARER_TOKEN, so server-to-server calls still work.