How to Set Up and Use the OmniRoute MCP Server

To set up the OmniRoute MCP server, instantiate the server with createMcpServer(), select your transport (stdio, HTTP, or SSE), and enforce permissions via the built-in scope validation layer.

OmniRoute bundles a production-ready MCP (Multi-Channel Provider) server that exposes 104 built-in tools across core routing, memory management, and agent skills. The server supports three transport protocols and enforces fine-grained permission scopes, making it suitable for both local CLI usage and distributed deployments.

Understanding the OmniRoute MCP Server Architecture

The OmniRoute MCP server is implemented in the open-sse/mcp-server/ directory and follows a modular architecture. At its core, the createMcpServer() function in open-sse/mcp-server/server.ts (line 618) constructs a McpServer instance, registers all base tools from the MCP_TOOLS catalog, and prepares the internal routing layer.

The tool catalog aggregates capabilities from multiple domains:

• Essential tools (Phase 1): Health checks, routing diagnostics, and cache status
• Advanced tools (Phase 2): Compression management, agent-skill operations, and gamification systems

These tools are defined in open-sse/mcp-server/schemas/tools.ts and deduplicated by name into a master MCP_TOOLS array, with a MCP_TOOL_MAP providing O(1) lookup performance.

Creating the Server Instance

All setups begin with the factory function that initializes the server and loads the 104 built-in tools.

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

const server = createMcpServer(); // Initializes McpServer at server.ts#L618

The createMcpServer() function automatically registers handlers for all tools in MCP_TOOLS, including those from CCR_MCP_TOOLS, memoryTools, skillTools, and agentSkillTools sub-modules.

Choosing a Transport Protocol

The OmniRoute MCP server supports three transport modes: stdio, HTTP, and SSE. Your choice depends on whether you are integrating with local CLI tools or remote services.

Stdio Transport (CLI Usage)

For local integrations and CLI-based workflows, use the stdio transport via the built-in shortcut or programmatic API.

Command-line approach:

npx omniroute --mcp

This executes startMcpStdio(createMcpServer()) as defined in open-sse/mcp-server/index.ts.

Programmatic approach:

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

const server = createMcpServer();
startMcpStdio(server); // Starts stdio transport

HTTP Transport (Remote Services)

For network-accessible deployments, instantiate the HttpTransport class.

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); // See httpTransport.ts#L13
http.listen(3001, () => console.log("MCP HTTP server listening on port 3001"));

The HTTP transport exposes the full tool catalog at runtime and supports the discovery endpoint documented below.

Enforcing Permission Scopes

Security is enforced through the scope validation layer in open-sse/mcp-server/scopeEnforcement.ts. Each tool declares required scopes in its definition, and incoming requests must include matching OMNIROUTE_MCP_SCOPES claims.

When server.invokeTool() is called, the scope enforcement middleware validates the caller's permissions against the tool's declared scopes array before execution proceeds. Tools with mismatched scopes are rejected automatically.

Working with the Tool Catalog

The 104 available tools are organized in open-sse/mcp-server/schemas/tools.ts with a two-phase maturity model:

• Phase 1: Essential operations (health checks, basic routing)
• Phase 2: Advanced features (pool management, A2A agent skills)

Querying Available Tools via API

OmniRoute exposes a public discovery endpoint to inspect the tool catalog at runtime.

Endpoint: GET /api/mcp/tools (implemented in src/app/api/mcp/tools/route.ts)

This returns the complete list of registered tools, their phases, descriptions, and required permission scopes, enabling dynamic client adaptation.

Invoking Tools Programmatically

Once the server is running, execute tools using the invokeTool method on the McpServer instance.

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

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

The invokeTool method handles scope validation, handler dispatch, and error formatting, returning structured results for all 104 built-in operations.

Registering Custom Tools

Extend the built-in catalog by registering custom tools alongside the defaults.

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

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

const server = createMcpServer();
server.registerTool(customTool); // Adds to MCP_TOOLS and updates MCP_TOOL_MAP

Custom tools integrate into the same scope enforcement and discovery systems as built-in tools.

Summary

• Initialize the server using createMcpServer() from open-sse/mcp-server/server.ts to load all 104 built-in tools
• Select transport based on deployment context: omniroute --mcp for stdio CLI usage, HttpTransport for remote HTTP access, or SSE for streaming
• Validate scopes through the automatic enforcement in scopeEnforcement.ts, checking OMNIROUTE_MCP_SCOPES against tool requirements
• Discover tools via the GET /api/mcp/tools endpoint or programmatic access to MCP_TOOL_MAP
• Extend functionality by calling server.registerTool() with McpToolDefinition objects that specify handlers, phases, and required scopes

Frequently Asked Questions

What transports does the OmniRoute MCP server support?

The server supports three transport protocols: stdio for local CLI integration, HTTP for REST-based remote access, and SSE for server-sent event streaming. The stdio transport is the default when running omniroute --mcp, while HTTP requires instantiating the HttpTransport class from httpTransport.ts.

How does permission scope enforcement work?

Permission scopes are enforced in open-sse/mcp-server/scopeEnforcement.ts. Each tool definition includes a scopes array declaring required permissions. Before execution, the server validates that the incoming request's OMNIROUTE_MCP_SCOPES claim contains at least one matching scope. Tools execute only when validation passes.

Can I add my own tools to the OmniRoute MCP server?

Yes. Import McpToolDefinition from schemas/toolDefinition.ts, construct a tool object with a handler function, and call server.registerTool(). Custom tools appear in the MCP_TOOLS catalog and MCP_TOOL_MAP, inherit scope enforcement automatically, and are discoverable via the /api/mcp/tools endpoint.

Where is the tool catalog defined?

The master tool catalog lives in open-sse/mcp-server/schemas/tools.ts. It aggregates CCR_MCP_TOOLS, memoryTools, skillTools, agentSkillTools, and other sub-collections into the exported MCP_TOOLS array. The MCP_TOOL_MAP provides O(1) name-based lookup for runtime efficiency.

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