Skip to main content
Glama
internal-swagger-mcp

internal-swagger-mcp

by zhangwanli09

internal-swagger-mcp

npm license

English | 简体中文

Let AI agents search and read your internal Swagger platform's API docs via MCP.

NOTE

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

Implements MCP 2026-07-28 and still serves 2025-era clients, over both stdio and stateless HTTP (no sticky sessions needed). Requires Node.js ≥ 22.

Tools

Tool

Purpose

swagger_list_sources

List configured services and their cache status

swagger_search_api

Search APIs by keyword, optionally filtered by method / service

swagger_get_api_detail

Show an API's full parameters and mock example

swagger_refresh_cache

Force-refresh the doc cache (default TTL: 30 minutes)

Related MCP server: mcp-swagger

Sources

The server holds no configuration; each client supplies a list of Swagger share links (<SOURCE> below), which look like http://your-server/...#/swaggerManage?uid=xxx.

For local (stdio) mode, put them in swagger-sources.json at the project root and commit it:

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

A relative --sources-file path resolves against the MCP server process's working directory. The relative paths below assume the client starts the server from the project root. Use an absolute path if your client starts it elsewhere. The server re-reads the file on every tool call. You can also omit --sources-file and set SWAGGER_SOURCES in the server process's environment to the same JSON array.

For remote (HTTP) mode, send the JSON array in the X-Swagger-Sources header on every POST /mcp, including legacy clients' initialize requests.

Connecting MCP clients

Use project scope so each repo pins its own sources. Once connected, swagger_list_sources should list your services.

For remote mode, start the server on a shared host first (see Security):

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

Claude Code

--scope project writes to .mcp.json. Replace <internal-IP> and <SOURCE> with your server address and Swagger share link. See the Claude Code docs.

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

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

Codex

Add one of the following configurations to .codex/config.toml in your project root. Codex loads this file for trusted projects. See the Codex MCP docs.

Local (stdio)

Replace /absolute/path/to/swagger-sources.json with the path to your project's sources file.

[mcp_servers.swagger]
command = "npx"
args = ["-y", "internal-swagger-mcp", "--sources-file", "/absolute/path/to/swagger-sources.json"]

Remote (Streamable HTTP)

Replace <mcp-host> and <SOURCE> with your MCP endpoint's hostname and Swagger share link. If the server requires a bearer token, you must use an https:// endpoint. For example, you can put a TLS-terminating reverse proxy in front of the HTTP server. Then uncomment bearer_token_env_var and set SWAGGER_MCP_TOKEN in the environment that launches Codex.

[mcp_servers.swagger]
url = "https://<mcp-host>/mcp"
http_headers = { "X-Swagger-Sources" = '["<SOURCE>"]' }
# bearer_token_env_var = "SWAGGER_MCP_TOKEN"

Start a new Codex session, use /mcp to check that swagger is connected, then ask Codex to run swagger_list_sources.

OpenCode

In opencode.json, OpenCode v2 uses mcp.servers.swagger as shown below. For v1, put swagger directly under mcp. For remote mode, replace the local entry with "type": "remote", url, and headers. See the OpenCode docs.

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

Cursor and other mcpServers clients

In Cursor, put this in .cursor/mcp.json. For other clients using mcpServers, use an absolute path if they lack Cursor's ${workspaceFolder} variable. See the Cursor docs.

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

Remote: replace the entry with { "url": "http://<internal-IP>:3000/mcp", "headers": { "X-Swagger-Sources": "[\"<SOURCE>\"]" } }.

HTTP deployment security

The server binds to 0.0.0.0 by default. It warns at startup when it binds to 0.0.0.0 and both the bearer token and Origin allowlist are empty.

Environment variable

Effect

MCP_BIND_HOST

Bind address, e.g. 127.0.0.1 for local-only

MCP_BEARER_TOKEN

