# How the MCP Server in OmniRoute Handles Tools and Transport Modes

> Discover how the OmniRoute MCP server manages tools and transport modes using STDIO and HTTP, with environment variables for scope control. Centralize tool registration and enhance interaction.

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

---

**The MCP server in OmniRoute centralizes tool registration and exposes capabilities through dual transport layers—STDIO for CLI interaction and HTTP for networked clients—while enforcing granular scope controls via environment variables.**

OmniRoute's Model-Context-Protocol (MCP) server implementation lives in the `open-sse/mcp-server` directory of the diegosouzapw/OmniRoute repository. This server aggregates native capabilities into a unified tool catalog, allowing LLMs to invoke memory operations, skill executions, and resource management functions through a standardized interface that supports both local and remote connectivity.

## Core Architecture Components

The MCP server architecture consists of several specialized modules that handle transport, registration, and security. According to the OmniRoute source code, these components work together to provide a consistent interface regardless of client type.

The **McpServer** instance in [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) serves as the central registry, importing tool collections from specialized modules and routing incoming requests to appropriate handlers. **Transport layers** in the same file instantiate both `StdioServerTransport` for command-line interaction and `httpTransport` for REST API access. **Scope enforcement** logic in [`scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scopeEnforcement.ts) filters available tools based on environment-driven security policies, while **manifest reduction** in [`toolCardinality.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/toolCardinality.ts) applies runtime profiles to limit tool cardinality.

Auxiliary systems include [`runtimeHeartbeat.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/runtimeHeartbeat.ts) for process keepalive and [`audit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/audit.ts) for comprehensive invocation logging. This modular design ensures that transport mechanisms, security policies, and business logic remain decoupled.

## Transport Modes: STDIO and HTTP

OmniRoute supports two primary transport mechanisms that share the same underlying `McpServer` instance, ensuring consistent tool availability and policy enforcement across all clients.

### STDIO Transport

The STDIO transport enables CLI-style interaction by reading JSON-L lines from `process.stdin` and writing responses to `process.stdout`. When starting the server via `omniroute mcp --transport stdio`, the system initializes `StdioServerTransport` from [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) to handle line-delimited JSON requests directly from the terminal.

This mode facilitates local tool invocation where the LLM client runs on the same machine as the OmniRoute process, eliminating network overhead while maintaining full protocol compliance.

### HTTP Transport

