Overview

This MCP (Model Context Protocol) server exposes an OpenAPI specification to Large Language Models so they can inspect, query, and reason about an API’s structure. Instead of pasting an entire spec into a prompt, an LLM can call curated tools that return paths, operations, parameter definitions, request/response schemas, examples, and component definitions. The server reads standard OpenAPI files (JSON or YAML) and serves them in LLM-friendly formats (YAML responses by default) for predictable parsing and comprehension.

This is useful when you want a conversational agent (e.g., Claude) to explore an API, generate integration code, validate requests/responses, or answer developer questions about endpoints without needing the model to memorize or ingest a raw spec. The project repository is available at https://github.com/hannesj/mcp-openapi-schema.

Features

Load any OpenAPI/Swagger file (JSON or YAML) specified at startup
Explore API paths, HTTP methods, summaries and descriptions
Inspect parameters, request bodies, and response schemas in detail
Look up components (schemas, parameters, responses, examples)
Search across paths, operations, and schemas for keywords
Return structured YAML outputs optimized for LLM consumption
Integrates with Claude Desktop and Claude Code via MCP registration

Installation / Configuration

Run the server with npx (no global install required). Pass the path to your OpenAPI file (absolute or relative):

# Use default openapi.yaml in current directory
npx -y mcp-openapi-schema

# Use a relative path to a spec
npx -y mcp-openapi-schema ../petstore.json

# Use an absolute path
npx -y mcp-openapi-schema /absolute/path/to/openapi.yaml

# Show CLI help
npx -y mcp-openapi-schema --help

Integrate with Claude Desktop by editing the local config to register the MCP server. Example entry for claude_desktop_config.json:

{
  "mcpServers": {
    "OpenAPI Schema": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-schema", "/ABSOLUTE/PATH/TO/openapi.yaml"]
    }
  }
}

Typical locations for the config file:

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %AppData%\Claude\claude_desktop_config.json

For Claude Code CLI, add and manage the MCP server:

# Add a server (project or global scope)
claude mcp add openapi-schema npx -y mcp-openapi-schema ~/Projects/petstore.yaml

# List registered servers
claude mcp list

# Inspect a registered server
claude mcp get openapi-schema

# Remove a server
claude mcp remove openapi-schema

Tip: use absolute paths for reliability when launching from different environments. Use the –scope flag with claude mcp to choose project vs. global configuration.

Available Tools

The server exposes a set of MCP tools (methods) that LLMs can call. Each returns structured YAML or JSON for ease of parsing.

Tool name	Purpose
list-endpoints	Enumerates all paths and HTTP methods with short summaries
get-endpoint	Detailed info for a specific path + method (parameters, request body, responses)
get-request-body	Returns the request body schema for a given endpoint and method
get-response-schema	Returns the response schema for an endpoint, method, and status code
get-path-parameters	Lists path-level parameters for a given path
list-components	Lists component types (schemas, parameters, responses, examples, etc.)
get-component	Returns definition for a specific component (e.g., #/components/schemas/Pet)
list-security-schemes	Lists defined security schemes and their types
get-examples	Fetches example payloads for a component or endpoint
search-schema	Full-text search across paths, operations, descriptions and component definitions

Example output format (YAML) is chosen to reduce tokenization ambiguity for LLMs.

Use Cases

Discover API surface: Ask “What endpoints are available?” and get a structured list of paths and methods suitable for follow-up questions or code generation.
Generate request code: Use get-request-body + get-response-schema to produce typed request/response objects for client libraries.
Validate integration assumptions: Query “What parameters does GET /pets/{petId} accept?” and use the parameter schema to build correct URL and query strings.
Security review: List security schemes to determine required auth headers or OAuth flows before implementing calls.
Documentation extraction: Extract component schemas and examples for producing markdown docs or OpenAPI-based reference pages.
Focused search: Use search-schema to find all occurrences of “user” or a particular model name across the spec to inform breaking-change assessments.

Concrete prompt examples for an LLM after registering the MCP:

“List all endpoints grouped by tag.”
“Show me the POST /pets request body schema.”
“What are the possible responses for DELETE /pets/{petId}?”
“Find all schemas that reference ‘User’.”

Troubleshooting & Tips

Ensure the OpenAPI file is valid JSON/YAML. The server will error on malformed specs.
Prefer absolute paths when registering MCP servers to avoid working-directory issues.
If responses appear verbose, request a specific tool (e.g., get-response-schema) to get targeted output suitable for downstream code generation.

This MCP server provides a compact, tool-driven interface between LLMs and OpenAPI specs, enabling safer, more accurate API reasoning and automation.

OpenAPI Schema MCP Server for LLMs