MCP OpenAPI Template

A template for building MCP (Model Context Protocol) servers from OpenAPI specifications.

This template provides a production-ready foundation for creating MCP servers that expose any REST API with an OpenAPI specification to LLM-powered tools.

Features

• Dynamic Tool Generation: Automatically creates MCP tools from OpenAPI specs
• Auth Gateway Integration: Centralized authentication via Auth Gateway
• Dual Transport: Supports both stdio (local) and sse (remote) transports
• Configurable Validation: Customizable ID patterns and input validation
• Tool Policies: Risk-based policies for blocking/logging operations
• Docker Ready: Production-ready Dockerfile and docker-compose

Quick Start

1. Clone/Use Template

# Using GitHub template feature (recommended)
# Click "Use this template" on GitHub

# Or clone directly
git clone https://github.com/jesusperezdeveloper/mcp_openapi_template my-api-mcp
cd my-api-mcp

2. Initialize Your Service

python -m scripts.init_service \
  --name "github" \
  --display-name "GitHub" \
  --base-url "https://api.github.com" \
  --openapi-url "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json"

3. Configure Auth Gateway

Edit .env with your Auth Gateway credentials:

AUTH_GATEWAY_URL=https://your-auth-gateway.com
AUTH_GATEWAY_API_KEY=your-api-key

4. Download OpenAPI Spec

python -m scripts.fetch_openapi

5. Run the Server

# Local mode (stdio)
PYTHONPATH=vendor python -m src.server

# Remote mode (SSE)
MCP_TRANSPORT=sse PYTHONPATH=vendor python -m src.server

Project Structure

mcp_openapi_template/
├── src/
│   ├── server.py           # Main MCP server
│   ├── config.py           # Configuration loader
│   ├── openapi_tools.py    # Dynamic tool generator
│   ├── auth_gateway.py     # Auth Gateway integration
│   ├── validation.py       # Input validation
│   └── tool_policies.py    # Risk policies
├── config/
│   ├── service.yaml        # Service configuration
│   ├── mcp.local.json      # Local MCP config
│   └── mcp.remote.json     # Remote MCP config
├── scripts/
│   ├── fetch_openapi.py    # Download OpenAPI spec
│   └── init_service.py     # Initialize new service
├── examples/
│   └── trello/             # Complete Trello example
├── openapi/                # OpenAPI specs (downloaded)
├── vendor/mcp/             # Vendorized MCP SDK
├── Dockerfile
└── docker-compose.yml

Configuration

service.yaml

The main configuration file (config/service.yaml) defines:

service:
  name: "myservice"
  display_name: "My Service"

api:
  base_url: "https://api.example.com"
  openapi_spec_url: "https://api.example.com/openapi.json"
  tool_prefix: "myservice"

auth:
  gateway_endpoint: "/credentials/myservice"
  credentials_format:
    - name: "api_key"
      query_param: "key"

validation:
  id_pattern: "^[a-zA-Z0-9]+$"

policies:
  blocked_patterns:
    - "delete_organization"

Environment Variables

Variable	Required	Description
AUTH_GATEWAY_URL	Yes	Auth Gateway URL
AUTH_GATEWAY_API_KEY	Yes	API Key for Auth Gateway
API_BASE_URL	No	Override API base URL
MCP_TRANSPORT	No	stdio (default) or sse
MCP_PORT	No	Port for SSE mode (default: 8000)

Authentication Flow

1. User obtains JWT from Auth Gateway (login)
2. User calls set_auth_token(jwt) in the MCP
3. MCP fetches API credentials from Auth Gateway
4. Credentials are cached for the session
5. User can now use all available tools

Adding Custom Helper Tools

See examples/trello/helpers.py for a complete example of adding user-friendly wrapper tools.

# In src/helpers.py
def register_helper_tools(mcp, auth_params, client_factory, require_auth):
    @mcp.tool(description="My custom tool")
    async def my_tool(param: str) -> dict:
        require_auth()
        # Implementation
        pass

Docker Deployment

# Build with OpenAPI spec
docker build \
  --build-arg OPENAPI_SPEC_URL="https://api.example.com/openapi.json" \
  -t my-mcp .

# Run
docker run -p 8000:8000 --env-file .env my-mcp

Examples

See the examples/ directory for complete configurations:

• Trello: Full configuration with helper tools, validation, and policies

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.