# How the OmniRoute MCP Server Functions with Tools, Scopes, and Transports

> Discover how the OmniRoute MCP server centralizes tool execution. Learn about its independent layers for tool cataloging, scope access control, and multi-transport communication.

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

---

**The OmniRoute MCP (Model Context Protocol) server centralizes tool execution by separating tool cataloging, scope-based access control, and multi-transport communication into three independent layers.**

This architecture allows the diegosouzapw/OmniRoute repository to expose a unified toolset across HTTP, STDIO, and streaming interfaces while enforcing strict security boundaries. Every tool is discoverable via a generated catalog, protected by scope checks, and reachable through any supported transport without code changes.

## Tool Catalog and Signatures

All OmniRoute MCP tools reside in `open-sse/mcp-server/tools/` and follow a standardized registration pattern.

The **catalog** is built at server startup in [`catalog.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/catalog.ts), which aggregates tool definitions from individual modules like [`skillTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/skillTools.ts), [`memoryTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/memoryTools.ts), and [`pluginTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/pluginTools.ts). Each tool provides:

- A **Zod schema** defined in [`schemas/tools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/schemas/tools.ts) for input validation
- A **signature** exported from [`toolSearch/signature.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/toolSearch/signature.ts) describing parameters, return types, and metadata
- A concrete implementation exported from its tool module

Tool resolution happens through [`toolSearch/search.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/toolSearch/search.ts), which indexes tools for fast lookup by name or partial match.

```typescript
// HTTP client call to invoke a tool via JSON-RPC 2.0
import fetch from 'node-fetch';

const response = await fetch('http://localhost:20128/api/mcp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'pickFastestModel',
    params: { models: ['gpt-4', 'claude-v2'] },
  }),
});

const result = await response.json();

```

## Scope Enforcement Architecture

Before any tool executes, OmniRoute validates the caller's privileges through [`scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scopeEnforcement.ts). This security layer prevents unauthorized access to sensitive operations.

### Identity Extraction

The [`mcpCallerIdentity.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/mcpCallerIdentity.ts) module extracts authentication context from incoming requests—whether from HTTP headers, STDIO environment variables, or stream metadata.

### Scope Checking

Scopes are **logical domains** grouping related capabilities:

- `skill` — Invoke AI skills and model routing
- `plugin` — Install and manage plugins
- `memory` — Access vector stores and embeddings
- `github` — Repository operations
- `obsidian` — Knowledge base integration

Scopes can be further restricted to **specific transports** or **client types**. The `enforceScope(caller, requiredScope)` function in [`scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scopeEnforcement.ts) throws a standardized error via `buildErrorBody()` on authorization failure.

```typescript
// Tool implementation with mandatory scope check
import { enforceScope } from './scopeEnforcement';
import { getCallerIdentity } from './mcpCallerIdentity';

export async function pickFastestModel(params, ctx) {
  const caller = await getCallerIdentity(ctx);
  
  // 'combo' scope required for model comparison tools
  enforceScope(caller, 'combo');
  
  // Tool logic executes only after authorization
  const fastest = await benchmarkModels(params.models);
  return { model: fastest.name, latency: fastest.latencyMs };
}

```

## Supported Transports

OmniRoute MCP abstracts transport details behind a common request-handler interface, allowing tools to remain transport-agnostic.

### HTTP Transport

The primary transport for browser clients and external APIs, implemented in [`httpTransport.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/httpTransport.ts). Handles standard JSON-RPC 2.0 over HTTP/HTTPS with full streaming support for large payloads.

### STDIO Transport

Used by the CLI in `src/bin/`, this transport pipes JSON-RPC messages over stdin/stdout. Enables shell scripts and subprocess invocations without network dependencies.

### Streamable HTTP Transport

An enhanced HTTP mode using chunked transfer encoding for real-time streaming of embeddings, file uploads, and long-running operations. Implemented as extensions in [`httpTransport.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/httpTransport.ts) with dedicated streaming helpers.

