How to Set Up MCP Server Tools for OmniRoute: Complete Implementation Guide

OmniRoute bundles a full-featured MCP server with 104 built-in tools that can be exposed via SSE, stdio, or HTTP transports by initializing createMcpServer(), selecting your preferred transport mode, and enforcing fine-grained permissions through the OMNIROUTE_MCP_SCOPES environment variable.

The OmniRoute repository by diegosouzapw provides a production-ready MCP (Multi-Channel Provider) server implementation that consolidates routing, memory, and agent skills into a unified tool catalog. Setting up MCP server tools for OmniRoute requires understanding the server factory pattern in open-sse/mcp-server/server.ts, configuring your chosen transport layer, and implementing the scope-based security model.

Understanding the OmniRoute MCP Server Architecture

The MCP server implementation centers around the createMcpServer() factory function defined at line 618 in open-sse/mcp-server/server.ts. This function instantiates an McpServer object pre-loaded with 104 built-in tools spanning essential operations (phase 1) like health checks and routing, plus advanced capabilities (phase 2) including compression management and gamification.

The architecture supports three transport modes for different integration scenarios:

• HTTP: RESTful API consumption via the HttpTransport class
• stdio: Command-line and subprocess communication through startMcpStdio()
• SSE: Server-Sent Events for real-time streaming connections

Security enforcement occurs in open-sse/mcp-server/scopeEnforcement.ts, which validates incoming requests against declared permission scopes before allowing tool execution.

Step-by-Step Setup Guide

Step 1: Initialize the MCP Server Instance

Begin by importing and invoking the factory function to build the server instance. According to the OmniRoute source code in open-sse/mcp-server/server.ts, createMcpServer() constructs the server object and populates it with MCP_TOOLS—the master tool array defined in open-sse/mcp-server/schemas/tools.ts.

import { createMcpServer } from "@omniroute/open-sse/mcp-server/server.ts";

const server = createMcpServer(); // Implementation at line 618 in server.ts

This initialization automatically constructs MCP_TOOL_MAP for O(1) tool lookup by name and prepares the internal request router for incoming calls.

Step 2: Select and Configure Your Transport

Choose between transport modes based on your deployment context. For HTTP-based integrations, instantiate the HttpTransport class from open-sse/mcp-server/httpTransport.ts:

import { HttpTransport } from "@omniroute/open-sse/mcp-server/httpTransport.ts";

const http = new HttpTransport(server);
http.listen(3001, () => console.log("MCP HTTP listening on port 3001"));

For stdio mode—typically used when integrating with CLI agents or parent processes—use the entry point defined in open-sse/mcp-server/index.ts or the convenience CLI shortcut:

# From the OmniRoute repository root

npx omniroute --mcp

This command invokes startMcpStdio(createMcpServer()) internally, launching the server in stdio mode for immediate tool access via standard input/output streams.

Step 3: Configure Scope Enforcement

Before exposing the server to clients, configure the OMNIROUTE_MCP_SCOPES environment variable to define permission boundaries. The middleware implemented in open-sse/mcp-server/scopeEnforcement.ts intercepts each incoming request and validates the caller's scope claims against the tool's required permissions array. Only tools whose scopes intersect with the caller's granted permissions execute, preventing unauthorized access to sensitive operations.

Exploring the Tool Catalog

The complete tool inventory resides in open-sse/mcp-server/schemas/tools.ts, which aggregates specialized tool arrays into a deduplicated master list:

• CCR_MCP_TOOLS: Core routing and CCR operations
• memoryTools: Memory management and retrieval functions
• skillTools: Agent skill operations
• agentSkillTools: A2A (Agent-to-Agent) capabilities
• poolTools: Resource pool management

The file exports MCP_ESSENTIAL_TOOLS (phase 1) and MCP_ADVANCED_TOOLS (phase 2), ensuring each tool name remains unique across the catalog.

For runtime discovery, clients can query the public API endpoint implemented in src/app/api/mcp/tools/route.ts. Send a GET request to /api/mcp/tools to retrieve the complete catalog including tool names, implementation phases, and required permission scopes.

