# How to Set Up and Use the OmniRoute MCP Server

> Quickly set up and use the OmniRoute MCP server. Learn to instantiate the server, select transport options like stdio HTTP or SSE, and enforce permissions with scope validation.

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

---

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

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

```bash
npx omniroute --mcp

```

This executes `startMcpStdio(createMcpServer())` as defined in [`open-sse/mcp-server/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/index.ts).

**Programmatic approach:**

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

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

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

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

### How does permission scope enforcement work?

Permission scopes are enforced in [`open-sse/mcp-server/scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.