```typescript
// Custom WebSocket transport implementation
import { createTransport } from '@omniroute/open-sse/mcp-server';

export const wsTransport = createTransport({
  send: (msg) => ws.send(JSON.stringify(msg)),
  receive: (handler) => ws.on('message', (data) => handler(JSON.parse(data))),
});

```

## Request Processing Flow

A complete OmniRoute MCP request travels through this pipeline:

1. **Client** initiates via HTTP, STDIO, or streamable connection
2. **Transport layer** deserializes JSON-RPC and normalizes context
3. [`mcpCallerIdentity.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/mcpCallerIdentity.ts) extracts authentication identity
4. [`scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scopeEnforcement.ts) verifies required scopes against caller permissions
5. [`toolSearch/catalog.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/toolSearch/catalog.ts) resolves the tool by name
6. **Tool implementation** executes business logic
7. **Response** serializes through the same transport to client

This linear flow ensures consistent security and error handling regardless of entry point.

## Runtime Observability

The OmniRoute MCP server maintains operational visibility through two dedicated systems:

- [`runtimeHeartbeat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/runtimeHeartbeat.ts) — Periodic health-check reporting with version, loaded tool count, and transport status
- [`audit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/audit.ts) — Centralized logging of all tool invocations, including caller identity, parameters (sanitized), execution time, and errors

These modules support rate limiting and compliance requirements without polluting core tool logic.

## Key Source Files

| File | Purpose |
|------|---------|
| [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) | Entry point wiring transports, catalog, and request handlers |
| [`open-sse/mcp-server/catalog.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/catalog.ts) | Tool catalog construction from module discovery |
| [`open-sse/mcp-server/scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/scopeEnforcement.ts) | Access control and privilege validation |
| [`open-sse/mcp-server/httpTransport.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/httpTransport.ts) | HTTP and streaming HTTP implementations |
| [`open-sse/mcp-server/toolSearch/search.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/toolSearch/search.ts) | Tool resolution and signature matching |
| [`open-sse/mcp-server/tools/skillTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/tools/skillTools.ts) | Skill invocation tool implementations |
| [`open-sse/mcp-server/runtimeHeartbeat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/runtimeHeartbeat.ts) | Health monitoring and status reporting |
| [`open-sse/mcp-server/audit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/audit.ts) | Usage logging and audit trail generation |

## Summary

- **Tool cataloging**: Dynamic discovery from `tools/` modules with Zod schemas and searchable signatures
- **Scope enforcement**: Domain-based access control (`skill`, `plugin`, `memory`, etc.) validated via [`scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scopeEnforcement.ts)
- **Multi-transport support**: HTTP, STDIO, and streamable HTTP share a unified interface in [`httpTransport.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/httpTransport.ts)
- **Security-first design**: Identity extraction precedes authorization precedes tool execution in all cases
- **Operational transparency**: Heartbeats and audit logging without tool-side instrumentation

## Frequently Asked Questions

### What MCP protocol version does OmniRoute implement?

OmniRoute implements **JSON-RPC 2.0** as the message framing protocol across all transports. The server accepts standard JSON-RPC requests with `method` specifying the tool name and `params` containing validated arguments. Responses follow standard JSON-RPC success/error formats.

### Can custom scopes be added without modifying core files?

Yes. Scope definitions reside in configuration consumed by [`scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scopeEnforcement.ts). New scopes can be declared in tool signatures and enforced through the same `enforceScope()` API without changing the enforcement logic itself. The scope-to-transport mapping is also externally configurable.

### How does the STDIO transport handle authentication?

The STDIO transport extracts identity from **environment variables** set by the parent process, as implemented in [`mcpCallerIdentity.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/mcpCallerIdentity.ts). This allows CLI wrappers to inject tokens while keeping the transport implementation stateless. The same scope checks apply regardless of transport origin.

### What happens when a tool exceeds streaming bandwidth limits?

The streamable HTTP transport in [`httpTransport.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/httpTransport.ts) applies **chunked transfer encoding** with backpressure handling. If limits are exceeded, the transport emits an error response mid-stream rather than buffering indefinitely, preventing memory exhaustion on the server side.