# How OmniRoute MCP Server Manages 109 Tools Across Three Transports

> Discover how OmniRoute MCP Server efficiently manages 109 tools across STDIO, HTTP, and SSE transports using its modular IO9 catalog and runtime flags for seamless operation.

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

---

**The OmniRoute MCP Server orchestrates its 109 tools through a modular IO9 catalog system defined in [`schemas/tools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/schemas/tools.ts) and switches between STDIO, Streamable-HTTP, and SSE transports via runtime flags in [`server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.

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

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

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/descriptionCompressor.ts)** when the database flag `mcpDescriptionCompressionEnabled` is active. The **[`runtimeHeartbeat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

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

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

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

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/schemas/tools.ts) and dynamic registration logic in [`server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/mcpCallerIdentity.ts)) and HTTP headers for web transports (handled by [`httpAuthContext.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/descriptionCompressor.ts) and health monitoring via [`runtimeHeartbeat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/mcpCallerIdentity.ts). For **HTTP and SSE transports**, it parses bearer tokens, API keys, and cookies from request headers using [`httpAuthContext.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.