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

> Set up MCP server tools for OmniRoute easily. This guide shows how to initialize createMcpServer, select transports, and enforce permissions for seamless integration. Get started today.

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

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/schemas/tools.ts).

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/httpTransport.ts):

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/index.ts) or the convenience CLI shortcut:

```bash

# 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```typescript
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:

```bash
npx omniroute --mcp

```

This executes the stdio transport starter defined in [`open-sse/mcp-server/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```typescript
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:

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/mcp/tools/route.ts)) to receive JSON containing all registered tools, their phases, and required permission scopes.