OmniRoute MCP Server Documentation

Model Context Protocol server with 105 tools across routing, cache, compression, memory, skills, proxy, pool, and context source operations.

Source of truth: open-sse/mcp-server/server.ts computes 105 unique tools with countUniqueMcpTools(): 42 canonical definitions (including the six CCR lifecycle tools and the agent-skills trio), plus memory (3), skills (4), GitHub skills (3), pool (6), gamification (8), plugins (8), Notion (6), Obsidian (22), and two RTK-only compression tools.

Installation

OmniRoute MCP is built-in. Start it with:

omniroute --mcp

Or via the open-sse transport:

# HTTP streamable transport (port 20130)
omniroute --dev  # MCP auto-starts on /mcp endpoint

Transports

The MCP server exposes three transports, all backed by the same createMcpServer() factory:

The active HTTP transport (sse or streamable-http) is selected by the mcpTransport setting. Switching transports closes existing sessions on the other transport.

Remote access (manage-scope bypass)

/api/mcp/* is in the LOCAL_ONLY tier (src/server/authz/routeGuard.ts) — by default only loopback hosts (localhost, 127.0.0.1, ::1) can reach it. Since v3.8.2, non-loopback clients may connect if they present an Authorization: Bearer <api-key> whose key carries the manage scope. This is the only way to reach the remote MCP server through a tunnel, reverse proxy, or public hostname.

# Grant manage scope: open the dashboard API Keys page and toggle
# "Management Access" on the key, or POST scopes:["manage"] when creating.

# Then connect from a remote MCP client:
curl -i \
  -H "Host: your-public-host.example" \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-client","version":"0"}}}' \
  https://your-public-host.example/api/mcp/stream

A non-manage key (or no Bearer) returns 403 LOCAL_ONLY. The sibling prefix /api/cli-tools/runtime/* is intentionally NOT bypassable — see Route Guard Tiers — Manage-scope carve-out.

IDE Configuration

See MCP Client Configuration for Claude Desktop, Cursor, Cline, and compatible MCP client setup.

Essential Tools (8) — Phase 1

Phase 1 — Search

Advanced Tools (11) — Phase 2

Cache Tools (2)

Compression Tools (13)

CCR entries are in-memory only and disappear on restart. Each block is limited to 2 MiB, each principal to 16 MiB, and the global store to 64 MiB. Entries default to a 24-hour TTL (maximum seven days). Full MCP retrieval is limited to 256 KiB; larger blocks remain available through the ranged and grep modes. Storage, retrieval, listing, inspection, deletion, and stats are isolated by the authenticated API-key principal. Audit records contain hashes and size metadata, never content.

omniroute_compression_status reports MCP description compression separately under analytics.mcpDescriptionCompression. Those values are metadata-size estimates for MCP listable descriptions (tools, prompts, resources, and resourceTemplates); they are not provider usage receipts and are marked with source: "mcp_metadata_estimate".

MCP Accessibility Tree Filter (v3.8.0)

Separate from the compression tools above, OmniRoute includes a post-execution filter that compresses the tool results of MCP browser/accessibility tools before they are returned to the agent. This filter is not itself a tool — it runs transparently on any tool result that contains verbose accessibility-tree or browser-snapshot text (≥2000 chars).

Key behaviors:

• Collapses ≥30 consecutive repeated sibling lines into head + tail summary
• Preserves [ref=eXX] anchors required by Playwright/computer-use
• Hard-truncates oversized text (>50,000 chars) with a navigation hint
• Expected savings: 60–80% on browser snapshot payloads

Configuration: compression.mcpAccessibility in global settings (migration 056). Implementation: open-sse/services/compression/engines/mcpAccessibility/. Full docs: Compression Engines — MCP Accessibility Tree Filter.

See Compression Engines and RTK Compression for the runtime compression model behind these tools.

1Proxy Tools (3)

Memory Tools (3)

Defined in open-sse/mcp-server/tools/memoryTools.ts. Auth/scope is enforced through the standard MCP scope pipeline.

Skill Tools (4)

Defined in open-sse/mcp-server/tools/skillTools.ts. Backed by src/lib/skills/registry + src/lib/skills/executor.

Notion Context Source (6)

Defined in open-sse/mcp-server/tools/notionTools.ts. Token stored in key_value table via src/lib/db/notion.ts. REST client in src/lib/notion/api.ts. Settings API in src/app/api/settings/notion/route.ts. Dashboard UI in src/app/(dashboard)/dashboard/endpoint/components/NotionSourceCard.tsx.

Configure your Notion integration token from the Context Sources tab in the Endpoint dashboard, or via the REST API:

# Set token
curl -X POST http://localhost:20128/api/settings/notion \
  -H "Content-Type: application/json" \
  -d '{"token": "ntn_..."}'

# Check status
curl http://localhost:20128/api/settings/notion

# Disconnect
curl -X DELETE http://localhost:20128/api/settings/notion

Agent Skill Catalog Tools (3)

Defined in open-sse/mcp-server/tools/agentSkillTools.ts. Backed by src/lib/agentSkills/catalog. These tools expose the 42-entry Agent Skills documentation catalog to MCP clients and external agents. Scope: read:catalog.

See AGENT-SKILLS.md for the full catalog and how external agents consume it.

Related Frameworks (v3.8.0)

computed = 105, computed by countUniqueMcpTools()) is intentionally scoped to runtime routing/cache/compression/memory/skills/proxy/context-source operations. Two adjacent frameworks ship alongside the MCP server in v3.8.0 and are documented separately:

Cloud Agents

Cloud Agents are out-of-process AI coding agents (codex-cloud, devin, jules) wired into OmniRoute through the same connection model used for LLM providers. They are exposed via their own REST surface (/api/v1/agents/*) and are not part of the MCP tool catalog — calling a Cloud Agent does not consume an MCP scope.

• Implementation: src/lib/cloudAgent/ (registry.ts, agents/codex-cloud.ts, agents/devin.ts, agents/jules.ts).
• Lifecycle: createTask, getStatus, approvePlan, sendMessage, listSources.
• Documentation: docs/frameworks/CLOUD_AGENT.md.

Guardrails

Guardrails are pre/post-execution filters (vision-bridge, pii-masker, prompt-injection) applied inside the chat pipeline. They run before the MCP tool/route layer is reached and emit structured violations to the audit pipeline; they are not invoked as MCP tools.

• Implementation: src/lib/guardrails/.
• Documentation: docs/security/GUARDRAILS.md.

When debugging an MCP call that appears blocked, check both the MCP audit log (scope_denied:* entries) and the guardrails audit trail — a request may be rejected by a guardrail before it ever reaches the MCP scope enforcement layer.

REST API Endpoints

Source files: src/app/api/mcp/{status,tools,sse,stream,audit,audit/stats}/route.ts.

Both SSE and Streamable HTTP transports are blocked until the MCP server is enabled in Settings (mcpEnabled) and the appropriate mcpTransport is selected. If the wrong transport is configured the route returns HTTP 400 with a hint to switch settings.

Authentication & Scopes

MCP tools are authenticated through API key scopes. Scope enforcement is centralized in open-sse/mcp-server/scopeEnforcement.ts. Each tool requires specific scopes:

Wildcard scopes are supported: read:* grants all read-scopes, * grants full access.

mcp:connect — narrow route capability (#7895)

Reaching the HTTP/SSE MCP transport (/api/mcp/*) from non-loopback requires the /api/mcp/ LOCAL_ONLY carve-out (see docs/security/ROUTE_GUARD_TIERS.md). Historically that carve-out only accepted a full manage/admin-scope API key — too broad for a caller that only needs to talk MCP. src/shared/constants/managementScopes.ts now exports MCP_CONNECT_SCOPE = "mcp:connect": an additive, narrow scope (same precedent as SELF_USAGE_SCOPE) that authorizes ONLY the /api/mcp/ bypass in src/server/authz/policies/management.ts — it grants no other management-route access and is deliberately kept OUT of MANAGEMENT_API_KEY_SCOPES. A key holding manage/admin still passes the carve-out unchanged; mcp:connect is a lower-privilege alternative for remote MCP-only callers, checked via hasMcpConnectOrManageScope().

Per-key HTTP scope binding (#7895)

Over HTTP/SSE, open-sse/mcp-server/httpTransport.ts now resolves the caller's real api_keys.scopes via resolveMcpCallerAuthInfo() (open-sse/mcp-server/httpAuthContext.ts) and passes it to the MCP SDK's transport.handleRequest(req, { authInfo }), so extra.authInfo.scopes reaching each tool call reflects the Bearer key's own scopes. scopeEnforcement.ts's resolveCallerScopeContext() already prioritized authInfo over the _meta and OMNIROUTE_MCP_SCOPES env fallback — this only populates that first, highest-priority source, which was previously unfed over HTTP. When no API key resolves (no header, invalid key), authInfo stays undefined and resolution falls through to the existing meta/env chain unchanged. This does NOT flip OMNIROUTE_MCP_ENFORCE_SCOPES's default — enforcement still has to be explicitly enabled; this change only makes the per-key path take precedence once it is. stdio has no per-caller identity (see mcpCallerIdentity.ts) and is unaffected — it stays on the _meta/env fallback chain.

Environment Variables

Description Compression

MCP tool, prompt, and resource registries can compress descriptions at registration/list time to reduce the metadata footprint exposed to clients (and therefore the prompt context cost). The implementation lives in open-sse/mcp-server/descriptionCompressor.ts and is wired into the MCP server via compressMcpRegistryMetadata inside createMcpServer().

• Compression runs over the description text using the Caveman ruleset (getRulesForContext("all", "full")) with preserved-block extraction (code spans, fenced blocks, etc.) so structural content is not altered.
• Toggle per-deployment via the compression.mcpDescriptionCompressionEnabled value in the key_value settings table (default: enabled) — exposed in the UI as Analytics → MCP description compression.
• Toggle process-wide via either OMNIROUTE_MCP_COMPRESS_DESCRIPTIONS=false or OMNIROUTE_MCP_DESCRIPTION_COMPRESSION=false.
• Realtime stats are surfaced via omniroute_compression_status under analytics.mcpDescriptionCompression and tagged source: "mcp_metadata_estimate" to disambiguate from real provider usage receipts.

Tool Cardinality Reduction (F4.3)

Description compression shrinks each tool's metadata; tool-cardinality reduction goes one step further by reducing how many tools are announced at all. Advertising fewer tools in the tools/list manifest cuts the per-request token cost the client's model pays for the tool catalog ("layer 5" compression). The implementation is a pure, stateless filter in open-sse/mcp-server/toolCardinality.ts (reduceToolManifest), wired into the registration loop in createMcpServer() (open-sse/mcp-server/server.ts).

Opt-in, off by default. The filter only runs when at least one of two environment variables is set; with neither set, all 105 tools are announced unchanged.

deny takes priority over allow. Names are comma-separated, trimmed, and empty entries are ignored. Examples:

# Drop two tools from the catalog
MCP_TOOL_DENY="omniroute_get_health,omniroute_list_combos" omniroute --mcp

# Announce only the routing + quota tools (allow-list mode)
MCP_TOOL_ALLOW="omniroute_route_request,omniroute_check_quota" omniroute --mcp

How filtered tools are removed: registration always succeeds; a tool the profile rejects is then .disable()d on the MCP SDK handle, so it never appears in tools/list but the wiring stays intact (clean enable/disable, no re-registration). The profile parser is readMcpToolProfileFromEnv(process.env), which returns null (no filtering) when both vars are empty.

The richer ToolProfile shape behind reduceToolManifest also supports scope-intersection filtering (allowScopes, with read:*-style wildcard matching) and a deterministic maxTools cap, but those two knobs need the full manifest at registration time and are not exposed through the environment variables today (a tools/list-level hook is a tracked follow-up). estimateManifestTokens() is available to compare the manifest token cost before and after reduction.

Runtime Heartbeat

The stdio transport persists liveness to ${DATA_DIR}/runtime/mcp-heartbeat.json every 5 seconds. The dashboard (/api/mcp/status) reads this file plus PID liveness to derive online. HTTP transports report state from in-process getMcpHttpStatus() instead (no file write).

The heartbeat snapshot contains:

{
  "pid": 12345,
  "startedAt": "2026-05-13T12:34:56.000Z",
  "lastHeartbeatAt": "2026-05-13T12:35:01.000Z",
  "version": "1.8.1",
  "transport": "stdio",
  "scopesEnforced": false,
  "allowedScopes": [],
  "toolCount": 43
}

Audit Logging

Every tool call is logged to the SQLite mcp_tool_audit table by open-sse/mcp-server/audit.ts:

• Tool name, arguments (hashed/truncated as per-tool auditLevel), result
• Duration in ms, success/failure flag, error message (when applicable)
• API key hash, timestamp
• Scope denials are logged as scope_denied:<reason> with the missing scope list

Use the dashboard or the /api/mcp/audit and /api/mcp/audit/stats REST endpoints to inspect recent calls.

Files