How to Configure MCP Server Tools in OmniRoute: The Complete Setup Guide

Configure MCP server tools in OmniRoute by creating a server instance with createMcpServer(), selecting your transport (SSE, stdio, or HTTP), and relying on built-in scope enforcement to securely expose 104 built-in tools.

OmniRoute ships with a production-ready MCP (Multi-Channel Provider) server that consolidates over a hundred tools behind a unified interface. This guide walks through the exact configuration steps, file locations, and code patterns needed to get the MCP server running—whether you're launching from the CLI, embedding it in a Node.js application, or exposing tools over HTTP.

Initialize the MCP Server Instance

The entry point for any MCP configuration is createMcpServer() in open-sse/mcp-server/server.ts at line 618. This factory function constructs a McpServer object, auto-registers all MCP_TOOLS, and prepares the internal routing layer.

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

const server = createMcpServer();  // Loads 104 tools into MCP_TOOLS and MCP_TOOL_MAP

The server pulls its tool catalog from open-sse/mcp-server/schemas/tools.ts. The master list aggregates specialized tool arrays and deduplicates by name:

// schemas/tools.ts
export const MCP_TOOLS = [
  ...CCR_MCP_TOOLS,      // core routing tools
  ...memoryTools,        // memory management
  ...skillTools,         // skill operations
  ...agentSkillTools,    // A2A agent integrations
  ...poolTools,          // connection pooling
  // additional domains...
];

Two maps are built for O(1) lookups:

• MCP_TOOL_MAP — name → tool definition
• MCP_TOOL_PHASES — filters by maturity (phase 1 = essential, phase 2 = advanced)

Select and Configure Your Transport

OmniRoute MCP supports three transport modes. Your choice determines how clients connect and invoke tools.

Option 1: stdio Transport (CLI)

The fastest way to configure MCP server tools is the built-in CLI shortcut. Run:

npx omniroute --mcp

This executes startMcpStdio(createMcpServer()) from open-sse/mcp-server/index.ts, binding the server to standard input/output for direct integration with MCP-compatible clients.

Option 2: HTTP Transport

For web-based tool access, instantiate HttpTransport:

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 on :3001"));

The transport constructor (line 13 in httpTransport.ts) wraps the same createMcpServer() call, ensuring consistent tool registration across all entry points.

Option 3: SSE Transport

Server-Sent Events support is available through the open-sse package structure. The SSE transport follows identical initialization patterns—swap HttpTransport for SseTransport if your use case requires persistent server-to-client streaming.

Enforce Permission Scopes

Tool access is gated by scope enforcement implemented in open-sse/mcp-server/scopeEnforcement.ts. Every incoming request carries an OMNIROUTE_MCP_SCOPES claim; the middleware validates this against each tool's required scopes before execution.

Scope checking happens automatically—no manual configuration required. Tools declare their scopes in their McpToolDefinition:

{
  name: "omniroute_manage_compression",
  scopes: ["omniroute.advanced", "infrastructure.write"],
  // ...
}

Callers must present matching scopes in their authentication context. Failed scope checks reject with a permission error before the handler executes.

Discover and Invoke Tools

Runtime Tool Discovery

Query the public API endpoint to enumerate available tools:

curl https://your-host/api/mcp/tools

This route (src/app/api/mcp/tools/route.ts) returns tool names, phases, scope requirements, and parameter schemas—useful for dynamic client generation.

Programmatic Invocation

Call tools directly through the server instance:

const result = await server.invokeTool("omniroute_get_health", {});
// → { status: "ok", version: "v3.8.50", uptime: 12450 }

The invokeTool method on McpServer handles:

1. Scope validation via scopeEnforcement.ts
2. Parameter schema validation
3. Handler execution
4. Result serialization

Register Custom Tools (Optional)

Extend the built-in catalog with domain-specific tools:

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

const customTool: McpToolDefinition = {
  name: "myorg_validate_schema",
  description: "Validates payload against internal JSON Schema",
  phase: 2,
  scopes: ["myorg.data.validation"],
  handler: async ({ schemaUrl, payload }) => {
    // implementation
    return { valid: true, errors: [] };
  },
};

server.registerTool(customTool);  // Updates MCP_TOOLS and MCP_TOOL_MAP

Custom tools integrate seamlessly with scope enforcement and appear in /api/mcp/tools responses.

Key Configuration Files

File	Purpose
open-sse/mcp-server/server.ts	createMcpServer() factory, McpServer class, invokeTool method
open-sse/mcp-server/index.ts	Public exports and stdio starter
open-sse/mcp-server/httpTransport.ts	HTTP transport binding
open-sse/mcp-server/schemas/tools.ts	Master tool catalog, MCP_TOOLS, MCP_TOOL_MAP
open-sse/mcp-server/scopeEnforcement.ts	Scope validation middleware
src/app/api/mcp/tools/route.ts	HTTP discovery endpoint
skills/omni-mcp/SKILL.md	CLI skill documentation

Summary

• Create the server with createMcpServer() at server.ts#L618 to load 104 built-in tools
• Choose stdio (CLI), HTTP, or SSE transport based on your integration pattern
• Trust automatic scope enforcement in scopeEnforcement.ts to gate tool access
• Extend with registerTool() for custom capabilities that inherit the same security model
• Discover tool metadata via GET /api/mcp/tools for dynamic client configuration

Frequently Asked Questions

What transports does OmniRoute MCP support?

OmniRoute MCP supports three transports: stdio for CLI and subprocess integration, HTTP for REST-style access, and SSE for server-sent event streaming. All three use the same createMcpServer() foundation and tool registration logic.

How do I add authentication to MCP tool calls?

Authentication is handled through scope claims rather than direct auth configuration. Set the OMNIROUTE_MCP_SCOPES context on incoming requests; scopeEnforcement.ts validates these against each tool's declared scopes array before execution.

Can I disable built-in tools I don't need?

The current implementation loads all 104 tools into MCP_TOOLS automatically. To restrict availability, use scope enforcement—assign tools restrictive scopes and ensure callers lack those scopes. Future versions may support explicit tool filtering at initialization.

Where is the tool catalog defined?

The master catalog lives in open-sse/mcp-server/schemas/tools.ts. It aggregates domain-specific tool arrays (CCR, memory, skills, pools) into MCP_TOOLS, builds MCP_TOOL_MAP for fast lookups, and exports phase-filtered subsets like MCP_ESSENTIAL_TOOLS.

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