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.
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.
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 serveThat's it. Your AI agent can now call your API.
Add to claude_desktop_config.json:
{
"mcpServers": {
"my-api": {
"command": "uv",
"args": ["run", "--directory", "/path/to/omcp", "omcp", "serve"]
}
}
}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.
| 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 |
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.
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"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.
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.
For smaller APIs, each operation becomes one MCP tool:
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ AI Agent │ MCP │ OMCP │ HTTP │ Your API │
│ (Claude) │ ──────► │ Server │ ──────► │ (REST) │
└─────────────┘ └─────────────┘ └─────────────┘
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"})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:9000100+ 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:8000Features:
- 100+ endpoints split into ~10 domain modules
- LLM-generated module organization
- Hub meta-tool pattern
- Chainlit web UI with tool visualization
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, CharlieFeatures:
- Per-request JWT authentication
- User isolation (each user sees only their data)
- Role-based access control
- Passthrough mode (OMCP forwards tokens, API validates)
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
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:
- Client sends request with
Authorization: Bearer <user-token> - OMCP extracts token (optionally validates via JWKS)
- OMCP forwards token to your API
- Your API authorizes the user as it always does
- User gets only their data
No credential storage. No changes to your API. Just works.
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 pathMETHOD *— All paths for a method/path/**— Path and all sub-paths
Filters are applied before LLM processing—your exclusions are enforced absolutely.
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 serveThe 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
See example.omcp.yaml for a complete reference with all options documented.
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| 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-moduleWhen 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 |
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┌─────────────────────────────────────────────────────────────────┐
│ 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.
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 -v181 tests passing.
See CONTRIBUTING.md for guidelines.
- OpenAPI → MCP tool generation
- Single server mode
- Modular mode with hub
- LLM-powered planning
- Static authentication (bearer, API key, OAuth2)
- Dynamic authentication (JWT passthrough)
- Response shaping (truncation, redaction)
- Streaming support for long operations
- OMCP Cloud (hosted, managed credentials)
- Semantic tool search (embeddings)