Your OpenAPI Spec  →  OMCP  →  AI agents call your API

git clone https://github.com/cal3bdev/omcp.git
cd omcp
uv sync

# omcp.yaml
name: "My API"
spec: "./openapi.json"
base_url: "https://api.example.com"

auth:
  type: bearer
  token: "${API_TOKEN}"

export API_TOKEN="your-token"
uv run omcp serve

{
  "mcpServers": {
    "my-api": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/omcp", "omcp", "serve"]
    }
  }
}

# This is your entire configuration
name: "My API"
spec: "./openapi.json"
base_url: "https://api.example.com"

User A (their JWT) ──┐
                     ├──►  OMCP  ──►  Your API
User B (their JWT) ──┘

# Dynamic auth: each user provides their own token
auth:
  type: jwt
  validation:
    enabled: true
    jwks_url: "https://auth.example.com/.well-known/jwks.json"

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│  AI Agent   │   MCP   │    OMCP     │  HTTP   │  Your API   │
│  (Claude)   │ ──────► │   Server    │ ──────► │  (REST)     │
└─────────────┘         └─────────────┘         └─────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                          AI Agent                               │
│                   (sees only 6 meta-tools)                      │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                          OMCP Hub                               │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │  list_modules   find_tool      call_tool                │   │
│   │  list_tools     get_schema     hub_status               │   │
│   └─────────────────────────────────────────────────────────┘   │
└───────────────────────────────┬─────────────────────────────────┘
                                │
          ┌─────────────────────┼─────────────────────┐
          ▼                     ▼                     ▼
    ┌───────────┐         ┌───────────┐         ┌───────────┐
    │   Users   │         │  Orders   │         │ Payments  │
    │  Module   │         │  Module   │         │  Module   │
    │ (15 tools)│         │ (20 tools)│         │ (12 tools)│
    └───────────┘         └───────────┘         └───────────┘
          │                     │                     │
          └─────────────────────┼─────────────────────┘
                                ▼
                        ┌─────────────┐
                        │  Your API   │
                        └─────────────┘

# 1. Discover what's available
find_tool("payment")              # → Shows payment-related tools

# 2. Understand parameters  
get_tool_schema("payments",       # → Full JSON schema
                "process_payment")

# 3. Execute
call_tool("payments",             # → Processes the payment
          "process_payment", 
          {"order_id": "123"})

# Terminal 1: Start the demo API
uv run python examples/demo_api/start.py

# Terminal 2: OMCP serves at http://localhost:9000

# Start everything with web UI
uv run python examples/large_api/start.py --ui

# Open http://localhost:8000

# Start with web UI
uv run python examples/auth_api/start.py --ui

# Open http://localhost:8000
# Switch between users: Alice (admin), Bob, Charlie

# Bearer token
auth:
  type: bearer
  token: "${API_TOKEN}"

# API key
auth:
  type: api_key
  key: "${API_KEY}"
  header_name: "X-API-Key"

# OAuth2 with PKCE
auth:
  type: oauth2
  client_id: "${CLIENT_ID}"
  client_secret: "${CLIENT_SECRET}"
  auth_url: "https://auth.example.com/authorize"
  token_url: "https://auth.example.com/token"
  scopes: ["read", "write"]

auth:
  type: jwt
  validation:
    enabled: false  # Passthrough: your API validates
    
  # OR validate in OMCP first:
  validation:
    enabled: true
    jwks_url: "https://auth.example.com/.well-known/jwks.json"
    issuer: "https://auth.example.com"
    audience: "my-api"

endpoints:
  # Exclude dangerous or internal routes
  exclude:
    - "DELETE *"          # All DELETE methods
    - "* /internal/**"    # All internal routes
    - "* /admin/**"       # All admin routes
    - "GET /health"       # Specific endpoint

  # Or whitelist specific endpoints
  include:
    - "GET /users/*"
    - "POST /orders"

# Set your LLM API key
export GEMINI_API_KEY="your-key"

# Generate optimized plan
uv run omcp plan

# Serve with optimized names
uv run omcp serve

name: "My API"
spec: "./openapi.json"
base_url: "https://api.example.com"

auth:
  type: bearer
  token: "${API_TOKEN}"

name: "Large API"
spec: "https://api.example.com/openapi.json"
base_url: "https://api.example.com"

mode: modular  # single | modular

auth:
  type: bearer
  token: "${API_TOKEN}"

# Endpoint filtering
endpoints:
  exclude:
    - "* /internal/**"
    - "DELETE *"

# LLM planner
llm:
  enabled: true
  provider: gemini  # openai | anthropic | gemini
  model: gemini-2.0-flash
  api_key: "${GEMINI_API_KEY}"
  strategy:
    max_tools_total: 200
    target_tools_per_module: 40
    naming:
      style: verb_noun
      max_name_length: 40

# Module configuration
modules:
  enabled: true
  split_strategy: llm  # llm | tags | path
  runtime:
    base_port: 9100
    host: "127.0.0.1"

# Hub configuration
hub:
  enabled: true
  port: 9000
  transport: http  # http | sse | stdio

uv run omcp serve -c config.yaml
uv run omcp plan -c config.yaml
uv run omcp list -c config.yaml --excluded
uv run omcp list -c config.yaml --by-module

# API Authentication
API_TOKEN=your-api-token

# LLM Providers (choose one)
GEMINI_API_KEY=your-gemini-key
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key

# OAuth2
CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret

┌─────────────────────────────────────────────────────────────────┐
│                        OMCP Pipeline                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   1. Load      OpenAPI spec (file or URL)                      │
│   2. Filter    Apply endpoint include/exclude rules            │
│   3. Plan      LLM suggests names, modules, descriptions       │
│   4. Validate  Check suggestions against actual spec           │
│   5. Build     Generate FastMCP servers deterministically      │
│   6. Serve     Run via stdio, SSE, or HTTP transport           │
│   7. Execute   Tool calls → authenticated HTTP requests        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

src/omcp/
├── auth/           # Auth providers (bearer, api_key, oauth2, jwt)
├── config/         # Configuration models (Pydantic v2)
├── hub/            # Hub server and meta-tools
├── modules/        # Module splitting and micro-MCP generation
├── planner/        # LLM planning and validation
├── server/         # Single server mode
├── spec/           # OpenAPI parsing and normalization
└── cli.py          # Typer CLI

examples/
├── auth_api/       # Dynamic JWT authentication demo
├── demo_api/       # Simple getting started example
├── large_api/      # 100+ endpoint hub demo
└── messy_api/      # Filtering and LLM optimization demo

uv sync
uv run pytest
uv run pytest tests/test_planner.py -v