OpenAPI Schema

What is mcp-openapi-schema?

mcp-openapi-schema is a Model Context Protocol (MCP) server designed to facilitate the interaction between Large Language Models (LLMs) like Claude and OpenAPI specifications. It allows LLMs to explore and understand complex OpenAPI schemas without overwhelming their context window, providing a structured way to access API documentation.

How to use mcp-openapi-schema?

mcp-openapi-schema can be used via the command line, integrated with Claude Desktop, or configured with Claude Code CLI.

Command Line Usage

Run the server with a specified OpenAPI schema file:

npx -y mcp-openapi-schema # Uses default openapi.yaml
npx -y mcp-openapi-schema ../petstore.json # Uses a relative path
npx -y mcp-openapi-schema /absolute/path/to/api-spec.yaml # Uses an absolute path

Claude Desktop Integration

Add the following to your claude_desktop_config.json file:

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

Claude Code Integration

1. Add the server:

   claude mcp add openapi-schema npx -y mcp-openapi-schema
   claude mcp add petstore-api npx -y mcp-openapi-schema ~/Projects/petstore.yaml
   

2. Verify:

   claude mcp list
   claude mcp get openapi-schema
   

3. Remove (if needed):

   claude mcp remove openapi-schema
   

4. Use: Ask questions about the OpenAPI schema in your Claude Code session.

Key Features of mcp-openapi-schema

• Schema Loading: Loads OpenAPI schema files (JSON or YAML).
• API Exploration: Allows exploration of API paths, operations, parameters, and schemas.
• Detailed Views: Provides detailed request and response schemas.
• Component Lookup: Enables lookup of component definitions and examples.
• Schema Search: Supports searching across the entire API specification.
• YAML Output: Responses are provided in YAML format for better LLM comprehension.
• MCP Tools: Offers a suite of tools for LLMs to interact with OpenAPI schemas, including:
  • list-endpoints: Lists all API paths and HTTP methods.
  • get-endpoint: Gets detailed information about a specific endpoint.
  • get-request-body: Gets the request body schema.
  • get-response-schema: Gets the response schema.
  • get-path-parameters: Gets parameters for a specific path.
  • list-components: Lists all schema components.
  • get-component: Gets detailed definition for a specific component.
  • list-security-schemes: Lists available security schemes.
  • get-examples: Gets examples for components or endpoints.
  • search-schema: Searches across paths, operations, and schemas.

Use Cases of mcp-openapi-schema

• LLM-powered API Documentation: Enables LLMs to understand and answer questions about complex APIs without needing to be trained on the entire schema.
• Automated API Interaction: Facilitates the creation of LLM agents that can intelligently interact with APIs based on their OpenAPI specifications.
• Developer Productivity: Helps developers quickly find information within large API schemas using natural language queries.
• API Testing and Validation: Can be used by LLMs to generate test cases or validate API interactions based on the schema.

FAQ about mcp-openapi-schema

Q: What is the Model Context Protocol (MCP)? A: The Model Context Protocol is a mechanism that allows LLMs to interact with external tools and data sources, extending their capabilities beyond their initial training data.

Q: What types of OpenAPI schema files are supported? A: Both JSON and YAML OpenAPI schema files are supported.

Q: Can I use this with other LLMs besides Claude? A: While the examples focus on Claude, the underlying MCP concept is designed to be general. If another LLM supports the MCP, it should theoretically be compatible.

Q: How do I specify which OpenAPI schema file to use? A: You can specify the schema file via a command-line argument when running the server, or within the configuration files for Claude Desktop or Claude Code.

Q: What kind of questions can I ask the LLM about the API schema? A: You can ask questions like "What endpoints are available?", "Show me the details for the POST /pets endpoint", "What parameters does the GET /pets/{petId} endpoint take?", "What is the request body schema for creating a new pet?", or "Search for anything related to "user" in this API."

OpenAPI Schema Model Context Protocol Server

A Model Context Protocol (MCP) server that exposes OpenAPI schema information to Large Language Models (LLMs) like Claude. This server allows an LLM to explore and understand OpenAPI specifications through a set of specialized tools.

Features

• Load any OpenAPI schema file (JSON or YAML) specified via command line argument
• Explore API paths, operations, parameters, and schemas
• View detailed request and response schemas
• Look up component definitions and examples
• Search across the entire API specification
• Get responses in YAML format for better LLM comprehension

Usage

Command Line

Run the MCP server with a specific schema file:

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

# Use a specific schema file (relative path)
npx -y mcp-openapi-schema ../petstore.json

# Use a specific schema file (absolute path)
npx -y mcp-openapi-schema /absolute/path/to/api-spec.yaml

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

Claude Desktop Integration

To use this MCP server with Claude Desktop, edit your claude_desktop_config.json configuration file:

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

Location of the configuration file:

• macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: $env:AppData\Claude\claude_desktop_config.json

Claude Code Integration

To use this MCP server with Claude Code CLI, follow these steps:

1. Add the OpenAPI Schema MCP server to Claude Code

   # Basic syntax
   claude mcp add openapi-schema npx -y mcp-openapi-schema
   
   # Example with specific schema
   claude mcp add petstore-api npx -y mcp-openapi-schema ~/Projects/petstore.yaml
   

2. Verify the MCP server is registered

   # List all configured servers
   claude mcp list
   
   # Get details for your OpenAPI schema server
   claude mcp get openapi-schema
   

3. Remove the server if needed

   claude mcp remove openapi-schema
   

4. Use the tool in Claude Code

   Once configured, you can invoke the tool in your Claude Code session by asking questions about the OpenAPI schema.

Tips:

• Use the -s or --scope flag with project (default) or global to specify where the configuration is stored
• Add multiple MCP servers for different APIs with different names

MCP Tools

The server provides the following tools for LLMs to interact with OpenAPI schemas:

• list-endpoints: Lists all API paths and their HTTP methods with summaries in a nested object structure
• get-endpoint: Gets detailed information about a specific endpoint including parameters and responses
• get-request-body: Gets the request body schema for a specific endpoint and method
• get-response-schema: Gets the response schema for a specific endpoint, method, and status code
• get-path-parameters: Gets the parameters for a specific path
• list-components: Lists all schema components (schemas, responses, parameters, etc.)
• get-component: Gets detailed definition for a specific component
• list-security-schemes: Lists all available security schemes
• get-examples: Gets examples for a specific component or endpoint
• search-schema: Searches across paths, operations, and schemas

Examples

Example queries to try:

What endpoints are available in this API?
Show me the details for the POST /pets endpoint.
What parameters does the GET /pets/{petId} endpoint take?
What is the request body schema for creating a new pet?
What response will I get from the DELETE /pets/{petId} endpoint?
What schemas are defined in this API?
Show me the definition of the Pet schema.
What are the available security schemes for this API?
Are there any example responses for getting a pet by ID?
Search for anything related to "user" in this API.