How OmniRoute MCP Server Manages 109 Tools Across Three Transports

The OmniRoute MCP Server orchestrates its 109 tools through a modular IO9 catalog system defined in schemas/tools.ts and switches between STDIO, Streamable-HTTP, and SSE transports via runtime flags in server.ts.

The OmniRoute MCP Server, located in the diegosouzapw/OmniRoute repository, provides a production-grade Model-Context-Protocol runtime that balances an extensive tool ecosystem with flexible communication layers. This architecture enables AI clients to invoke routing, memory, and integration tools through their preferred transport mechanism while maintaining consistent authentication and scope enforcement.

Tool Registration Architecture

The IO9 Catalog and Tool Definitions

The server centralizes its tool definitions in src/open-sse/mcp-server/schemas/tools.ts, which exports a master object containing metadata and Zod input schemas for every available tool. This catalog—internally referred to as the "IO9" collection—includes 109 distinct tools spanning categories like core routing, provider management, memory systems, and third-party integrations.

// src/open-sse/mcp-server/schemas/tools.ts
export const MCP_TOOLS = {
  getComboMetrics: { input: getComboMetricsInput, /* ... */ },
  routeRequest:     { input: routeRequestInput,     /* ... */ },
  pickFastestModel: { input: pickFastestModelInput, /* ... */ },
  // ... 100+ additional definitions
};

Dynamic Registration with Scope Enforcement

During initialization in src/open-sse/mcp-server/server.ts, the server binds each catalog definition to a concrete handler through a registration wrapper that enforces security and logging policies. The code patches the native registerTool method to inject scope validation and error sanitization before the actual tool execution.

// src/open-sse/mcp-server/server.ts
const registerTool = server.registerTool.bind(server);

server.registerTool = (name, config, handler) => {
  const metadata = { ...config, name };
  
  const filteredHandler = async (input, extra) => {
    if (MCP_ENFORCE_SCOPES) {
      await evaluateToolScopes(name, extra);
    }
    return handler(input, extra);
  };
  
  return registerTool(name, metadata, filteredHandler as never);
};

Following this shim setup, the server proceeds to register all 109 tools explicitly. The registration calls begin around line 760 in server.ts and cover tool groups including:

• Core routing: createCombo, bestComboForTask, pickFastestModel
• Provider management: checkQuota, getProviderMetrics, syncPricing
• Memory and data: memoryTools, localCorpusTools
• Productivity integrations: githubSkillTools, notionTools, obsidianTools

The utility toolCount.ts maintains an accurate tally of registered tools, including grouped collections like skillTools and pluginTools, which the server uses for diagnostics and manifest size enforcement.

Transport Layer Implementation

STDIO Transport for Local Execution

When the server detects the --mcp command-line flag, it initializes the STDIO transport using the @modelcontextprotocol/sdk/server/stdio.js implementation. This mode operates without an HTTP context, making it ideal for local scripting and command-line integrations.

