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

> Configure the OmniRoute MCP server for agent integrations with this complete guide. Learn setup, transports, and API key scopes for seamless connections.

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

---

**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):

```bash
omniroute --mcp

```

This reads from [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/scopeEnforcement.ts). Per-key transport handling lives in [`open-sse/mcp-server/httpAuthContext.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

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

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) aggregates these at startup.

### Example: Invoke a Tool Over Streamable-HTTP

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/httpTransport.ts).

### Inspect Audit Logs

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/toolCardinality.ts) |
| **Runtime Heartbeat** | Writes liveness JSON for stdio transport health checks | [`open-sse/mcp-server/runtimeHeartbeat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) | Server factory, tool registration |
| [`open-sse/mcp-server/httpTransport.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/httpTransport.ts) | SSE and streamable-HTTP transport logic |
| [`open-sse/mcp-server/scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/scopeEnforcement.ts) | Scope resolution and enforcement |
| [`open-sse/mcp-server/httpAuthContext.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) with heartbeat support in [`runtimeHeartbeat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/toolCardinality.ts) to hide unused tools from the capability advertisement. Combine with description compression ([`descriptionCompressor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/descriptionCompressor.ts)) to minimize the initialize response payload. Set `MCP_TOOL_DENY` to explicitly disable specific tools by name.