How the MCP Server in OmniRoute Handles Tools and Transport Modes

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 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 filters available tools based on environment-driven security policies, while manifest reduction in toolCardinality.ts applies runtime profiles to limit tool cardinality.

Auxiliary systems include runtimeHeartbeat.ts for process keepalive and 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 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. 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, the server imports specialized tool sets spanning memory management, skill execution, and external integrations:

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. 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 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 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 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:

omniroute mcp --transport stdio

Once running, submit requests as single JSON lines:

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

The server responds via stdout with structured results:

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

Calling Tools via HTTP

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

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

The response includes tool-specific results:

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

Configuring Tool Profiles

Restrict tool availability using environment variables before server startup:

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, 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.
• 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 uses StdioServerTransport for line-delimited JSON interaction via stdin/stdout, while the HTTP transport in 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. Additionally, 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 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 (core server setup), httpTransport.ts (HTTP handling), scopeEnforcement.ts (security validation), and toolCardinality.ts (manifest filtering). Individual tool implementations live in the tools/ subdirectory, including memoryTools.ts, poolTools.ts, and skillTools.ts.

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