Require Authorization: Bearer <token> on all /mcp requests (add it to the client's headers)

MCP_ALLOWED_ORIGINS

Comma-separated Origin allowlist for /mcp. With the allowlist enabled, clients that omit Origin must authenticate with a configured bearer token. If you set both variables, every client needs the token.

License

MIT

Available Tools

4 tools
swagger_get_api_detailGet Swagger API DetailA
Read-onlyIdempotent

Get full details of a single API interface, including all parameter definitions and response examples.

Parameters:

  • source (required): Service name, from the [service name] returned by swagger_list_sources or swagger_search_api.

  • method (required): HTTP method, e.g. "GET", "POST".

  • path (required): Full interface path, e.g. "/qmAuthorityCenter/systemFun/initPerformanceSolution".

Response includes:

  • Basic interface info (name, description, status, Content-Type).

  • Full definitions for Query / Path / Header / Form / Body parameters (name, type, required, description). Required column: "是" = required, "否" = optional, "?" = platform metadata is ambiguous (checkType=1 with no error message — cross-check with backend code or treat as optional).

  • Sub-fields of nested Object parameters.

  • Response results (Demo JSON + output field table).

  • Mock response field table.

Inputs: path (required), method (required), source (required). Returns: name, path, method, status, +8 more

swagger_list_sourcesList Swagger SourcesA
Read-onlyIdempotent

List all configured Swagger documentation sources and their cache status.

For each service, returns:

  • name: Service name (from config, or auto-read from projectName).

  • fetchedAt: Last cache time (null means not yet loaded).

  • totalInterfaces: Total interface count (shown when loaded).

  • modules: Module list.

Use this before calling swagger_search_api to discover which services are available.

Inputs: no named parameters. Returns: sources

swagger_refresh_cacheRefresh Swagger CacheA
Idempotent

Force-refetch Swagger documentation data and update the cache.

Use this after the documentation has been updated (interfaces added or modified) to fetch the latest data.

Parameters:

  • source (optional): Service name. Omit to refresh all services.

Returns: Refresh results, including success/failure status and updated interface counts.

Inputs: source. Returns: failed, refreshed

swagger_search_apiSearch Swagger APIA
Read-only

Search API interfaces in the internal Swagger documentation.

Searches by keyword across interface name, description, path, and module name. Optionally filter by HTTP method and service.

Parameters:

  • keyword (required): Search keyword, e.g. "登录", "user", "/api/order". Chinese is supported.

  • method (optional): HTTP method filter, e.g. "GET", "POST".

  • source (optional): Service name filter, taken from swagger_list_sources results.

  • include_deprecated (optional): Whether to include deprecated interfaces. Default false.

  • limit (optional): Maximum number of results. Default 20.

Response: Each matched interface includes: service name, module name, HTTP method, full path, interface name, description, status.

Examples:

  • Search login interfaces: keyword="登录"

  • Search POST interfaces: keyword="用户", method="POST"

  • Search within a specific service: keyword="order", source="订单服务"

Inputs: keyword (required), limit, method, source, +1 more. Returns: total, failed, keyword, results, +1 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a distinct stage of the Swagger documentation workflow: listing sources, searching APIs, retrieving interface detail, and refreshing the cache. There is no meaningful overlap; descriptions and required parameters make the intended use of each tool clear.

    Naming Consistency5/5

    All tools follow a consistent swagger_<verb>_<noun> pattern: swagger_list_sources, swagger_search_api, swagger_get_api_detail, swagger_refresh_cache. The convention is predictable and immediately readable.

    Tool Count5/5

    Four tools is a tight, well-scoped surface for a Swagger documentation server. Each tool earns its place by covering a necessary step in the discovery-to-detail workflow, with no obvious redundancy.

    Completeness4/5

    The set covers source discovery, keyword search, detailed interface lookup, and cache refresh, which handles the core read workflow. Minor gaps exist, such as browsing all interfaces without a keyword or listing modules/interfaces directly, but agents can work around these via search.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides LLM-agnostic access to API documentation through MCP and REST endpoints, enabling AI assistants to retrieve, search, and proxy requests to whitelisted APIs across multiple platforms.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Exposes Swagger/OpenAPI API documentation to AI models, enabling exploration, search, and interaction with endpoints, schemas, and execution of API calls.
      14
      13 npm
      2
      MIT