# How the MCP Server Integrates with OmniRoute: Complete Guide to 37 Available Tools

> Discover how the MCP server integrates with OmniRoute, exposing 37 specialized tools for AI agents. Learn about fine-grained scope enforcement and audit logging with this complete guide.

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

---

**The MCP (Model Context Protocol) Server acts as a protocol adapter that wraps OmniRoute's HTTP API to expose 37 specialized tools for AI agents, enabling fine-grained scope enforcement and audit logging while translating MCP tool calls into standard OmniRoute HTTP requests.**

The OmniRoute MCP server provides a lightweight sidecar that runs alongside the main gateway at `diegosouzapw/OmniRoute`. This integration allows AI agents such as Claude Desktop, Cursor, and VS Code to interact with OmniRoute's routing engine through standardized MCP transports rather than raw HTTP calls, providing a secure bridge between agent interfaces and the gateway's capabilities.

## MCP Server Architecture and Integration Flow

The MCP server does not replace the main HTTP API (the `/v1/*` routes on port 20128). Instead, it wraps those APIs and exposes them as MCP tools that agents can invoke via standard MCP transports.

### Startup and Transport Initialization

The server launches either directly via `npx tsx open-sse/mcp-server/server.ts` or through the OmniRoute CLI using `omniroute --mcp`. This process creates a **stdio transport** that agent clients can spawn. The server expects `OMNIROUTE_BASE_URL` (defaulting to `http://localhost:20128`) and an optional `OMNIROUTE_API_KEY` to forward requests to the OmniRoute HTTP endpoints.

### Scope Enforcement and Security

Before any tool executes, [`open-sse/mcp-server/scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/scopeEnforcement.ts) validates the caller's permissions. The system checks `OMNIROUTE_MCP_ENFORCE_SCOPES` and `OMNIROUTE_MCP_SCOPES` environment variables. Scopes map one-to-one with the tool catalog, guaranteeing fine-grained multi-tenant access control where each tool requires specific read or write permissions.

### Tool Dispatch and Validation

Each tool functions as a thin wrapper that performs three operations:

1. Validates input using Zod schemas defined in [`open-sse/mcp-server/schemas/tools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/schemas/tools.ts)
2. Calls the appropriate OmniRoute API (such as `/api/combos` or `/v1/chat/completions`)
3. Returns the response in MCP-standard JSON-RPC-like format

### Audit Logging with SHA-256 Hashing

The [`open-sse/mcp-server/audit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/audit.ts) module provides traceability without leaking sensitive payloads. It hashes the raw input using SHA-256 and stores truncated output in the SQLite `mcp_tool_audit` table, creating an immutable record of tool invocations.

## Complete Catalog of 37 MCP Tools

The full catalog documented in [`docs/frameworks/MCP-SERVER.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/frameworks/MCP-SERVER.md) organizes tools into functional categories. While the following tables detail 23 representative tools, the complete runtime catalog contains 37 instruments covering health monitoring, routing, budgeting, caching, and compression.

### Phase 1: Essential Tools (8 Tools)

These foundational tools provide core gateway interaction capabilities:

- **`omniroute_get_health`** (scope: `read:health`): Returns gateway health, uptime, circuit-breaker status, rate-limit info, and cache statistics
- **`omniroute_list_combos`** (scope: `read:combos`): Lists all defined combos (model chains) with optional metrics
- **`omniroute_get_combo_metrics`** (scope: `read:combos`): Retrieves performance metrics for a specific combo
- **`omniroute_switch_combo`** (scope: `write:combos`): Enables or disables a combo for routing
- **`omniroute_check_quota`** (scope: `read:quota`): Shows remaining API quota per provider and token health
- **`omniroute_route_request`** (scope: `execute:completions`): Sends a chat-completion request through OmniRoute's routing engine
- **`omniroute_cost_report`** (scope: `read:usage`): Provides cost breakdowns by period (session/day/etc.) and provider
- **`omniroute_list_models_catalog`** (scope: `read:models`): Lists every model available across providers with capabilities and pricing

### Phase 2: Advanced Tools (8 Tools)

These instruments enable sophisticated routing decisions and resilience management:

