Quick Start

This guide will help you quickly get up and running with openapi-mcp, from basic setup to your first API interactions.

Prerequisites

Before starting, ensure you have:

  • Built the openapi-mcp binaries (see Installation)
  • An OpenAPI 3.x YAML or JSON specification file

Sample OpenAPI Spec

If you don't have an OpenAPI spec handy, you can use the included example: 

examples/fastly-openapi-mcp.yaml

Step 1: Start the MCP Server

The simplest way to run openapi-mcp is in stdio mode with your OpenAPI spec: 

bin/openapi-mcp examples/fastly-openapi-mcp.yaml

This loads the OpenAPI spec, validates it, generates MCP tools for each operation, and starts an MCP server that communicates over stdin/stdout.

If your API requires authentication, you can provide it via command-line flags or environment variables: 

# Using API key
API_KEY=your_api_key bin/openapi-mcp examples/fastly-openapi-mcp.yaml

# Using Bearer token
BEARER_TOKEN=your_token bin/openapi-mcp examples/fastly-openapi-mcp.yaml

To run as an HTTP server instead of stdio mode: 

bin/openapi-mcp --http=:8080 examples/fastly-openapi-mcp.yaml

HTTP Mode Authentication

When using HTTP mode, you can provide authentication via HTTP headers in your requests: 

# Example with API key header
curl -H "X-API-Key: your_key" http://localhost:8080/mcp -d '...'

# Example with Bearer token  
curl -H "Authorization: Bearer your_token" http://localhost:8080/mcp -d '...'

Step 2: Use the Interactive Client

The mcp-client is an interactive client that allows you to explore the available MCP tools and make calls: 

bin/mcp-client bin/openapi-mcp examples/fastly-openapi-mcp.yaml

If you're running in HTTP mode, connect to the HTTP endpoint: 

bin/mcp-client http://localhost:8080

Step 3: Explore Available Tools

Once in the client, you can list all available tools: 

mcp> list

This will display all the operations from your OpenAPI spec that have been converted to MCP tools.

Step 4: View Tool Schema

To see the schema for a specific tool, use the schema command: 

mcp> schema createService

This shows the expected input parameters, including data types, descriptions, and whether they're required.

Step 5: Call a Tool

To call a tool, use the call command with JSON arguments: 

mcp> call createService {"name": "My Service", "type": "vcl"}

The client will make the API call and display the response.

Step 6: Handle Confirmation for Dangerous Operations

For dangerous operations (PUT, POST, DELETE), openapi-mcp requires confirmation: 

mcp> call deleteService {"service_id": "SU1Z0isxPaozGVKXdv0eY"}

{
  "type": "confirmation_request",
  "confirmation_required": true,
  "message": "This action is irreversible. Proceed?",
  "action": "delete_resource"
}

To proceed, retry with the __confirmed parameter: 

mcp> call deleteService {"service_id": "SU1Z0isxPaozGVKXdv0eY", "__confirmed": true}

Step 7: Get Complete API Documentation

To get complete documentation for all available tools, use the describe tool: 

mcp> call describe

This returns comprehensive information about all available tools, including schemas, examples, and descriptions.

Serving Multiple APIs (Multi-Mount)

You can serve multiple OpenAPI specs at different base paths using the --mount flag in HTTP mode: 

openapi-mcp --http=:8080 --mount /petstore:petstore.yaml --mount /books:books.yaml

By default, this will serve the Petstore API at /petstore (StreamableHTTP), and the Books API at /books. If you use --http-transport=sse, endpoints like /petstore/sse and /petstore/message will be available for SSE clients.

Next Steps

Now that you've got the basics down, here are some next steps: