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

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 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 at line 34.
• sse: Provides a server-sent events stream for browser or agent clients, implemented in 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.

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. 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 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 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 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 every 5 seconds so dashboards can surface server health. The status endpoint at 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

omniroute --mcp

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

HTTP Streamable Transport Example

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

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

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 and open-sse/mcp-server/httpTransport.ts.
• Security is enforced via fine-grained API-key scopes in 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 and heartbeat monitoring via src/app/api/mcp/status/route.ts.
• Token optimization is achieved through description compression in open-sse/mcp-server/descriptionCompressor.ts and tool filtering via 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.

How does the MCP server handle security and permissions?

Security is implemented through scope enforcement in 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, allowing you to reduce token overhead by exposing only necessary tools to clients.

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