Provides progressive-disclosure Markdown access to OpenAPI/Swagger API specifications, allowing AI agents to list endpoints, inspect endpoint details, retrieve schemas, and batch-select related operations.
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., "@openapi-md-mcp List endpoints under /v1/scoring"
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.
An MCP server that exposes OpenAPI specs to markdown with progressive disclosure.
Swagger UI (/docs) is a JS shell; AI can't scrape its content
The full /openapi.json is often tens of thousands of tokens—too expensive to stuff into context
This tool keeps the AI's resident context to just an endpoint table of "key + summary" (~1k tokens), drilling down by key to fetch single-endpoint / single-schema markdown details—measured to save ~90% of context
Related MCP server: OpenAPI MCP Server
tool | input | output |
|
| Endpoint table |
|
| Endpoint details: auth, parameter table, request body ( |
|
| Schema property table + nested |
|
| Batch selection: endpoint key table with auth column + matching schema names (horizontal aggregation, e.g. "all authenticated endpoints") |
|
| Batch drill-down: mixed keys fetch all details at once, referenced schemas auto-merged into a deduplicated appendix |
Drill-down key = METHOD /path or schema name, obtained directly from the output of the layer above.
Single-key drill-down can't answer horizontal questions ("all authenticated endpoints" would require dozens of individual get_endpoint calls), so the batch layer fills the gap:
select(patterns=["GET /v1/auth/*", "* /v1/scoring/*"], security="X-Service-Token", tag="scoring", schema_glob="Credit*")
patterns elements look like "METHOD /path/glob": method can be * (case-insensitive); path glob is case-sensitive
security is a scheme name; patterns are OR'd together, and AND'd with security/tag
Zero matches return success text (available schemes / tags + relaxation suggestions), not an error
get_batch(["POST /v1/scoring/credit", "CreditBatchRequest"])
Keys deduplicated preserving order, cap of 40; total rendered character cap of 100k, beyond which include_refs=False or batching is suggested
include_refs=True auto-merges $refs referenced during rendering into a "shared schema appendix" (each name rendered only once)
variable | default | description |
|
| Runtime spec (preferred). Can be set directly to the |
| empty | Fallback spec file path (used when the runtime URL is unreachable) |
|
| Fetch timeout (seconds) |
Spec supports JSON and YAML; cached in-process for 60s after loading
Requests are direct (trust_env=False): the target is a localhost / intranet spec, so system proxy is bypassed (macOS system proxy hijacks localhost into a 502)
Read-only, no API-calling capability (auth headers never enter the MCP layer)
Claude Code user-level registration (register once, available in all repositories):
claude mcp add openapi-md -s user -- \
uv run --directory /path/to/openapi-md-mcp openapi-md-mcpRepositories needing a different data source can override env in their project-level .mcp.json.
Tool names / descriptions / inputSchema conform to spec §Tools (name character set and length, deterministic tools/list ordering)
All five tools declare annotations.readOnlyHint: true (read-only)
Error semantics follow spec §Tools Error Handling: spec load failure, unknown keys (with near-match suggestions), invalid filter patterns, and batch over-limit are thrown as ToolError for Tool Execution Error → surfaced online as CallToolResult(isError=true), and the client feeds suggestions back to the model for self-correction; zero matches are success text; no call (API invocation) capability
Version negotiation: stdio uses the initialize handshake epoch (highest 2025-11-25); the stateless envelope epoch of 2026-07-28 is handled by the SDK at the HTTP transport layer (server/discover), not applicable to the stdio scenario
uv sync # 安装依赖
uv run pytest --cov=openapi_md_mcp # 测试（fixture 为真实 OpenAPI 3.1 快照）批量获取端点详情与 schema 属性表，引用的 schema 自动整合为共享附录（去重）。keys 混合 "METHOD /path" 端点键与 schema 名（去重后 ≤40 个）；键从 list_endpoints / select 获得。
Inputs: keys (required), include_refs. Returns: result
获取单个端点的 markdown 详情（鉴权、参数、请求体、响应）。method 大小写不敏感；键从 list_endpoints 获得。
Inputs: path (required), method (required). Returns: result
获取单个 schema 的属性表与嵌套下钻键。schema 名从 get_endpoint 输出的 → get_schema(Name) 获得。
Inputs: name (required). Returns: result
列出 API 全部端点（方法/路径/摘要表）。了解 API 全貌的第一步；需要细节时用 get_endpoint / get_schema 按键下钻。
Inputs: tag. Returns: result
按 glob 模式与鉴权 / tag 过滤批量选中端点键与 schema 名（含鉴权列的键表）。patterns 元素形如 "GET /v1/*"（方法可为 *、大小写不敏感）；零匹配返回可用条件提示。选中后用 get_batch 批量取详情。
Inputs: tag, patterns, security, schema_glob. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 5 tools
Each tool is clearly anchored to a distinct stage of the workflow: overview, single endpoint details, single schema details, bulk selection, and bulk retrieval. There is no meaningful overlap between the five operations.
The names mostly follow a clear verb_noun pattern, with list_endpoints for the collection and get_endpoint / get_schema for individual items. The bare 'select' and the somewhat generic 'get_batch' are minor deviations from the otherwise consistent style.
Five tools form a tight, well-scoped set for navigating OpenAPI documents: overview, detail, schema access, filtering, and batch retrieval. Each tool has a clear purpose and none feel redundant.
The main exploration workflow is complete: list endpoints, inspect endpoint and schema details, filter selections, and batch fetch. A dedicated way to enumerate all schemas up front would be a minor improvement, but the select/get_batch flow provides a workable path.
Same functionality, consuming only 1/20 of the context window tokens.
Provide your AI coding tools with token-efficient access to up-to-date technical documentation for…
Polished system design diagrams (SVG/PNG) from a tiny YAML spec, ~18x fewer tokens than raw SVG.
Free no-LLM token savers: URL→Markdown, outline, JSON trim, log compress, token count; x402 extras