How to Set Up the OmniRoute MCP Server for Agent Integrations: Complete Configuration Guide

The OmniRoute MCP server is built-in and enabled via the --mcp flag or --dev mode, supports three transports (stdio, SSE, streamable-HTTP), and requires API-key scopes (manage or mcp:connect) for remote access.

The Model Context Protocol (MCP) server in OmniRoute exposes 104 tools that let IDE assistants, browser-based agents, and custom MCP clients interact with your routing infrastructure. As implemented in diegosouzapw/OmniRoute, the server runs inside the same process as the main application and requires minimal configuration to activate. This guide walks through enabling transports, securing access, and integrating agents from source-code level to production deployment.

Enable the MCP Server

OmniRoute provides three ways to start the MCP server, depending on your use case.

CLI Start with Dedicated Flag

Use the --mcp flag for standalone MCP operation with stdio transport (default for IDE integrations):

omniroute --mcp

This reads from open-sse/mcp-server/server.ts and initializes the server factory that registers all 104 available tools.

Development Mode with HTTP Endpoint

For browser-based agents and HTTP clients, start in development mode:

omniroute --dev

The MCP server auto-starts on the /mcp endpoint with SSE transport as the default. The transport layer is implemented in open-sse/mcp-server/httpTransport.ts, which also handles the streamable-http variant for multi-session clients.

Explicit Transport Selection

Override the default by setting the mcpTransport value in the key_value table:

curl -X POST http://localhost:20128/api/settings/mcpTransport \
     -H "Content-Type: application/json" \
     -d '{"value":"streamable-http"}'

Valid options are:

• stdio — IDE integrations (Claude Desktop, Cursor, etc.)
• sse — Event-stream clients
• streamable-http — Multi-session HTTP with mcp-session-id header

Configure Authentication and Scopes

MCP endpoints enforce API-key-based scope validation through open-sse/mcp-server/scopeEnforcement.ts. Per-key transport handling lives in open-sse/mcp-server/httpAuthContext.ts.

Two scope levels control access:

Scope	Capability	Use Case
manage or admin	Full remote access to any MCP transport	Administrators, dashboard users
mcp:connect	MCP transport access only, no management rights	Agent integrations, limited-access clients

Create a narrow-scope key via the Dashboard → API Keys page, or programmatically:

curl -X POST http://localhost:20128/api/keys \
     -H "Authorization: Bearer <admin-key>" \
     -H "Content-Type: application/json" \
     -d '{"scopes":["mcp:connect"]}'

The mcp:connect scope was introduced in v3.8.50 specifically to support agent integrations without over-provisioning permissions.

Enable Remote Access (Non-Loopback)

