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

> Configure MCP server tools in OmniRoute easily. Create a server instance with createMcpServer(), choose your transport, and benefit from secure scope enforcement for 104 built-in tools.

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

---

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

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/schemas/tools.ts). The master list aggregates specialized tool arrays and deduplicates by name:

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

```bash
npx omniroute --mcp

```

This executes `startMcpStdio(createMcpServer())` from [`open-sse/mcp-server/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`:

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

```

The transport constructor (line 13 in [`httpTransport.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`:

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

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

```

This route ([`src/app/api/mcp/tools/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

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

```typescript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) | `createMcpServer()` factory, `McpServer` class, `invokeTool` method |
| [`open-sse/mcp-server/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/index.ts) | Public exports and stdio starter |
| [`open-sse/mcp-server/httpTransport.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/httpTransport.ts) | HTTP transport binding |
| [`open-sse/mcp-server/schemas/tools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/schemas/tools.ts) | Master tool catalog, `MCP_TOOLS`, `MCP_TOOL_MAP` |
| [`open-sse/mcp-server/scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/scopeEnforcement.ts) | Scope validation middleware |
| [`src/app/api/mcp/tools/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/mcp/tools/route.ts) | HTTP discovery endpoint |
| [`skills/omni-mcp/SKILL.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`.