- **`omniroute_simulate_route`** (scopes: `read:health`, `read:combos`): Dry-runs a routing decision, showing the fallback tree and estimated cost
- **`omniroute_set_budget_guard`** (scope: `write:budget`): Sets a session budget with actions (`degrade`, `block`, `alert`) when exceeded
- **`omniroute_set_resilience_profile`** (scope: `write:resilience`): Applies a resilience profile (`aggressive`, `balanced`, `conservative`)
- **`omniroute_test_combo`** (scopes: `execute:completions`, `read:combos`): Executes a real prompt against each provider in a combo, reporting latency and cost
- **`omniroute_get_provider_metrics`** (scope: `read:health`): Returns per-provider latency percentiles and circuit-breaker state
- **`omniroute_best_combo_for_task`** (scopes: `read:combos`, `read:health`): AI-driven recommendation of the optimal combo for a given task type
- **`omniroute_explain_route`** (scopes: `read:health`, `read:usage`): Explains why a request was routed to a particular provider, including scoring factors and fallbacks
- **`omniroute_get_session_snapshot`** (scope: `read:usage`): Retrieves a snapshot of the current session including costs, tokens, top models, and budget guard status

### Cache and Compression Tools (7 Tools)

These handlers manage OmniRoute's caching and compression layers:

- **`omniroute_cache_stats`** (scope: `read:cache`): Shows semantic-cache, prompt-cache, and idempotency statistics
- **`omniroute_cache_flush`** (scope: `write:cache`): Flushes cache entries globally or by signature/model
- **`omniroute_compression_status`** (scope: `read:compression`): Reports compression mode, analytics, and provider-aware cache stats
- **`omniroute_compression_configure`** (scope: `write:compression`): Adjusts compression mode and trigger thresholds at runtime
- **`omniroute_set_compression_engine`** (scope: `write:compression`): Switches the compression engine (Caveman, RTK, or stacked pipelines)
- **`omniroute_list_compression_combos`** (scope: `read:compression`): Lists named compression combos and their routing assignments
- **`omniroute_compression_combo_stats`** (scope: `read:compression`): Provides analytics grouped by compression combo and engine

## Implementation Examples

The [`open-sse/mcp-server/README.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/README.md) provides reference implementations for multiple languages.

### Python Agent Workflow

This example demonstrates health checks, combo listing, and request routing:

```python
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server = StdioServerParameters(
        command="npx",
        args=["tsx", "open-sse/mcp-server/server.ts"],
        env={"OMNIROUTE_BASE_URL": "http://localhost:20128"}
    )
    async with stdio_client(server) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # Health check

            health = await session.call_tool("omniroute_get_health", {})
            print("Health:", health.content[0].text)

            # List combos with metrics

            combos = await session.call_tool(
                "omniroute_list_combos", {"includeMetrics": True}
            )
            print("Combos:", combos.content[0].text)

            # Best combo for a coding task

            best = await session.call_tool(
                "omniroute_best_combo_for_task",
                {"taskType": "coding", "budgetConstraint": 0.5}
            )
            print("Best combo:", best.content[0].text)

            # Route a request through OmniRoute

            response = await session.call_tool(
                "omniroute_route_request",
                {
                    "model": "claude-sonnet-4",
                    "messages": [{"role": "user", "content": "Explain async/await"}],
                    "role": "coding"
                },
            )
            print("Response:", response.content[0].text)

asyncio.run(main())

```

### TypeScript Programmatic Integration

For Node.js environments, the SDK provides typed access:

```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

async function demo() {
  const transport = new StdioClientTransport({
    command: "npx",
    args: ["tsx", "open-sse/mcp-server/server.ts"],
    env: { OMNIROUTE_BASE_URL: "http://localhost:20128" },
  });

  const client = new Client({ name: "my-agent", version: "1.0.0" });
  await client.connect(transport);

  const quota = await client.callTool({
    name: "omniroute_check_quota",
    arguments: { provider: "claude" },
  });
  console.log("Claude quota:", quota.content);

  const result = await client.callTool({
    name: "omniroute_route_request",
    arguments: {
      model: "claude-sonnet-4",
      messages: [{ role: "user", content: "What is a promise in JS?" }],
    },
  });
  console.log("Result:", result.content);
  await client.close();
}
demo();

```

### Direct HTTP Bypass (Go)

Applications can bypass the MCP layer and call OmniRoute directly:

```go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func routeRequest(baseURL, model, prompt string) (string, error) {
    payload := map[string]any{
        "model": model,
        "messages": []map[string]string{
            {"role": "user", "content": prompt},
        },
        "stream": false,
    }
    body, _ := json.Marshal(payload)
    resp, err := http.Post(baseURL+"/v1/chat/completions", "application/json", bytes.NewReader(body))
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()
    data, _ := io.ReadAll(resp.Body)
    return string(data), nil
}

func main() {
    base := "http://localhost:20128"
    result, _ := routeRequest(base, "auto", "Hello from Go!")
    fmt.Println("Result:", result)
}

```

## Key Source Files

The implementation spans several critical files in the `open-sse/mcp-server` directory:

- **[`server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/server.ts)**: Entry point that sets up stdio transport and registers all tool handlers
- **[`index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/index.ts)**: Barrel export for the MCP module, enabling other components (such as the A2A server) to import the runtime
- **[`scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scopeEnforcement.ts)**: Implements fine-grained scope checks against environment variables
- **[`audit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/audit.ts)**: Handles SHA-256 input hashing and SQLite audit logging
- **[`schemas/tools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/schemas/tools.ts)**: Zod schemas for all tool inputs and outputs
- **[`tools/advancedTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tools/advancedTools.ts)**: Handlers for Phase 2 advanced tools
- **[`__tests__/essentialTools.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/__tests__/essentialTools.test.ts)**: Unit tests validating the essential tool set