Practical Implementation Examples

Starting the HTTP Transport Server

Deploy the MCP server over HTTP for web-based integrations and remote tool invocation:

import { createMcpServer } from "@omniroute/open-sse/mcp-server/server.ts";
import { HttpTransport } from "@omniroute/open-sse/mcp-server/httpTransport.ts";

const server = createMcpServer();
const http = new HttpTransport(server);
http.listen(3001, () => console.log("MCP HTTP listening on port 3001"));

Launching via CLI stdio Transport

For local development or integration with agent systems requiring stdio communication:

npx omniroute --mcp

This executes the stdio transport starter defined in open-sse/mcp-server/index.ts, creating a persistent process that reads JSON-RPC messages from stdin and writes responses to stdout.

Invoking Tools Programmatically

Execute specific tools using the server's invokeTool method after initialization:

const server = createMcpServer();
const result = await server.invokeTool("omniroute_get_health", {});
console.log(result); // Returns: { status: "ok", version: "v3.8.50", ... }

Registering Custom Tools

Extend the built-in catalog with domain-specific tools using the registration API:

import { McpToolDefinition } from "@omniroute/open-sse/mcp-server/schemas/toolDefinition.ts";

const customTool: McpToolDefinition = {
  name: "my_custom_echo",
  description: "Echoes back the supplied payload",
  phase: 1,
  scopes: ["my.custom.scope"],
  handler: async ({ payload }) => ({ echoed: payload }),
};

const server = createMcpServer();
server.registerTool(customTool);

The registerTool method appends your tool to the internal MCP_TOOLS array and updates MCP_TOOL_MAP for immediate availability.

Summary

• Initialize the server using createMcpServer() from open-sse/mcp-server/server.ts (line 618) to preload 104 built-in tools automatically
• Choose transports between HTTP (HttpTransport), stdio (startMcpStdio), or SSE based on your integration architecture and security requirements
• Enforce security by configuring OMNIROUTE_MCP_SCOPES to validate permissions via the middleware in open-sse/mcp-server/scopeEnforcement.ts
• Discover tools dynamically through the GET /api/mcp/tools endpoint or inspect open-sse/mcp-server/schemas/tools.ts for the static catalog
• Extend functionality by registering custom tools with server.registerTool(), which automatically updates the internal tool map for O(1) lookup

Frequently Asked Questions

What transports does the OmniRoute MCP server support?

The OmniRoute MCP server supports three transports: stdio for command-line integration via startMcpStdio(), HTTP for RESTful API access through the HttpTransport class, and SSE for real-time streaming connections. The stdio mode launches via npx omniroute --mcp, while HTTP requires instantiating HttpTransport from open-sse/mcp-server/httpTransport.ts and calling listen().

How does scope enforcement work in OmniRoute MCP tools?

Each tool definition includes a scopes array defining required permissions. When a request arrives, the middleware in open-sse/mcp-server/scopeEnforcement.ts compares the caller's OMNIROUTE_MCP_SCOPES environment variable against the tool's required scopes. The request proceeds only if the caller possesses at least one matching scope, preventing unauthorized access to sensitive operations like pool management or agent skill modifications.

Can I add custom tools to the existing OmniRoute MCP server?

Yes. Import the McpToolDefinition interface from open-sse/mcp-server/schemas/toolDefinition.ts, define your tool with a unique name, handler function, and scope requirements, then call server.registerTool(customTool) on your initialized server instance. This appends your tool to the internal MCP_TOOLS array and updates MCP_TOOL_MAP for immediate availability alongside the 104 built-in tools.

Where can I find the complete list of available MCP tools in OmniRoute?

The master catalog resides in open-sse/mcp-server/schemas/tools.ts, which exports MCP_TOOLS, MCP_ESSENTIAL_TOOLS (phase 1), and MCP_ADVANCED_TOOLS (phase 2). For runtime discovery, query the public API endpoint at GET /api/mcp/tools (implemented in src/app/api/mcp/tools/route.ts) to receive JSON containing all registered tools, their phases, and required permission scopes.

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