// src/open-sse/mcp-server/server.ts
if (process.argv.includes("--mcp")) {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

In this mode, authentication relies on environment variables (OMNIROUTE_API_KEY or ROUTER_API_KEY), resolved through mcpCallerIdentity.ts when the standard httpAuthContext is unavailable.

Streamable-HTTP Transport

Without the --mcp flag, the server boots the Streamable-HTTP transport defined in src/open-sse/mcp-server/httpTransport.ts. This transport creates a WebStandardStreamableHTTPServerTransport instance that listens on a configurable port (defaulting to PORT environment variable).

The transport handles two primary request types:

• POST requests to /api/mcp for standard JSON-RPC tool invocations
• GET requests with Accept: text/event-stream for SSE connections

Each request passes through httpAuthContext.ts, which extracts bearer tokens, API keys, or cookies and injects them into the authInfo object used for tool scoping.

SSE Transport for Streaming Responses

The SSE transport layers on top of the Streamable-HTTP implementation. When a client connects with an Accept: text/event-stream header, the transport switches to streaming mode, yielding incremental tool results through a persistent connection.

For large payloads, the server automatically invokes descriptionCompressor.ts when the database flag mcpDescriptionCompressionEnabled is active. The runtimeHeartbeat.ts module monitors transport health, emitting periodic heartbeat messages to aid in debugging connection stability.

Server Startup and Transport Selection

The boot sequence follows a deterministic flow that first registers all tool handlers, then selects the appropriate transport based on runtime arguments:

// Conceptual flow from src/open-sse/mcp-server/server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { startHttpTransport } from "./httpTransport.ts";

async function bootstrap() {
  const server = new McpServer();
  
  // 1. Register all 109 tools from IO9 catalog
  // (Registration loop begins ~line 760 in server.ts)
  
  // 2. Select transport mode
  if (process.argv.includes("--mcp")) {
    const transport = new StdioServerTransport();
    await server.connect(transport);
    console.log("STDIO transport active");
  } else {
    const { transport } = await startHttpTransport();
    await server.connect(transport);
    console.log("HTTP/SSE transport active on port", process.env.PORT || 20128);
  }
}

Executing omniroute --mcp spawns the STDIO transport, while omniroute alone initializes the HTTP/SSE transport on the configured port.

Practical Implementation Examples

Invoking Tools via HTTP POST

Clients interact with the HTTP transport by sending authenticated POST requests to the RPC endpoint:

const response = await fetch("http://localhost:20128/api/mcp", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${process.env.OMNIROUTE_API_KEY}`,
  },
  body: JSON.stringify({
    tool: "pickFastestModel",
    input: { modelIds: ["gpt-4", "claude-2"] },
  }),
});

const result = await response.json();
console.log(result);

Consuming SSE Streams

For real-time tool outputs, clients connect to the SSE endpoint:

const evtSource = new EventSource(
  "http://localhost:20128/api/mcp?tool=explainRoute&input=%7B%7D"
);

evtSource.onmessage = (event) => {
  console.log("Stream chunk:", event.data);
};

evtSource.onerror = (error) => {
  console.error("SSE connection error:", error);
};

Registering Custom Tools

Developers extend the server by registering additional tools during bootstrap:

// Custom tool implementation
async function myAnalyticsHandler(input: unknown, extra: McpToolExtraLike) {
  const validatedInput = mySchema.parse(input);
  // ... business logic ...
  return { result: "Analysis complete", data: validatedInput };
}

// Registration during server setup
server.registerTool(
  "analyzeCustomMetrics",
  {
    input: z.object({ query: z.string(), limit: z.number().optional() }),
    description: "Perform custom analytics on routing data",
  },
  myAnalyticsHandler
);

Summary

• The OmniRoute MCP Server manages 109 tools through a centralized IO9 catalog in schemas/tools.ts and dynamic registration logic in server.ts that wraps handlers with scope enforcement and logging.
• Three transport modes—STDIO (via --mcp), Streamable-HTTP, and SSE—provide flexibility for local scripting, REST API calls, and streaming interactions respectively.
• Authentication context shifts based on transport: environment variables for STDIO (handled by mcpCallerIdentity.ts) and HTTP headers for web transports (handled by httpAuthContext.ts).
• Tool categories span core routing, provider quotas, memory systems, and third-party integrations like GitHub and Notion, all registered explicitly in the server bootstrap sequence.
• Automatic compression via descriptionCompressor.ts and health monitoring via runtimeHeartbeat.ts optimize performance for high-volume streaming scenarios.

Frequently Asked Questions

How does OmniRoute MCP Server authenticate requests across different transports?

The server uses context-aware authentication resolution. For STDIO transport, it extracts credentials from the OMNIROUTE_API_KEY or ROUTER_API_KEY environment variables via mcpCallerIdentity.ts. For HTTP and SSE transports, it parses bearer tokens, API keys, and cookies from request headers using httpAuthContext.ts, injecting the results into an authInfo object available to all tool handlers.

What is the IO9 tool catalog in the OmniRoute MCP Server?

The IO9 catalog is the internal designation for the comprehensive tool registry defined in src/open-sse/mcp-server/schemas/tools.ts. This module exports the MCP_TOOLS object containing 109 tool definitions, each specifying a Zod input schema, description, and metadata. The server dynamically binds these definitions to handler implementations during startup, supporting categories ranging from core routing algorithms to productivity integrations like Obsidian and Notion.

Can I add custom tools to the OmniRoute MCP Server without modifying core files?

Yes. While the 109 built-in tools are registered in server.ts, the architecture supports importing custom tool modules and registering them via server.registerTool() during the bootstrap sequence. Each registration requires a unique name, a Zod schema for input validation, and an async handler function that receives the parsed input and an McpToolExtraLike context object containing authentication and request metadata.

What is the difference between Streamable-HTTP and SSE transports in OmniRoute?

The Streamable-HTTP transport handles standard request-response cycles via POST requests to /api/mcp. The SSE transport utilizes the same underlying HTTP server but activates when a client sends a GET request with Accept: text/event-stream, establishing a persistent connection for streaming partial results. Both transports share the same authentication pipeline and port configuration, with the SSE layer automatically compressing large payloads when mcpDescriptionCompressionEnabled is set to true.

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