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

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 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
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 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 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 provides reference implementations for multiple languages.

Python Agent Workflow

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

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:

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:

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: Entry point that sets up stdio transport and registers all tool handlers
• index.ts: Barrel export for the MCP module, enabling other components (such as the A2A server) to import the runtime
• scopeEnforcement.ts: Implements fine-grained scope checks against environment variables
• audit.ts: Handles SHA-256 input hashing and SQLite audit logging
• schemas/tools.ts: Zod schemas for all tool inputs and outputs
• tools/advancedTools.ts: Handlers for Phase 2 advanced tools
• __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 provides mandatory access control mapping tools to specific read/write permissions
• Audit logging via 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

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 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.

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