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

> Learn to set up the OmniRoute MCP server and its 105+ tools for agent orchestration. Enable MCP, choose transport, create API keys, and start orchestrating agents.

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

---

**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/main/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/main/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/main/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/main/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

```bash

# 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/main/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

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

```javascript
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

```bash

# 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

```typescript
// 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:

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

```

### Remote Access with Narrow `mcp:connect` Scope

```bash
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/main/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/main/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/main/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/main/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/main/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/main/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/main/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/main/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/main/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/main/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/main/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/main/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/main/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.