openapi-mcp Examples

1. Running openapi-mcp with a Sample OpenAPI Spec

This example shows how to run openapi-mcp with the included Fastly API example spec.

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

This starts an MCP server in stdio mode, exposing all operations from the Fastly API spec as MCP tools.

2. Using mcp-client to Interact with the Server

Connect to the running MCP server with the interactive client:

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

Example session:

mcp> list
["listServices", "createService", "getService", "updateService", "deleteService", ...]

mcp> schema createService
Schema for createService:
{
  "type": "object",
  "properties": {
    "name": {"type": "string", "description": "The name of the service."},
    "comment": {"type": "string", "description": "A freeform descriptive note."},
    "type": {"type": "string", "enum": ["vcl", "wasm"], "description": "The type of this service."}
  },
  "required": ["name", "type"]
}
Example: call createService {"name": "My Service", "type": "vcl"}

mcp> call createService {"name": "My Service", "type": "vcl"}
HTTP POST /service
Status: 200
Response:
{
  "id": "SU1Z0isxPaozGVKXdv0eY",
  "name": "My Service",
  "customer_id": "x4xCwxxJxGCx123Rx5xTx",
  "type": "vcl",
  "created_at": "2016-08-17T19:27:28+00:00",
  "updated_at": "2016-08-17T19:27:28+00:00"
}

3. Running as an HTTP Server

Instead of stdio mode, you can run openapi-mcp as an HTTP server:

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

This starts an HTTP server on port 8080. You can connect to it using any HTTP client or the MCP client:

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

4. Using Authentication

Many APIs require authentication. openapi-mcp supports multiple authentication methods:

API Key Authentication

# Using command-line flag
bin/openapi-mcp --api-key=your_api_key examples/fastly-openapi-mcp.yaml

# Using environment variable
API_KEY=your_api_key bin/openapi-mcp examples/fastly-openapi-mcp.yaml

Bearer Token Authentication

# Using command-line flag
bin/openapi-mcp --bearer-token=your_token examples/fastly-openapi-mcp.yaml

# Using environment variable
BEARER_TOKEN=your_token bin/openapi-mcp examples/fastly-openapi-mcp.yaml

Basic Authentication

# Using command-line flag
bin/openapi-mcp --basic-auth=username:password examples/fastly-openapi-mcp.yaml

# Using environment variable
BASIC_AUTH=username:password bin/openapi-mcp examples/fastly-openapi-mcp.yaml

5. Generating Documentation

Generate Markdown documentation for all tools:

bin/openapi-mcp --doc=tools.md examples/fastly-openapi-mcp.yaml

Generate HTML documentation:

bin/openapi-mcp --doc=tools.html --doc-format=html examples/fastly-openapi-mcp.yaml

6. Filtering Operations

Filter operations by tag:

bin/openapi-mcp --tag=admin examples/fastly-openapi-mcp.yaml

Filter operations by description (using regex):

bin/openapi-mcp --include-desc-regex="user|account" examples/fastly-openapi-mcp.yaml
bin/openapi-mcp --exclude-desc-regex="deprecated" examples/fastly-openapi-mcp.yaml

7. Using as a Library in Go Code

You can use openapi-mcp as a Go library in your own projects:

package main

import (
	"github.com/getkin/kin-openapi/openapi3"
	"github.com/jedisct1/openapi-mcp/pkg/openapi2mcp"
)

func main() {
	// Load OpenAPI spec
	doc, err := openapi2mcp.LoadOpenAPISpec("openapi.yaml")
	if err != nil {
		panic(err)
	}
	
	// Create MCP server
	srv := openapi2mcp.NewServer("myapi", doc.Info.Version, doc)
	
	// Serve over HTTP
	if err := openapi2mcp.ServeStreamableHTTP(srv, ":8080", "/mcp"); err != nil {
		panic(err)
	}
}

8. Handling Confirmation for Dangerous Operations

By default, openapi-mcp requires confirmation for any PUT, POST, or DELETE operation. Here's how the flow works:

First call:

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

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

Second call with confirmation:

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

// Response
{
  "type": "api_response",
  "data": {
    "status": "ok"
  },
  "metadata": {
    "status_code": 200
  }
}

To disable this confirmation mechanism:

bin/openapi-mcp --no-confirm-dangerous examples/fastly-openapi-mcp.yaml

9. Dry Run Mode

Preview the generated tool schemas without starting a server:

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

10. Summary Mode

Print a summary of the operations:

bin/openapi-mcp --summary --dry-run examples/fastly-openapi-mcp.yaml

Example output:

OpenAPI spec loaded and validated successfully.
Registered all OpenAPI operations as MCP tools.
Total tools: 28
Tags:
  Service: 5
  Version: 3
  Domain: 3
  Origin: 3
  Backend: 3
  CacheSettings: 3
  Purge: 5
  WAF: 3
  Stats: 2
  Metrics: 1

11. Post-Processing with External Commands

Process the generated schema JSON with an external command:

bin/openapi-mcp --doc=tools.md --post-hook-cmd='jq . | tee /tmp/filtered.json' examples/fastly-openapi-mcp.yaml