Provides tools for loading, listing, searching, and exploring endpoints of OpenAPI/Swagger specifications.
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., "@Spectacle Load the spec at ./openapi.yaml and list all endpoints"
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 lets Claude (and other MCP clients) query, search, and explore OpenAPI specifications. Point it at a spec file and ask questions about endpoints, parameters, schemas, and more.
Supports OpenAPI 3.x (JSON/YAML) and Swagger 2.0 (auto-converted).
Tool | Description |
| Load an OpenAPI/Swagger spec from a local file path |
| List all endpoints, optionally filtered by HTTP method or tag |
| Get detailed info about a specific endpoint (brief/normal/full verbosity) |
| Full-text search across endpoints with relevance ranking |
Related MCP server: openapi-mcp-proxy
Node.js 18+
pnpm
git clone https://github.com/your-username/spectacle-mcp.git
cd spectacle-mcp
pnpm installAdd to your project's .mcp.json:
{
"mcpServers": {
"spectacle": {
"command": "pnpm",
"args": ["tsx", "/absolute/path/to/spectacle-mcp/src/index.ts"],
}
}
}Once configured, Claude can use the tools directly. Some example prompts:
"Load the spec at ./openapi.yaml and list all endpoints"
"What parameters does POST /users accept?"
"Search the API for anything related to authentication"
"Show me the full details of GET /orders/{id} including response schemas"
spec_load — Load and cache a spec. Swagger 2.0 files are automatically converted to OpenAPI 3.x. Specs are cached in memory and reloaded when the file changes.
list_endpoints — Two output formats:
compact — one line per endpoint (GET /pets)
grouped — organized by tag with summaries
get_endpoint — Three verbosity levels:
brief — method, path, summary
normal — adds parameters, request body, response codes
full — adds complete expanded schemas
search_endpoints — Keyword search with AND semantics (all terms must match). Results are ranked by relevance with weighted field scoring (path > operationId > summary > tags > parameters > description). Three return formats: snippets, ids, or full.
pnpm start # Run the MCP server
pnpm dev # Run with file watching (auto-restart on changes)pnpm tsx test/smoke.ts # Integration tests
pnpm tsx test/swagger2-test.ts # Swagger 2.0 conversion testssrc/
index.ts — MCP server setup and tool registration
spec.ts — Spec loading, caching, $ref resolution, and indexing
format.ts — Output formatting and search scoring
test/
petstore.yaml — OpenAPI 3.0 test fixture
swagger2.json — Swagger 2.0 test fixture
smoke.ts — Integration tests
swagger2-test.ts — Conversion testsGet detailed information about a specific API endpoint.
Inputs: path (required), method (required), spec_path (required), verbosity.
List all API endpoints in a loaded spec. Filter by method or tag.
Inputs: spec_path (required), tag, format, method.
Search API endpoints by keyword. AND semantics — all terms must match.
Inputs: q (required), spec_path (required), limit, return.
Load an OpenAPI spec from a local file path. Converts Swagger 2.0 automatically.
Inputs: spec_path (required), force_reload.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 4 tools
Each tool has a distinct primary purpose: load a spec, list all endpoints, get one endpoint, or search endpoints. The only possible confusion is between list_endpoints and search_endpoints, but the filtering vs. keyword-search distinction is clear enough.
Most tools follow a clear verb_noun pattern: list_endpoints, get_endpoint, search_endpoints. spec_load is a minor deviation—load_spec would be more consistent—but overall the naming is readable and predictable.
Four tools is a well-scoped size for an OpenAPI inspection server. Each tool is non-redundant and covers a necessary part of the workflow without bloat.
The toolset covers the core inspection lifecycle: load a spec, list endpoints, get details, and search. There are minor gaps like retrieving spec metadata or listing tags, but the primary use cases are fully supported and there are no dead ends.
MCP server for AI access to Swagger by SmartBear.
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
