How to Set Up the OmniRoute MCP Server with 105 Tools for Agent Orchestration

Enable MCP via OMNIROUTE_MCP_ENABLED=1, choose your transport (stdio, SSE, or streamable-HTTP), create an API key with the required scopes, and start OmniRoute to expose 105+ tools for external agent discovery and orchestration.

What Is the OmniRoute MCP Server?

OmniRoute ships a built-in Model Context Protocol (MCP) server that exposes 105 tools across three transport layers. These tools enable external agents to discover, invoke, and orchestrate the full OmniRoute stack—including routing, quotas, compression, memory, and the Agent Skills catalog.

According to the diegosouzapw/OmniRoute source code, the MCP server factory lives in [open-sse/mcp-server/server.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/mcp-server/server.ts), which registers every tool, applies description compression, and wires scope enforcement automatically.

Enable and Start the MCP Server

Step 1: Enable MCP

You have two options to activate the server:

• Environment variable: Set OMNIROUTE_MCP_ENABLED=1 before starting OmniRoute
• Settings UI: Toggle MCP enablement in the dashboard

The server auto-starts on launch once enabled.

Step 2: Choose Your Transport

The mcpTransport setting controls which transport layer is active (default: sse):

Transport	Best For	Entry Point
stdio	Desktop clients (Claude Desktop, Cursor)	Direct process I/O via [open-sse/mcp-server/server.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/mcp-server/server.ts)
sse	Browser agents needing EventSource streams	POST/GET /api/mcp/sse ([src/app/api/mcp/sse/route.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/app/api/mcp/sse/route.ts))
streamable-http	Multi-session HTTP clients with persistent sessions	POST/GET/DELETE /api/mcp/stream ([src/app/api/mcp/stream/route.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/app/api/mcp/stream/route.ts))

Step 3: Start OmniRoute

# STDIO transport for desktop integrations

omniroute --mcp

# HTTP transports (SSE or streamable) with dev server

omniroute --dev

Switching transports automatically closes existing sessions on other transports.

Authentication and Scope Configuration

All MCP calls require an API key with specific scopes. Missing scopes trigger a scope_denied audit entry, handled by [open-sse/mcp-server/scopeEnforcement.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/mcp-server/scopeEnforcement.ts).

Required Scopes by Tool Category