The HTTP transport exposes the MCP endpoint over TCP via an Express-style handler implemented in [`open-sse/mcp-server/httpTransport.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/httpTransport.ts). This transport listens for POST requests containing JSON payloads, forwards them to the `McpServer.handleRequest` method, and returns structured responses.

Networked clients can reach the server at `http://localhost:20128/api/mcp`, making this transport suitable for distributed architectures where the LLM client runs independently from the OmniRoute backend.

## Tool Registration and Catalog Management

The server maintains a comprehensive tool registry that aggregates capabilities from multiple domain-specific collections.

### Tool Collections Import

Inside [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts), the server imports specialized tool sets spanning memory management, skill execution, and external integrations:

```typescript
import { memoryTools }      from "./tools/memoryTools.ts";
import { skillTools }       from "./tools/skillTools.ts";
import { agentSkillTools }  from "./tools/agentSkillTools.ts";
import { githubSkillTools } from "./tools/githubSkillTools.ts";
import { pluginTools }      from "./tools/pluginTools.ts";
import { compressionTools } from "./tools/compressionTools.ts";
import { poolTools }        from "./tools/poolTools.ts";
import { gamificationTools } from "./tools/gamificationTools.ts";
import { notionTools }      from "./tools/notionTools.ts";
import { obsidianTools }    from "./tools/obsidianTools.ts";
import { localCorpusTools } from "./tools/localCorpusTools.ts";

```

These imports merge into a single manifest alongside the base `MCP_TOOLS` definition, creating a unified catalog that the server exposes to clients.

### Dynamic Manifest Reduction

Before announcing available capabilities, the server processes the full tool list through `reduceToolManifest` in [`open-sse/mcp-server/toolCardinality.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/toolCardinality.ts). This function evaluates caller profiles to trim the manifest according to allow/deny lists and token limits.

The `readMcpToolProfileFromEnv` function reads three environment variables to configure these restrictions: `MCP_TOOL_ALLOW` (comma-separated permitted tools), `MCP_TOOL_DENY` (explicitly blocked tools), and `MCP_TOOL_MAX` (maximum tools to include). This filtering occurs at runtime, allowing operators to expose different capability subsets to different LLM instances without restarting the server.

## Scope Enforcement and Security

The MCP server implements defense-in-depth security through environment-driven scope validation.

When `OMNIROUTE_MCP_ENFORCE_SCOPES` is set to `true`, the server reads allowed scopes from the `OMNIROUTE_MCP_SCOPES` environment variable (comma-separated values). The validation logic in [`open-sse/mcp-server/scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/scopeEnforcement.ts) compares these permitted scopes against each tool's declared scope tags, filtering the manifest to include only tools with intersecting permissions.

This design enables sandboxing scenarios where restricted LLM clients access only safe memory tools, while privileged clients retain access to sensitive operations like GitHub integrations or system-level plugins.

## Tool Invocation Flow

The complete request lifecycle follows a standardized five-step process:

1. **Client Request**: A JSON payload containing `toolName` and arguments arrives via STDIO line or HTTP POST body.
2. **Transport Handling**: The transport layer extracts the payload and invokes `mcpServer.handleRequest`.
3. **Scope Verification**: [`scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scopeEnforcement.ts) validates the caller's scopes against the requested tool's requirements.
4. **Handler Execution**: Upon permission grant, the system calls the appropriate handler (e.g., `memoryTools.getMemory`) and wraps results in `TextToolResult` objects.
5. **Auditing**: [`audit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/audit.ts) records the invocation via `logToolCall` before returning the response through the transport layer.

This pipeline ensures that every tool call undergoes authentication, authorization, and logging before execution completes.

## Practical Usage Examples

### Starting the STDIO Transport

Launch the MCP server in CLI mode to accept piped JSON requests:

```bash
omniroute mcp --transport stdio

```

Once running, submit requests as single JSON lines:

```json
{ "toolName": "memory_get", "args": { "ownerId": "123" } }

```

The server responds via stdout with structured results:

```json
{ "result": "Here is the stored note…" }

```

### Calling Tools via HTTP

For networked clients, send POST requests to the HTTP endpoint:

```bash
curl -X POST http://localhost:20128/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"toolName":"pool_status","args":{}}'

```

The response includes tool-specific results:

```json
{
  "toolName":"pool_status",
  "result":{"totalSessions":12,"idleSessions":5}
}

```

### Configuring Tool Profiles

Restrict tool availability using environment variables before server startup:

```bash
export OMNIROUTE_MCP_ENFORCE_SCOPES=true
export OMNIROUTE_MCP_SCOPES=memory,skill

```

With these settings, the server announces only tools tagged with `memory` or `skill` scopes, effectively sandboxing the LLM client to safe operations.

## Summary

- The **MCP server** in OmniRoute centralizes tool management in [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts), aggregating capabilities from domain-specific modules like `memoryTools` and `poolTools`.
- **Dual transport support** via STDIO and HTTP allows both local CLI usage and remote API access, with both paths using the same underlying `McpServer` instance.
- **Security enforcement** relies on environment variables (`OMNIROUTE_MCP_ENFORCE_SCOPES`, `OMNIROUTE_MCP_SCOPES`) and dynamic manifest reduction through `reduceToolManifest`.
- The **invocation pipeline** includes transport handling, scope validation, handler execution, and comprehensive auditing via [`audit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/audit.ts).
- Operators can **sandbox LLM clients** by configuring tool profiles that limit available capabilities without code changes.

## Frequently Asked Questions

### What transport modes does OmniRoute's MCP Server support?

OmniRoute supports **STDIO** and **HTTP** transports. The STDIO transport in [`server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/server.ts) uses `StdioServerTransport` for line-delimited JSON interaction via stdin/stdout, while the HTTP transport in [`httpTransport.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/httpTransport.ts) exposes a POST endpoint at `/api/mcp` for networked clients. Both transports route requests through the same `McpServer` instance to ensure consistent behavior.

### How does OmniRoute enforce tool security and scoping?

Scope enforcement occurs through environment variables and runtime filtering. When `OMNIROUTE_MCP_ENFORCE_SCOPES` is enabled, the server reads permitted scopes from `OMNIROUTE_MCP_SCOPES` and validates each tool call against these permissions in [`scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scopeEnforcement.ts). Additionally, [`toolCardinality.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/toolCardinality.ts) performs manifest reduction based on `MCP_TOOL_ALLOW`, `MCP_TOOL_DENY`, and `MCP_TOOL_MAX` settings.

### Can I restrict which tools are available to specific LLM clients?

Yes. The `reduceToolManifest` function in [`open-sse/mcp-server/toolCardinality.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/toolCardinality.ts) dynamically filters the tool catalog at runtime based on caller profiles. By setting environment variables like `MCP_TOOL_ALLOW=memory_get,pool_status`, operators can expose only specific tools to particular clients without modifying the source code or restarting the server infrastructure.

### Where is the MCP server implementation located in the OmniRoute repository?

The implementation resides in the `open-sse/mcp-server` directory. Key files include [`server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/server.ts) (core server setup), [`httpTransport.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/httpTransport.ts) (HTTP handling), [`scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scopeEnforcement.ts) (security validation), and [`toolCardinality.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/toolCardinality.ts) (manifest filtering). Individual tool implementations live in the `tools/` subdirectory, including [`memoryTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/memoryTools.ts), [`poolTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/poolTools.ts), and [`skillTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/skillTools.ts).