# OmniRoute MCP Server: Purpose, Architecture, and 110+ Tool Catalog

> Discover the purpose of the OmniRoute MCP server. It provides 110+ tools for routing, cache, compression, and memory management via RPC, enabling IDE integrations and LLM proxies.

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

---

**The MCP server in OmniRoute is a built-in RPC layer that exposes 110+ tools for routing, cache, compression, and memory management through stdio, SSE, and streamable HTTP transports, enabling IDE integrations and programmable LLM proxies.**

The **OmniRoute MCP server** transforms the routing engine into a programmable interface for large language models. Located in the `diegosouzapw/OmniRoute` repository, this component implements the **Model Context Protocol** to expose internal capabilities as discoverable JSON-RPC tools. It supports three interchangeable transport modes and enforces fine-grained security scopes for every invocation.

## What Is the MCP Server in OmniRoute?

The **MCP (Model Context Protocol) server** is OmniRoute’s built-in RPC layer that exposes a rich catalog of **110 tools** covering routing, cache, compression, memory, skills, proxy, and Radar functionality. The server is started via the CLI flag `omniroute --mcp` and binds to a single `createMcpServer()` factory defined in [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) that manages tool registration, scope enforcement, and audit logging.

## Transport Architecture: Three Modes of Operation

The MCP server supports three interchangeable transports, allowing clients to choose the most appropriate communication channel:

- **stdio**: Used for IDE integrations like Claude Desktop and Cursor. The entry point is [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) at line 34.
- **sse**: Provides a server-sent events stream for browser or agent clients, implemented in [`open-sse/mcp-server/httpTransport.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/httpTransport.ts) at line 30.
- **streamable-http**: Supports multi-session HTTP clients using the `mcp-session-id` header, defined at line 35 of [`open-sse/mcp-server/httpTransport.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/httpTransport.ts).

## Core Responsibilities and Implementation

### Tool Registration and Discovery

At startup, the server enumerates the tool catalog via `tools/list`, computing the total count through `countUniqueMcpTools()` at line 11. The catalog is organized into groups: Essential (Phase 1), Advanced (Phase 2), Cache, Compression, Memory, Skill, Notion, Agent-Skill, and Proxy.

### Scope Enforcement and Security

Each tool declares required API-key scopes enforced by [`open-sse/mcp-server/scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/scopeEnforcement.ts). The enforcement pipeline evaluates permissions at lines 78-84; missing scopes generate a `scope_denied` audit entry and reject the call immediately.

### Audit Logging and Observability

Every invocation is recorded in the SQLite `mcp_tool_audit` table by [`open-sse/mcp-server/audit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/audit.ts) at lines 20-26. Operators can inspect usage, success rates, and timing via the `/api/mcp/audit` endpoint.

### Description Compression for Token Efficiency

Tool metadata is optionally compressed at registration time via [`open-sse/mcp-server/descriptionCompressor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/descriptionCompressor.ts) at lines 59-66. This reduces the token cost of the tool manifest that clients must embed in their prompts.

### Tool Cardinality Control

Environment variables `MCP_TOOL_DENY` and `MCP_TOOL_ALLOW` let operators prune the catalog via [`open-sse/mcp-server/toolCardinality.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/toolCardinality.ts) at lines 70-81, lowering token overhead by filtering available tools before registration completes.

### Runtime Health Monitoring

The stdio transport writes a heartbeat file [`mcp-heartbeat.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/mcp-heartbeat.json) every 5 seconds so dashboards can surface server health. The status endpoint at [`src/app/api/mcp/status/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/mcp/status/route.ts) exposes this telemetry.

### Remote Access Control

While `/api/mcp/*` routes default to the `LOCAL_ONLY` tier, clients possessing the `mcp:connect` scope or a full `manage` key can access the server over tunnels or public hosts, as configured at lines 42-48 of the access control layer.

## Practical Usage and Code Examples

### Starting the Server

```bash
omniroute --mcp

```

The server prints its PID and heartbeat path, then listens on the stdio pipe for JSON-RPC requests.

### HTTP Streamable Transport Example

```bash
curl -X POST http://localhost:20128/api/mcp/stream \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc":"2.0",
        "id":1,
        "method":"omniroute_get_health",
        "params":{}
      }'

```

This returns uptime, circuit-breaker states, and cache stats via the `omniroute_get_health` tool.

### Node.js Client Integration

```javascript
import { spawn } from 'node:child_process';
import { createInterface } from 'node:readline';

const mcp = spawn('omniroute', ['--mcp']);
const rl = createInterface({ input: mcp.stdout });

rl.on('line', line => console.log('MCP response:', line));

const request = {
  jsonrpc: '2.0',
  id: 42,
  method: 'omniroute_simulate_route',
  params: {
    prompt: 'Write a short poem about sunrise.',
    model: 'gpt-4o-mini'
  }
};

mcp.stdin.write(JSON.stringify(request) + '\n');

```

The `omniroute_simulate_route` call returns a structured simulation showing which providers would be tried, fallback paths, and estimated latencies.

### Using the Client Library

```typescript
import { createMcpClient } from '@omniroute/mcp-client';

const client = await createMcpClient({
  transport: 'stdio',
  apiKey: process.env.OMNIROUTE_API_KEY,
});

const tools = await client.call('omniroute_tool_search', {});
console.log('Available MCP tools:', tools);

```

## Summary

- **The OmniRoute MCP server** exposes 110+ tools through three transports: stdio, SSE, and streamable HTTP, defined in [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) and [`open-sse/mcp-server/httpTransport.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/httpTransport.ts).
- **Security** is enforced via fine-grained API-key scopes in [`open-sse/mcp-server/scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/scopeEnforcement.ts), with denials logged as `scope_denied`.
- **Observability** is provided through SQLite audit logging in [`open-sse/mcp-server/audit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/audit.ts) and heartbeat monitoring via [`src/app/api/mcp/status/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/mcp/status/route.ts).
- **Token optimization** is achieved through description compression in [`open-sse/mcp-server/descriptionCompressor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/descriptionCompressor.ts) and tool filtering via [`open-sse/mcp-server/toolCardinality.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/toolCardinality.ts).
- **Access control** supports local-only defaults with optional remote access via keys scoped with `mcp:connect`.

## Frequently Asked Questions

### How do I start the OmniRoute MCP server?

Start the server by running the CLI command `omniroute --mcp`. This initializes the `createMcpServer()` factory and begins listening on the stdio transport by default, printing the process ID and heartbeat file path to stdout.

### What transports does the OmniRoute MCP server support?

The server supports three transports: **stdio** for IDE integrations like Claude Desktop, **sse** for server-sent event streams, and **streamable-http** for multi-session HTTP clients using the `mcp-session-id` header. All transports are defined in [`open-sse/mcp-server/httpTransport.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/httpTransport.ts).

### How does the MCP server handle security and permissions?

Security is implemented through scope enforcement in [`open-sse/mcp-server/scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/scopeEnforcement.ts). Each tool declares required API-key scopes, and the server evaluates these permissions at runtime. Missing scopes result in a `scope_denied` audit entry and rejected execution.

### Can I reduce the number of tools exposed by the MCP server?

Yes. Use the environment variables `MCP_TOOL_DENY` and `MCP_TOOL_ALLOW` to filter the tool catalog. The filtering logic runs in [`open-sse/mcp-server/toolCardinality.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/toolCardinality.ts), allowing you to reduce token overhead by exposing only necessary tools to clients.