davidmoltin/openapi-mcp-context-server

MCP OpenAPI Server

Multi-client OpenAPI MCP server with OAuth2 support.

This code implements an MCP (Model Context Protocol) OpenAPI Server - a sophisticated middleware that converts OpenAPI specifications into MCP tools that can be used by AI assistants and other clients.

Core Functionality:

1. OpenAPI to MCP Translation

• Parses OpenAPI specifications from URLs
• Converts REST API endpoints into MCP tools
• Generates proper JSON schemas for tool parameters
• Caches parsed tools for performance

2. Dual Communication Interfaces

• WebSocket MCP Protocol: Real-time bidirectional communication with AI clients
• HTTP REST API: Management interface for adding/removing APIs and executing tools

3. Key Components

MCPServer struct manages:

• OpenAPI parser for spec processing
• WebSocket connections to MCP clients
• Tool cache with automatic refresh
• Workflow engine integration
• OAuth2 authentication manager

Client Management:

• Tracks connected WebSocket clients
• Handles authentication headers
• Automatic cleanup of inactive connections
• Session-based tool execution

Tool Execution Engine:

• Finds tools by name in the cache
• Builds HTTP requests from tool parameters
• Handles path/query/body parameter mapping
• Formats responses with error handling
• Supports all HTTP methods (GET, POST, PUT, DELETE, etc.)

4. MCP Protocol Implementation

Handles standard MCP methods:

• initialize - Client handshake and capability negotiation
• tools/list - Returns available tools from OpenAPI specs
• tools/call - Executes API calls through the tool system
• ping - Connection keepalive

5. Management API Endpoints

• POST /openapi/add - Dynamically add new OpenAPI sources
• DELETE /openapi/remove - Remove API sources
• GET /tools - List all available tools
• GET /health - Server status and metrics
• POST /sessions/{id}/execute - Direct tool execution

6. Advanced Features

• Automatic caching with TTL and background refresh
• Background cleanup of inactive clients
• Dynamic API loading without server restart
• Session isolation for multi-tenant usage
• Workflow engine integration for complex operations

Use Case:

This server acts as a bridge, allowing AI assistants to interact with any REST API by simply providing its OpenAPI specification. The AI can then call these APIs as if they were native tools, enabling integration with thousands of existing web services without custom code.

For example: Add a Stripe API spec → AI can now process payments, add a GitHub API spec → AI can manage repositories, etc.

Quick Start

# Install dependencies
go mod tidy

# Build
make build

# Run
make run

# Test
make test-health

Configuration

Edit configs/default.yaml for server settings.

Configuration Priority

The server supports flexible base URL configuration with the following priority:

1. Claude Desktop api_url (highest priority)
2. Server YAML base_url (fallback)

Claude Desktop Config

Option 1: Direct MCP Tool (Recommended) 🎯

{
  "mcpServers": {
    "elastic-path-openapi": {
      "command": "/Users/davidjstover/mcp-openapi-server/bin/mcp-server",
      "args": ["-stdio", "-config", "/Users/davidjstover/mcp-openapi-server/configs/default.yaml"],
      "env": {
        "ELASTIC_PATH_CLIENT_ID": "your-client-id-here",
        "ELASTIC_PATH_CLIENT_SECRET": "your-client-secret-here",
        "ELASTIC_PATH_BASE_URL": "https://useast.api.elasticpath.com",
        "ELASTIC_PATH_GRANT_TYPE": "client_credentials",
        "ELASTIC_PATH_SCOPE": ""
      }
    }
  }
}

Setup Steps for Option 1:

1. Build the MCP server: make build
2. Replace the paths above with your actual project location
3. Replace the Elastic Path credentials with your actual values
4. Add this config to your Claude Desktop settings
5. Restart Claude Desktop

Option 2: WebSocket Server (For Development/Testing)

{
  "mcpServers": {
    "elastic-path-websocket": {
      "command": "node",
      "args": ["-e", "const WebSocket = require('ws'); const ws = new WebSocket('ws://localhost:8080/mcp'); ws.on('open', () => console.log('Connected')); ws.on('message', (data) => process.stdout.write(data)); process.stdin.on('data', (data) => ws.send(data));"]
    }
  }
}

Setup Steps for Option 2:

1. Start the server: make run (runs on localhost:8080)
2. Add the WebSocket bridge config above to Claude Desktop
3. Restart Claude Desktop

Environment Variable Options:

• ELASTIC_PATH_CLIENT_ID: Your OAuth2 client ID (required)
• ELASTIC_PATH_CLIENT_SECRET: Your OAuth2 client secret (required)
• ELASTIC_PATH_BASE_URL: API base URL (required)
• ELASTIC_PATH_GRANT_TYPE: OAuth2 grant type (default: "client_credentials")
• ELASTIC_PATH_SCOPE: OAuth2 scope (optional, leave empty if not needed)

Important Notes:

• ✅ Option 1 is recommended - Direct stdio communication with Claude
• ⚠️ Option 2 requires Node.js - WebSocket bridge for development
• 🔧 Credentials: Replace with your actual Elastic Path API credentials
• 📁 Paths: Update paths to match your project location
• 🔐 Grant Types: Supports "client_credentials", "password", "authorization_code", etc.
• 📖 More Examples: See examples/claude-desktop-configs.json for different OAuth2 configurations

Server Configuration

# configs/default.yaml
openapi_sources:
  known_apis:
    elastic_path:
      spec_url: "https://useast.api.elasticpath.com/v2/openapi.json"  # REQUIRED
      base_url: "https://useast.api.elasticpath.com"                 # Optional fallback
      description: "Elastic Path Commerce Cloud API"                 # Optional
      llms_txt_url: "https://developer.elasticpath.com/llms.txt"    # Optional
      context_ttl: "12h"                                             # Optional
      auto_discover_llms: true                                       # Optional

business_context:
  default_ttl: "6h"           # Cache TTL for llms.txt files
  fallback_to_stale: true     # Use stale cache if fetch fails
  max_cache_size: 50          # Maximum cached contexts

This allows clients to override API regions/environments dynamically while maintaining server defaults.

Development