How the MCP Server Integrates with OmniRoute: A Technical Deep Dive

The MCP server in OmniRoute acts as a programmable façade that exposes core routing services—combo routing, caching, memory, and audit—as named tools accessible over HTTP, SSE, and stdio transports.

The MCP (Multi‑Channel Protocol) server is built directly into OmniRoute and provides a unified interface for AI agents and automation tools to interact with the platform's internal services. Rather than replacing the existing HTTP API, it wraps the same service layer used by standard REST endpoints and repackages it as 107 configurable tools with fine‑grained access control and comprehensive audit logging.

---

Core Architecture and Integration Points

Entry Point and Server Bootstrap

The integration begins in open‑sse/mcp-server/server.ts, which bootstraps the MCP server when OmniRoute starts with the --mcp flag or OMNIROUTE_ENABLE_MCP=true. This module:

• Reads environment configuration including OMNIROUTE_MCP_ENFORCE_SCOPES and OMNIROUTE_MCP_SCOPES
• Creates an Express router mounted at /api/mcp/*
• Initializes the transport layer and tool catalog

---

Tool Catalog and Service Mapping

open‑sse/mcp-server/catalog.ts generates the tool manifest that maps each of the 107 built‑in tools to internal OmniRoute service handlers. Every tool definition in open-sse/mcp-server/tools/ routes to the same core functions used by the standard HTTP API:

Tool Category	Internal Service	Example Tool
Combo routing	open-sse/services/combo.ts	createCombo
Cache operations	open-sse/services/cache.ts	getCacheEntry, flushCache
Memory management	open-sse/services/memory.ts	queryMemory, scrapeMemory
System observability	open-sse/services/audit.ts	observabilitySnapshot

---

Transport Layer Implementation

open‑sse/mcp-server/httpTransport.ts implements three transport mechanisms:

1. HTTP (REST) – POST /api/mcp/<tool> for synchronous calls
2. SSE (Server‑Sent Events) – /api/mcp/sse for streaming completions
3. stdio – Line‑delimited JSON for IDE and CLI integrations

Each transport validates incoming requests with Zod schemas, enforces authorization, and delegates to the appropriate catalog handler.

---

Security and Scope Enforcement

open‑sse/mcp-server/scopeEnforcement.ts provides fine‑grained access control through configurable scopes:

• Default scopes: All tools accessible (OMNIROUTE_MCP_SCOPES unset or ["*"])
• Explicit scopes: Granular permissions like read:combos, write:cache, admin:audit
• Enforcement mode: When OMNIROUTE_MCP_ENFORCE_SCOPES=true, every tool call validates against the token's scope list

MCP calls authenticate via OMNIROUTE_API_KEY carrying the mcp scope—the same key mechanism used for internal A2A (Agent‑to‑Agent) calls.

---

Audit and Compliance

open‑sse/mcp-server/audit.ts persists every tool invocation to the mcp_audit SQLite table with immutable records. The audit API at GET /api/mcp/audit serves both the OmniRoute dashboard and external compliance tooling.

---

Data Flow: From Request to Service Execution

1. Startup – server.ts creates the /api/mcp/ router and loads environment configuration
2. Registration – catalog.ts iterates 107 tool definitions into an in‑memory map
3. Request handling – Transport layer parses JSON, validates schemas, checks scopes
4. Service execution – Handler calls core services (routing, cache, memory, etc.)
5. Response & audit – Result returned to client; invocation logged to mcp_audit

---

Practical Code Examples

Listing Available MCP Tools

curl -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
     $OMNIROUTE_BASE_URL/api/mcp/tools

Returns a JSON array with name, description, and required scopes for each tool.

---

Invoking a Routing Tool via HTTP

curl -X POST -H "Content-Type: application/json" \
     -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
     -d '{"targets":["gpt-4o"],"prompt":"Explain MCP"}' \
     $OMNIROUTE_BASE_URL/api/mcp/createCombo

The createComboTool handler in tools/createComboTool.ts delegates to open-sse/services/combo.ts, identical to the standard REST flow.

---

Streaming Completions via SSE

curl -N -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
     $OMNIROUTE_BASE_URL/api/mcp/sse \
     -d '{"tool":"omniroute_chat_completions","args":{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}}'

Server‑sent events stream chunks through open-sse/handlers/chatCore.ts—the same path as /v1/chat/completions.

---

Python Client with Official MCP SDK

from mcp import MCPClient

client = MCPClient(
    base_url="http://localhost:20128",
    api_key="YOUR_OMNIROUTE_API_KEY"
)

# Fetch tool catalog

tools = client.list_tools()
print(tools)

# Execute cache lookup

result = client.invoke(
    "omniroute_get_cache_entry",
    {"key": "session:abc123"}
)
print(result)

The SDK handles transport selection, scope attachment, and response parsing automatically.

---

Key Source Files

File	Purpose
open-sse/mcp-server/server.ts	Server bootstrap and route registration
open-sse/mcp-server/catalog.ts	Tool manifest generation and handler mapping
open-sse/mcp-server/httpTransport.ts	HTTP/SSE/stdio transport implementation
open-sse/mcp-server/scopeEnforcement.ts	Scope-based access control
open-sse/mcp-server/audit.ts	SQLite audit logging
docs/frameworks/MCP-SERVER.md	Design documentation and transport matrices
docs/reference/ENVIRONMENT.md	Configuration variables reference

---

Summary

• MCP server integration wraps OmniRoute's core services as 107 named tools without duplicating business logic
• Three transports (HTTP, SSE, stdio) support diverse client types from web apps to desktop agents
• Unified security model uses OMNIROUTE_API_KEY with configurable scopes for principle of least privilege
• Complete observability via SQLite audit logging and the observability_snapshot tool
• Zero duplication—MCP handlers call the same service functions as standard REST endpoints

---

Frequently Asked Questions

What transports does the OmniRoute MCP server support?

The MCP server supports three transports: HTTP for synchronous REST calls, SSE for streaming completions, and stdio for CLI and IDE integrations like VS Code Copilot or Claude Desktop. Configuration is automatic based on how the server is launched.

How does MCP scope enforcement work in OmniRoute?

Scopes are enforced by open-sse/mcp-server/scopeEnforcement.ts using environment variables. Set OMNIROUTE_MCP_SCOPES to an array like ["read:combos","write:cache"] and enable OMNIROUTE_MCP_ENFORCE_SCOPES=true to restrict tool access. The default allows all tools.

Can I use the same API key for MCP and regular OmniRoute API calls?

Yes. The OMNIROUTE_API_KEY carries the mcp scope and authenticates both MCP tool invocations and internal A2A calls. This single‑source‑of‑truth design simplifies key rotation and permission management.

Where are MCP tool invocations logged?

Every call is persisted to the mcp_audit SQLite table by open-sse/mcp-server/audit.ts. Access logs via GET /api/mcp/audit or the OmniRoute dashboard for compliance review and debugging.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}