OMCP

Give AI agents access to your API in minutes, not weeks.

OMCP converts your OpenAPI spec into a Model Context Protocol server. Point it at your spec, run one command, and AI agents can call your API.

Your OpenAPI Spec  →  OMCP  →  AI agents call your API

No tool definitions to write. No integration code to maintain. Just your spec and one config file.

---

The Problem

You have an API. You want AI agents to use it. Your options today:

Approach	Pain
Write tool definitions manually	Tedious, error-prone, falls out of sync with your API
Use an agent framework	Still have to map every endpoint, handle auth, manage context limits
Build from scratch	Weeks of integration work for each API

With OMCP: Point at your OpenAPI spec. Run omcp serve. Done.

---

Quick Start

Installation

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

Minimal Setup

# 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

That's it. Your AI agent can now call your API.

Connect to Claude Desktop

Add to claude_desktop_config.json:

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

---

Who Is This For

OMCP is for developers who already have an API and want AI agents to use it:

You Are	Your Goal	Why OMCP
SaaS developer	Add AI chat to your product	Uses your existing API, zero new backend code
Platform engineer	Build internal AI tooling	Hub architecture handles 100+ endpoints
Startup founder	Ship AI features fast	Minutes to integrate, not weeks
Enterprise team	AI layer on existing systems	Works with your existing auth

If you have an API and an OpenAPI spec, OMCP gets you to "AI-ready" in minutes.

---

Why OMCP

Without OMCP	With OMCP
Write tool definitions for every endpoint	Point at your OpenAPI spec
Maintain tool code as your API evolves	Changes auto-propagate from spec
Handle auth, errors, retries manually	Built-in auth providers
100+ tools overwhelm agent context	Hub architecture scales to any size
Agents struggle with cryptic auto-generated names	LLM optimizes names and descriptions
Build separate integration for each agent platform	MCP works with Claude, GPT, Gemini, and more

---

Key Features

🚀 Zero-Code Tool Generation

Your OpenAPI spec is the source of truth. OMCP reads it and generates MCP tools automatically:

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

Every endpoint becomes a tool. Schemas become parameters. Descriptions become tool documentation.

🔐 Multi-Tenant Ready

One OMCP server handles unlimited users. Each request carries its own token:

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

OMCP validates and forwards. Your API handles authorization exactly as it does today. No credential storage. No session management. No changes to your auth system.

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

📈 Scales to Any API Size

OMCP adapts to your API's complexity:

API Size	Mode	How It Works
Small (<30 ops)	single	One MCP server, all tools exposed directly
Medium (30-100 ops)	modular	Split into domain-specific micro-MCPs
Large (100+ ops)	modular + Hub	Micro-MCPs behind a hub with 6 meta-tools

The hub prevents context window bloat by exposing discovery tools instead of hundreds of individual tools.

🧠 LLM-Powered Optimization

OMCP uses an LLM to transform cryptic auto-generated names into agent-friendly tools:

Auto-Generated	LLM-Optimized
get_widgets_widgets_get	list_widgets
post_users_users_post	create_user
adjust_stock_widgets__widget_id__stock_patch	adjust_widget_stock

Every suggestion is validated against your actual spec. No hallucinated endpoints.

---

Architecture

Single Mode

For smaller APIs, each operation becomes one MCP tool:

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

Modular Mode with Hub

For large APIs, the hub exposes 6 meta-tools while providing access to all underlying operations:

┌─────────────────────────────────────────────────────────────────┐
│                          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   │
                        └─────────────┘

Agent workflow:

# 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"})

---

Examples

Demo API (Getting Started)

Basic example with a small API:

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

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

MegaStore (Large API + Hub)

100+ endpoint e-commerce API demonstrating modular mode with LLM planning:

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

# Open http://localhost:8000

Features:

• 100+ endpoints split into ~10 domain modules
• LLM-generated module organization
• Hub meta-tool pattern
• Chainlit web UI with tool visualization

Notes API (Multi-Tenant Authentication)

Multi-tenant example where each user authenticates with their own JWT:

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

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

Features:

• Per-request JWT authentication
• User isolation (each user sees only their data)
• Role-based access control
• Passthrough mode (OMCP forwards tokens, API validates)

---

Authentication

Static Auth (Server-Wide)

For APIs where OMCP uses a single credential:

# 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"]

Run OAuth2 flow: uv run omcp auth

Dynamic Auth (Per-Request JWT)

For multi-tenant scenarios where each client provides their own token:

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"

How it works:

1. Client sends request with Authorization: Bearer <user-token>
2. OMCP extracts token (optionally validates via JWKS)
3. OMCP forwards token to your API
4. Your API authorizes the user as it always does
5. User gets only their data

No credential storage. No changes to your API. Just works.

---

Endpoint Filtering

Control exactly which endpoints become MCP tools:

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"

Pattern syntax:

• METHOD /path — Specific method and path
• * /path — All methods for a path
• METHOD * — All paths for a method
• /path/** — Path and all sub-paths

Filters are applied before LLM processing—your exclusions are enforced absolutely.

---

LLM-Powered Planning

Generate optimized tool names and module organization:

# 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

The plan is saved to omcp.plan.json and validated against your spec:

• ✅ Every tool maps to a real operation
• ✅ No hallucinated endpoints
• ✅ Module groupings make semantic sense
• ✅ Safety policies are enforced

---

Configuration Reference

See example.omcp.yaml for a complete reference with all options documented.

Minimal

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

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

Full

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

---

CLI Commands

Command	Description
omcp serve	Run MCP server(s)
omcp plan	Generate LLM-optimized plan
omcp list	List operations from spec
omcp auth	Run OAuth2 authorization flow

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

---

Hub Meta-Tools Reference

When using modular mode with hub enabled:

Tool	Purpose
list_modules()	List all modules with descriptions and tool counts
list_module_tools(module)	List tools in a specific module
find_tool(query)	Search for tools by keyword across all modules
get_tool_schema(module, tool)	Get full parameter schema for a tool
call_tool(module, tool, args)	Execute any tool in any module
hub_status()	Get hub statistics

---

Environment Variables

Reference in config with ${VAR_NAME}:

# 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

---

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                        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        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key principle: LLM suggestions are never trusted blindly. Every tool is validated against operations that actually exist in your spec.

---

Project Structure

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

---

Contributing

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

181 tests passing.

See CONTRIBUTING.md for guidelines.

---

Roadmap

• [x] OpenAPI → MCP tool generation
• [x] Single server mode
• [x] Modular mode with hub
• [x] LLM-powered planning
• [x] Static authentication (bearer, API key, OAuth2)
• [x] Dynamic authentication (JWT passthrough)
• [ ] Response shaping (truncation, redaction)
• [ ] Streaming support for long operations
• [ ] OMCP Cloud (hosted, managed credentials)
• [ ] Semantic tool search (embeddings)

---

License

Apache‑2.0; No‑Hosting Source‑Available License (planned) When OMCP Cloud launches, server/hub/planner components will be released under a source‑available license that prohibits offering OMCP as a hosted/managed service to third parties without a commercial agreement.

Links

• Model Context Protocol
• FastMCP
• OpenAPI Specification

---