OmniRoute Embedded MCP Server: Architecture, Tools, and Implementation Guide

The OmniRoute embedded MCP server exposes the router's entire functionality as a Model-Context-Protocol API at /api/mcp, enabling AI agents to execute 30+ tools—including health checks, web search, and routing configuration—through Zod-validated, JWT-scoped JSON-RPC calls.

OmniRoute bundles a complete Model-Context-Protocol (MCP) implementation that transforms the AI router into a programmable assistant. Located in the open-sse/mcp-server/ directory according to the source code, this embedded server validates incoming requests with Zod schemas, enforces fine-grained permissions via JWT scopes, and exposes both essential operational tools and advanced internal services to autonomous agents and IDE extensions.

Core Architecture Components

The MCP server follows a middleware pattern built on an Express-like HTTP handler. Each component handles a specific stage of the request lifecycle, from initial validation to authorization and dispatch.

HTTP Entry Point and Request Handling

The file open-sse/mcp-server/server.ts creates the main HTTP handler that listens on /api/mcp. This entry point extracts the tool name from the JSON body, validates inputs against Zod schemas, and dispatches calls to the appropriate tool implementation. The server accepts POST requests containing a JSON-RPC-style payload:

{
  "tool": "omniroute_get_health",
  "input": {}
}

After validation, the server returns typed JSON output and logs the interaction based on the tool's configured audit level.

Tool Registry and Discovery

The open-sse/mcp-server/toolSearch/register.ts module maintains a global registry of all available tools. At startup, every tool definition—including Zod input/output schemas, descriptions, required scopes, and audit levels—is loaded into memory. Agents can query the /tool/search endpoint to discover capabilities dynamically, receiving a complete catalog of callable functions along with their parameter requirements.

Scope Enforcement and Authorization

Before any tool executes, open-sse/mcp-server/scopeEnforcement.ts inspects the caller's JWT for required permissions. Each tool declares necessary scopes such as read:health or execute:search in its definition. Requests lacking the appropriate scopes receive a 403 Forbidden response. The system also supports audit levels (basic, full, none) that determine whether requests are logged to the mcp_audit table for compliance tracking.

Essential Phase 1 Tools

Phase 1 tools are defined in open-sse/mcp-server/schemas/tools.ts and cover core operational, monitoring, and routing functions. These tools proxy existing OmniRoute REST endpoints while providing type-safe interfaces for AI agents.

Health and System Monitoring

• omniroute_get_health: Returns uptime, memory usage, circuit-breaker state, rate-limit status, cache statistics, and any degraded subsystems. Proxies /api/monitoring/health and /api/resilience.
• omniroute_db_health_check: Verifies SQLite database health, schema version, and migration status.
• omniroute_cache_stats and omniroute_cache_flush: Report hit/miss counters and clear the in-memory or Redis cache.

Routing and Configuration Management

• omniroute_list_combos: Lists all configured combo chains (model pipelines) with optional performance metrics from /api/combos.
• omniroute_switch_combo: Enables or disables a specific combo via the combo management API.
• omniroute_create_combo: Registers new combos with model lists and routing strategies.
• omniroute_set_routing_strategy: Changes the global strategy to priority, weighted, fill-first, or custom algorithms.
• omniroute_set_resilience_profile: Adjusts circuit-breaker thresholds and cooldown periods.
• omniroute_route_request: Sends chat-completion requests through the full routing pipeline, handling combo selection, budget limits, and role hints by calling /v1/chat/completions.

Search and Content Fetching

• omniroute_web_search: Executes web searches through OmniRoute's gateway, supporting providers like Serper, Brave, and Perplexity via /v1/search.
• omniroute_x_search: Searches X/Twitter content via SuperGrok or X-Quik backends.
• omniroute_web_fetch: Retrieves URL content as markdown, HTML, or screenshots using Firecrawl or Jina-Reader.

Analytics and Debugging

• omniroute_cost_report: Generates cost analytics for sessions, days, weeks, or months with provider and model breakdowns.
• omniroute_check_quota: Reports API quota usage per provider, token health, and reset timing.
• omniroute_simulate_route: Simulates routing decisions without invoking providers, useful for debugging configuration changes.
• omniroute_explain_route: Produces human-readable explanations of routing decisions for specific requests.

Advanced Phase 2 Tools

Advanced tools reside in open-sse/mcp-server/tools/advancedTools.ts and expose internal OmniRoute services. These utilities are gated by higher audit levels (full) and typically require admin scopes.

