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

> Discover how the MCP server integrates with OmniRoute, acting as a programmable facade for core routing services. Learn about its HTTP, SSE, and stdio transports.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: deep-dive
- Published: 2026-08-13

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) | `createCombo` |
| Cache operations | [`open-sse/services/cache.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/cache.ts) | `getCacheEntry`, `flushCache` |
| Memory management | [`open-sse/services/memory.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/memory.ts) | `queryMemory`, `scrapeMemory` |
| System observability | [`open-sse/services/audit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/server.ts) creates the `/api/mcp/` router and loads environment configuration
2. **Registration** – [`catalog.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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

```bash
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

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/tools/createComboTool.ts) delegates to [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts), identical to the standard REST flow.

---

### Streaming Completions via SSE

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts)—the same path as `/v1/chat/completions`.

---

### Python Client with Official MCP SDK

```python
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) | Server bootstrap and route registration |
| [`open-sse/mcp-server/catalog.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/catalog.ts) | Tool manifest generation and handler mapping |
| [`open-sse/mcp-server/httpTransport.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/httpTransport.ts) | HTTP/SSE/stdio transport implementation |
| [`open-sse/mcp-server/scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/scopeEnforcement.ts) | Scope-based access control |
| [`open-sse/mcp-server/audit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/audit.ts) | SQLite audit logging |
| [`docs/frameworks/MCP-SERVER.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/frameworks/MCP-SERVER.md) | Design documentation and transport matrices |
| [`docs/reference/ENVIRONMENT.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/audit.ts). Access logs via `GET /api/mcp/audit` or the OmniRoute dashboard for compliance review and debugging.