By default, /api/mcp/* routes are LOCAL_ONLY — restricted to localhost connections. To accept requests from remote hosts:

1. Present a Bearer token with manage or mcp:connect scope
2. Optionally expose OmniRoute behind a reverse proxy or tunnel

Remote client example calling the streamable-HTTP endpoint:

curl -i \
  -H "Host: your-public-host.example" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","clientInfo":{"name":"my-client","version":"1.0"}}}' \
  https://your-public-host.example/api/mcp/stream

Without valid scope credentials, the request is rejected at the scope enforcement layer before reaching tool handlers.

Integrate Agents: End-to-End Workflow

Once the server is running, agents follow this pattern:

1. Initialize — Send initialize or any tool call through the chosen transport
2. Execute tools — Use names like omniroute_route_request, omniroute_memory_search, omniroute_skills_execute (full catalog in open-sse/mcp-server/tools/*.ts)
3. Audit — Every call is logged to the mcp_tool_audit table, accessible via /api/mcp/audit or the dashboard

Tool registration is modular: each category (memory, skills, compression, proxy, etc.) has its own file under open-sse/mcp-server/tools/. The server factory in open-sse/mcp-server/server.ts aggregates these at startup.

Example: Invoke a Tool Over Streamable-HTTP

curl -X POST http://localhost:20128/api/mcp/stream \
     -H "Authorization: Bearer <mcp-key>" \
     -H "mcp-session-id: demo-session" \
     -H "Content-Type: application/json" \
     -d '{
           "jsonrpc":"2.0",
           "id":1,
           "method":"omniroute_route_request",
           "params":{"model":"gpt-4","messages":[{"role":"user","content":"Hello"}]}
         }'

The mcp-session-id header is required for streamable-http to maintain state across requests, as implemented in open-sse/mcp-server/httpTransport.ts.

Inspect Audit Logs

curl http://localhost:20128/api/mcp/audit?limit=5 \
     -H "Authorization: Bearer <admin-key>"

Optional Configuration Features

OmniRoute includes several MCP-specific optimizations:

Feature	Purpose	Implementation
Description Compression	Reduces metadata payload for tools, prompts, resources	open-sse/mcp-server/descriptionCompressor.ts
Tool Cardinality Reduction	Hides selected tools to save token budget in large catalogs	open-sse/mcp-server/toolCardinality.ts
Runtime Heartbeat	Writes liveness JSON for stdio transport health checks	open-sse/mcp-server/runtimeHeartbeat.ts

Environment variables provide fine-grained control:

• OMNIROUTE_MCP_ENFORCE_SCOPES — Toggle scope enforcement
• MCP_TOOL_DENY — Comma-separated list of tools to disable

Reference docs/frameworks/MCP-SERVER.md for the complete variable list.

Key Source Files

Understanding these files helps with debugging and customization:

File	Role
open-sse/mcp-server/server.ts	Server factory, tool registration
open-sse/mcp-server/httpTransport.ts	SSE and streamable-HTTP transport logic
open-sse/mcp-server/scopeEnforcement.ts	Scope resolution and enforcement
open-sse/mcp-server/httpAuthContext.ts	Per-key transport authorization
open-sse/mcp-server/tools/*.ts	Individual tool implementations
src/app/api/mcp/*/route.ts	Public REST endpoints (/status, /tools, /sse, /stream, /audit)

Summary

• Start the server with --mcp (stdio) or --dev (HTTP/SSE)
• Select transport via mcpTransport setting: stdio, sse, or streamable-http
• Secure access with API keys bearing manage or mcp:connect scope
• Enable remote access by presenting valid Bearer tokens; loopback restriction applies by default
• Monitor usage through the mcp_tool_audit table and /api/mcp/audit endpoint
• Optimize payload with description compression and tool cardinality reduction for token-constrained agents

Frequently Asked Questions

What transport should I use for Claude Desktop or Cursor?

Use stdio. These IDEs spawn the MCP server as a subprocess and communicate over standard input/output. Start OmniRoute with omniroute --mcp — no additional configuration needed. The transport is handled by open-sse/mcp-server/server.ts with heartbeat support in runtimeHeartbeat.ts.

How do I restrict an API key to only MCP access without full admin rights?

Create a key with the mcp:connect scope. Introduced in v3.8.50, this scope grants transport access while blocking management operations like key creation or configuration changes. Set this in the Dashboard or via POST /api/keys with {"scopes":["mcp:connect"]}.

Why can't I reach /api/mcp/stream from another machine?

Loopback protection is active. By default, MCP endpoints reject non-localhost requests regardless of authentication. To enable remote access, ensure your request includes a valid Bearer token with manage or mcp:connect scope, then expose the OmniRoute port through your reverse proxy or tunnel. The enforcement logic resides in open-sse/mcp-server/scopeEnforcement.ts.

How do I reduce the tool catalog size for token-limited agents?

Enable tool cardinality reduction. Use open-sse/mcp-server/toolCardinality.ts to hide unused tools from the capability advertisement. Combine with description compression (descriptionCompressor.ts) to minimize the initialize response payload. Set MCP_TOOL_DENY to explicitly disable specific tools by name.

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