internal-swagger-mcp
Lets AI agents discover, search, and read API documentation from an internal Swagger platform over MCP.
List configured Swagger services and their cache status.
Search API interfaces by keyword, with optional HTTP method, service, deprecated-inclusion, and result-limit filters.
Retrieve full API details: parameters (query/path/header/form/body), nested object fields, response demos/field tables, and mock response fields.
Force-refresh cached Swagger documentation for one service or all services.
Run over stdio or stateless HTTP; sources are supplied per client via sources file, environment variable, or
X-Swagger-Sourcesheader, with optional bearer-token and Origin allowlist security.
Allows AI agents to query internal Swagger platform API documentation, including listing services, searching APIs by keyword, viewing full parameters and mock examples, and refreshing the cache.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@internal-swagger-mcp search for endpoints related to user authentication"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
internal-swagger-mcp
English | 简体中文
Let AI agents search and read 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.
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 |
| List configured services and their cache status |
| Search APIs by keyword, optionally filtered by method / service |
| Show an API's full parameters and mock example |
| 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 PORTClaude 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 |
| Bind address, e.g. |
| Require |
| Comma-separated Origin allowlist for |
License
Available Tools
4 toolsswagger_get_api_detailGet Swagger API DetailARead-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 SourcesARead-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 CacheAIdempotent
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 APIARead-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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
AgentReady Tools is a searchable catalog of more than 250 APIs, MCP servers and developer tools that AI agents can use, each with agent-readiness checks (docs, auth, OpenAPI, MCP support). Search by task, get tool details and related tools, and read or share field notes from other agents in the Agent Community. Remote MCP endpoint: https://agentready-tools.com/mcp
Team docs served to AI agents over MCP - search, Markdown reads, version pinning, read audit.
Search and inspect source-pinned agent skills, plugins and tools through a free public MCP.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceProvides 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.-
- AlicenseAqualityDmaintenanceExposes Swagger/OpenAPI API documentation to AI models, enabling exploration, search, and interaction with endpoints, schemas, and execution of API calls.1413 npm2MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI agents to explore, search, and query API definitions from OpenAPI/Swagger JSON files.5 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnables agents to query real-time OpenAPI documentation of backend services, providing tools to list services, endpoints, and schemas via MCP.-