• Memory management: Tools for searching, adding, and clearing vector store entries interact with the internal memory system.
• Pool management: Monitor and warm browser-pool resources, or reset pool states.
• Plugin operations: Install, reload, or disable OmniRoute plugins dynamically.
• External integrations: Read and write notes from Obsidian and Notion workspaces.
• Gamification: Fetch or update user-level scores and achievement data.
• Compression utilities: Handle large payload compression and decompression.
• Agent discovery: Query which cloud agents and skills are available for delegation.

Additionally, open-sse/mcp-server/tools/pickFastestModel.ts provides a utility for selecting the fastest available provider for a given request, while open-sse/mcp-server/runtimeHeartbeat.ts maintains the server's liveness and reports periodic health to the main router process.

Tool Execution Flow

When an AI agent or IDE extension invokes the MCP server, the request flows through four distinct stages:

1. Discovery: The client queries /tool/search to retrieve available tools and their schemas from the registry in register.ts.
2. Validation: The client POSTs to /api/mcp with a tool name and input object. The server validates the input against Zod schemas defined in the tool definition.
3. Authorization: scopeEnforcement.ts validates that the JWT contains the required scopes (e.g., execute:search for web search tools).
4. Execution and Audit: The server dispatches to the underlying OmniRoute API or internal service, logs the interaction based on the tool's audit level, and returns the typed result.

Implementation Examples

Calling Tools from Node.js

Agents can invoke tools directly via HTTP POST requests to the MCP endpoint:

import fetch from "node-fetch";

async function callMcp<TInput, TOutput>(tool: string, input: TInput) {
  const resp = await fetch("http://localhost:20128/api/mcp", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.OMNIRoute_JWT}`, // must contain required scopes
    },
    body: JSON.stringify({ tool, input }),
  });

  if (!resp.ok) throw new Error(`MCP error ${resp.status}`);
  const data = (await resp.json()) as TOutput;
  return data;
}

// Example: get health status
callMcp("omniroute_get_health", {})
  .then((info) => console.log("Health:", info))
  .catch(console.error);

Integrating with LLM Prompts

Large language models can generate MCP tool calls that clients execute on their behalf:

const prompt = `
Please look up the latest GPU pricing. Use the MCP tool:
{
  "tool": "omniroute_web_search",
  "input": { "query": "latest NVIDIA GPU pricing 2024", "max_results": 3 }
}
`;

The LLM outputs the JSON-RPC structure, which the host application extracts and forwards to POST /api/mcp, receiving structured search results for the model to process.

Summary

• The OmniRoute embedded MCP server exposes the router as a first-class toolset via /api/mcp, using JSON-RPC-style calls validated by Zod schemas.
• Phase 1 tools in open-sse/mcp-server/schemas/tools.ts provide essential operations: health monitoring, combo management, web search, and cost analytics.
• Phase 2 tools in open-sse/mcp-server/tools/advancedTools.ts expose internal services like memory search, browser pools, and plugin management, requiring elevated permissions.
• Scope enforcement via open-sse/mcp-server/scopeEnforcement.ts ensures JWT-authorized access with granular permissions like read:health or execute:search.
• Audit levels (basic, full, none) and the mcp_audit table provide compliance logging for regulated environments.

Frequently Asked Questions

What is the Model-Context-Protocol (MCP) server in OmniRoute?

The MCP server is an embedded HTTP API within OmniRoute—located under open-sse/mcp-server/—that implements the Model-Context-Protocol specification. It allows AI agents to treat the router itself as a tool provider, enabling programmatic access to routing decisions, health metrics, and external integrations through a standardized JSON-RPC interface.

How does the MCP server authenticate requests?

Authentication occurs through JWT tokens passed in the Authorization header. Before executing any tool, open-sse/mcp-server/scopeEnforcement.ts verifies that the token contains the required scopes defined in the tool's schema (such as admin for advanced tools or read:health for monitoring). Unauthorized requests receive a 403 Forbidden response.

What distinguishes Phase 1 from Phase 2 tools?

Phase 1 tools—defined in open-sse/mcp-server/schemas/tools.ts—cover core operational needs like health checks, routing configuration, and web search. Phase 2 tools—located in open-sse/mcp-server/tools/advancedTools.ts—expose internal infrastructure including vector memory, browser pools, and plugin systems. Phase 2 tools require higher audit levels (full) and administrative scopes.

How can AI agents discover available tools programmatically?

Agents query the /tool/search endpoint, which is backed by the registry in open-sse/mcp-server/toolSearch/register.ts. This returns a complete catalog of all registered tools, including their Zod input/output schemas, descriptions, required scopes, and audit levels, enabling dynamic capability discovery without hard-coding tool names.

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