Explore any public OpenAPI spec — get overview, endpoints, and operation details via openapi-mcp-server (npx)
When an agent needs to understand or generate code against a REST API, the first step is reading its OpenAPI spec. This MCP server connects to oapis.org to fetch, summarize, and drill into OpenAPI specifications by known identifier (e.g. "openai", "stripe") or by URL. Two tools: getApiOverview (lists all endpoints grouped by tag) and getApiOperation (returns the full YAML schema for one endpoint). No API key needed.
Recipe: Explore any public OpenAPI spec via openapi-mcp-server
Server: npx -y openapi-mcp-server (stdio, no auth) Tools: 2 — getApiOverview, getApiOperation Verified: 2026-06-11, 2 runs (getApiOverview + getApiOperation on OpenAI spec)
What it does
Connects to oapis.org to fetch and summarize any public OpenAPI specification. Two-step workflow: get a human-readable overview of all endpoints, then drill into any specific operation for its full YAML schema.
Tool overview
| Tool | Input | Returns |
|---|---|---|
getApiOverview | id — known API identifier (e.g. "openai") or URL to raw OpenAPI file | Markdown overview: title, version, base URL, all endpoints grouped by tag with one-line descriptions |
getApiOperation | id + operationIdOrRoute (e.g. "createSpeech") | Full YAML schema for that endpoint: request body, parameters, response types, auth requirements |
Typical agent workflow
getApiOverview(id: "openai")→ see all 271 endpoints grouped by tag (Audio, Chat, Images, etc.)- Pick an operation:
getApiOperation(id: "openai", operationIdOrRoute: "createSpeech")→ full request/response schema in YAML - Use the schema to generate client code or validate parameters
Known API identifiers
The server description lists examples: openai, stripe, github, etc. — these are shorthand IDs from openapisearch.com. You can also pass a URL to a raw OpenAPI JSON/YAML file.
Gotchas
- The
idparameter MUST be a known oapis.org identifier or a direct URL to a raw spec file. Passing a domain like "stripe.com" or "petstore3.swagger.io" returns "No OpenAPI found." - The overview can be very large for APIs with 100+ endpoints — the OpenAI overview (271 endpoints) is 3,000+ characters.
- v2 is exploration-only: it does NOT execute API calls or handle authentication. It's designed for codegen and understanding, not runtime.
{ "server": "npx -y openapi-mcp-server", "transport": "stdio", "protocol_version": "2024-11-05", "tools_found": 2, "tool_names": ["getApiOverview", "getApiOperation"], "trace": [ { "step": "getApiOverview", "request": { "name": "getApiOverview", "arguments": { "id": "openai" } }, "response_excerpt": "# openai OpenAPI overview > Below is an overview of the openai openapi in simple language. This API contains 271 endpoints. OpenAI API v2.3.0 - https://api.openai.com ## Assistants - listAssistants: Returns a list of assistants. - createAssistant: Create an assistant... ## Audio - createSpeech: Generates audio from the input text. - createTranscription: Transcribes audio..." }, { "step": "getApiOperation", "request": { "name": "getApiOperation", "arguments": { "id": "openai", "operationIdOrRoute": "createSpeech" } }, "response_excerpt": "openapi: 3.1.0 info: title: OpenAI API version: 2.3.0 paths: /audio/speech: post: operationId: createSpeech tags: [Audio] summary: Generates audio from the input text. requestBody: content: application/json: schema: properties: model: {enum: [tts-1, tts-1-hd, gpt-4o-mini-tts]} input: {type: string, maxLength: 4096} voice: {enum: [alloy, ash, ballad, coral, echo, sage, shimmer, verse]} response_format: {enum: [mp3, opus, aac, flac, wav, pcm]} speed: {type: number, minimum: 0.25, maximum: 4.0}" } ], "failure_cases": [ { "input": { "id": "petstore3.swagger.io" }, "error": "API error: No OpenAPI found at petstore3.swagger.io", "note": "Domain names don't work — use oapis.org shorthand identifiers or direct URLs to raw spec files" } ] }