Scope	Required For
read:health	omniroute_get_health, omniroute_get_provider_metrics, omniroute_simulate_route
read:combos	omniroute_list_combos, omniroute_get_combo_metrics, omniroute_best_combo_for_task
write:combos	omniroute_switch_combo, omniroute_set_routing_strategy
execute:completions	omniroute_route_request, omniroute_test_combo
execute:search	omniroute_web_search
read:catalog	All Agent Skills tools (omniroute_agent_skills_*)
mcp:connect	Narrow scope for remote /api/mcp/* access without full manage privilege

Creating an API Key via REST

curl -X POST http://localhost:20128/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"scopes":["read:health","read:combos","execute:completions","read:catalog"]}'

The key policy enforcement is defined in [src/server/authz/policies/management.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/server/authz/policies/management.ts).

Core MCP Tools for Agent Orchestration

Each tool is registered in [open-sse/mcp-server/server.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/mcp-server/server.ts) via server.registerTool(), wrapped with withScopeEnforcement for authorization.

Tool	Purpose	Scope
omniroute_get_health	Verify server liveliness and circuit-breaker state	read:health
omniroute_list_combos	Discover available routing combos	read:combos
omniroute_best_combo_for_task	Get optimal combo recommendations for workloads	read:combos
omniroute_route_request	Send chat completions through OmniRoute's routing engine	execute:completions
omniroute_cost_report	Retrieve cost/token usage for budgeting agents	read:usage
omniroute_agent_skills_list	Pull the 42-entry Agent Skills catalog	read:catalog
omniroute_agent_skills_get	Fetch a single SKILL.md by skill ID	read:catalog
omniroute_agent_skills_coverage	Query documentation coverage statistics	read:catalog

The Agent Skills tools are implemented in [open-sse/mcp-server/tools/agentSkillTools.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/mcp-server/tools/agentSkillTools.ts).

Practical Code Examples for MCP Server Setup

Initialize an MCP Client (Node.js)

The MCP client library is bundled with OmniRoute—no extra dependencies required.

import { McpClient } from '@modelcontextprotocol/sdk/client/mcp.js';

const client = new McpClient({
  baseUrl: 'http://localhost:20128/api/mcp',
  apiKey: 'sk-…',               // API key with required scopes
  transport: 'sse',             // or 'stream', 'stdio'
});

// Verify server health
const health = await client.callTool('omniroute_get_health', {});
console.log(JSON.parse(health.content[0].text));

List Combos and Get Recommendations

# List all available combos

curl -H "Authorization: Bearer sk-…" \
     http://localhost:20128/api/mcp/tools | \
     jq '.tools[] | select(.name|contains("omniroute_list_combos"))'

# Request optimal combo for low-latency, low-cost chat

curl -X POST http://localhost:20128/api/mcp/stream \
     -H "Authorization: Bearer sk-…" \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc":"2.0",
       "id":1,
       "method":"omniroute_best_combo_for_task",
       "params":{
         "task":"chat",
         "budget":"low",
         "latency":"fast"
       }
     }'

Query the Agent Skills Catalog

// In an LLM system prompt, instruct the agent:
{
  "role": "assistant",
  "content": "Call `omniroute_agent_skills_list` to discover capabilities you can expose to users."
}

The response includes each skill's id, name, category, and rawUrl for direct GitHub fetch:

curl -L "$(jq -r '.skills[0].rawUrl' response.json)"

Remote Access with Narrow mcp:connect Scope

curl -i -H "Authorization: Bearer sk-…" \
  -H "Host: public-omniroute.example.com" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"omniroute_get_health","params":{}}' \
  https://public-omniroute.example.com/api/mcp/stream

Only keys with mcp:connect or manage bypass the LOCAL_ONLY route guard.

Key Source Files for MCP Server Configuration

File	Purpose
[open-sse/mcp-server/server.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/mcp-server/server.ts)	MCP server factory: creates McpServer, registers 105 tools, applies description compression
[open-sse/mcp-server/httpTransport.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/mcp-server/httpTransport.ts)	SSE and streamable-HTTP transports, session handling, auth extraction
[open-sse/mcp-server/scopeEnforcement.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/mcp-server/scopeEnforcement.ts)	Centralized scope verification via evaluateToolScopes
[open-sse/mcp-server/tools/agentSkillTools.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/mcp-server/tools/agentSkillTools.ts)	Agent Skills catalog tools (42 entries)
[src/app/api/mcp/status/route.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/app/api/mcp/status/route.ts)	/api/mcp/status endpoint for health, version, tool count
[src/app/api/mcp/tools/route.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/app/api/mcp/tools/route.ts)	Tool manifest for client SDKs
[src/app/api/mcp/audit/route.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/app/api/mcp/audit/route.ts)	Audit log endpoint for debugging scope denials
[docs/frameworks/MCP-SERVER.md](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/docs/frameworks/MCP-SERVER.md)	Official MCP server documentation
[docs/frameworks/AGENT-SKILLS.md](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/docs/frameworks/AGENT-SKILLS.md)	Agent Skills catalog documentation

Summary

• Enable MCP via environment variable (OMNIROUTE_MCP_ENABLED=1) or dashboard toggle
• Select a transport: stdio for desktop, sse for browsers, streamable-http for persistent sessions
• Provision an API key with minimal scopes matching your tool requirements
• Start OmniRoute with --mcp (stdio) or --dev (HTTP transports)
• Invoke tools via SDK client or direct HTTP/cURL using standard JSON-RPC 2.0
• Leverage the 42-entry Agent Skills catalog to let external agents self-discover capabilities

Frequently Asked Questions

How many tools does the OmniRoute MCP server expose?

The OmniRoute MCP server exposes 105 tools as of release v3.8.50. This total includes core routing tools, health monitoring, combo management, cost reporting, and the 42-entry Agent Skills catalog. The exact count is available at runtime via the /api/mcp/status endpoint ([src/app/api/mcp/status/route.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/app/api/mcp/status/route.ts)).

Can I use multiple transports simultaneously?

No. The mcpTransport setting selects a single active transport, and switching automatically terminates sessions on other transports. For hybrid deployments, run multiple OmniRoute instances with different transport configurations, or use the streamable-HTTP transport which supports multiple concurrent sessions via the mcp-session-id header.

What's the difference between mcp:connect and manage scopes?

The mcp:connect scope ([src/server/authz/policies/management.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/server/authz/policies/management.ts)) is a narrow permission that allows remote clients to reach /api/mcp/* endpoints without granting full administrative access. The manage scope provides blanket access to all management APIs. Use mcp:connect for least-privilege remote agent orchestration.

How do I debug scope denial errors?

Scope denials are logged as scope_denied audit entries. Query [src/app/api/mcp/audit/route.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/app/api/mcp/audit/route.ts) to retrieve recent audit events, or check the enforcement logic in [open-sse/mcp-server/scopeEnforcement.ts](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/mcp-server/scopeEnforcement.ts). The evaluateToolScopes function provides detailed caller context resolution for troubleshooting.

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