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

> Explore the OmniRoute embedded MCP server architecture and tools. Exposes router functionality via a Model-Context-Protocol API for AI agent integration with 30+ tools.

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

---

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

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

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

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