## Summary

- The **MCP server** acts as a protocol adapter translating MCP tool calls into OmniRoute HTTP requests while maintaining the gateway's native `/v1/*` API intact
- **37 tools** are available across categories including health monitoring, combo management, routing execution, budget guards, and compression controls
- **Scope enforcement** in [`scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scopeEnforcement.ts) provides mandatory access control mapping tools to specific read/write permissions
- **Audit logging** via [`audit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/audit.ts) stores SHA-256 hashed inputs and truncated outputs in SQLite for security compliance
- The server supports **stdio and HTTP transports**, enabling integration with Claude Desktop, Cursor, VS Code, and custom agents
- Runtime tool discovery is available through the `list_tools` endpoint and documented in [`docs/frameworks/MCP-SERVER.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/frameworks/MCP-SERVER.md)

## Frequently Asked Questions

### How does the MCP server differ from using OmniRoute's HTTP API directly?

The MCP server provides a standardized protocol layer that AI agents understand natively. While direct HTTP calls require manual authentication and payload construction, the MCP server handles **scope enforcement**, **input validation via Zod schemas**, and **audit logging** automatically. It translates MCP's JSON-RPC-like format into standard OmniRoute HTTP requests, acting as a secure bridge rather than a replacement for the underlying API.

### What scopes are required for managing budgets and resilience profiles?

Budget management requires the **`write:budget`** scope to use `omniroute_set_budget_guard`, while resilience configuration requires **`write:resilience`** for `omniroute_set_resilience_profile`. These write scopes are distinct from read scopes like `read:usage` or `read:health`, ensuring that agents requesting cost reports cannot inadvertently modify budget constraints or resilience parameters.

### How does the audit system protect sensitive data while maintaining traceability?

The [`open-sse/mcp-server/audit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/audit.ts) module applies **SHA-256 hashing** to raw inputs before storage, creating cryptographic fingerprints without retaining the actual prompts or completions. It stores truncated outputs in the SQLite `mcp_tool_audit` table. This approach satisfies audit requirements for compliance and debugging while preventing the leakage of sensitive data such as API keys or proprietary prompts.

### Can the MCP server run independently of the main OmniRoute gateway?

No, the MCP server requires an active OmniRoute gateway. It relies on `OMNIROUTE_BASE_URL` (defaulting to `http://localhost:20128`) to forward all tool requests to the gateway's HTTP endpoints. The server functions as a sidecar process that depends on the gateway's `/v1/chat/completions`, `/api/combos`, and other routes to fulfill tool invocations.