# How to Set Up and Use the MCP Server with OmniRoute: Complete 2024 Guide

> Master setting up and using the MCP server with OmniRoute. This 2024 guide covers its 104 tools, transport modes, and scope enforcement. Get started now!

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

---

**OmniRoute bundles a production-ready MCP (Multi-Channel Provider) server with 104 built-in tools, three transport modes (SSE, stdio, HTTP), and fine-grained scope enforcement—all accessible via `createMcpServer()` in [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts).**

The **Model Context Protocol (MCP)** server in OmniRoute turns the framework into a tool-capable backend that LLMs and agents can invoke through standardized endpoints. Whether you're exposing health checks, routing logic, or custom business operations, the server ships with everything needed for secure, scoped tool execution.

---

## Creating the MCP Server Instance

Every OmniRoute MCP deployment starts with `createMcpServer()` in [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) (line 618). This factory function builds a `McpServer` instance, automatically registers all 104 base tools from `MCP_TOOLS`, and prepares the internal router for incoming requests.

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

const server = createMcpServer();  // ← initializes tool registry + handlers

```

The tool catalog itself is assembled in [`open-sse/mcp-server/schemas/tools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/schemas/tools.ts) from several specialized subsets:

- `CCR_MCP_TOOLS` — core routing and CCR operations
- `memoryTools` — memory persistence and retrieval
- `skillTools` — skill execution utilities
- `agentSkillTools` — A2A (agent-to-agent) capabilities
- `poolTools` — resource pool management

```typescript
// schemas/tools.ts — master tool aggregation
export const MCP_TOOLS = [
  ...CCR_MCP_TOOLS,
  ...memoryTools,
  ...skillTools,
  ...agentSkillTools,
  ...poolTools,
  // …additional tool categories
];

```

The server also maintains `MCP_TOOL_MAP` for O(1) name-based lookups and splits tools into **Phase 1 (essential)** and **Phase 2 (advanced)** categories for progressive capability exposure.

---

## Starting the MCP Server: Three Transport Options

OmniRoute supports **three transport modes** for different integration scenarios. Each wraps the same `McpServer` core but exposes it through different protocols.

### stdio Transport (CLI Quick Start)

The fastest way to launch the MCP server for local LLM integrations:

```bash
npx omniroute --mcp

```

Behind the scenes, this executes `startMcpStdio(createMcpServer())` from [`open-sse/mcp-server/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/index.ts). The stdio transport is ideal for Claude Desktop, Cursor, and other MCP clients that communicate over standard input/output streams.

### HTTP Transport (Programmatic Servers)

For remote deployments or web-facing APIs, instantiate `HttpTransport` directly:

```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 server listening on port 3001");
});

```

The `HttpTransport` constructor (line 13 in [`httpTransport.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/httpTransport.ts)) internally calls `createMcpServer()` and binds request handling to the specified port.

### SSE Transport (Server-Sent Events)

For real-time streaming tool outputs, the SSE transport enables push-based updates to connected clients. Configure this through the same transport pattern by selecting the SSE variant in your server bootstrap.

---

## Scope Enforcement and Security

Before any tool executes, [`open-sse/mcp-server/scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/scopeEnforcement.ts) validates the caller's permissions. The middleware checks the `OMNIROUTE_MCP_SCOPES` claim in the request context against each tool's `scopes` array in its definition.

**Permission flow:**

1. Incoming request carries scope claims (JWT, headers, or context)
2. Scope enforcement middleware intersects claims with `tool.scopes`
3. Execution proceeds only if at least one required scope matches

```typescript
// Example tool definition with scoped access
{
  name: "omniroute_admin_clear_cache",
  scopes: ["admin.cache", "superuser"],  // requires either scope
  handler: async (args) => { /* ... */ }
}

```

Tools without explicit scopes default to open access, though production deployments should always restrict sensitive operations.

---

## Discovering Available Tools

Clients can introspect the server's capabilities at runtime via the discovery endpoint implemented in [`src/app/api/mcp/tools/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/mcp/tools/route.ts):

```bash
curl http://localhost:3000/api/mcp/tools

```

Response includes tool names, descriptions, required scopes, and phase classifications:

```json
{
  "tools": [
    {
      "name": "omniroute_get_health",
      "phase": 1,
      "scopes": [],
      "description": "Returns server health status and version"
    },
    {
      "name": "omniroute_list_routes",
      "phase": 1,
      "scopes": ["routes.read"],
      "description": "Lists all registered routes"
    }
  ],
  "total": 104,
  "phases": { "essential": 42, "advanced": 62 }
}

```

---

## Invoking Tools Programmatically

Direct tool execution bypasses transport layers for internal use:

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

const server = createMcpServer();

// Synchronous invocation with typed results
const health = await server.invokeTool("omniroute_get_health", {});
console.log(health);  // → { status: "ok", version: "v3.8.50", uptime: 3600 }

// Tools accepting arguments
const routes = await server.invokeTool("omniroute_list_routes", {
  filter: "api/v1/*",
  includeInactive: false
});

```

The `invokeTool` method on `McpServer` handles argument validation, scope checking, and error wrapping automatically.

---

## Adding Custom Tools to the MCP Server

Extend the base catalog with domain-specific operations by implementing `McpToolDefinition`:

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

const validateWebhookSignature: McpToolDefinition = {
  name: "stripe_validate_signature",
  description: "Verifies Stripe webhook payload authenticity",
  phase: 2,
  scopes: ["payments.webhooks"],
  inputSchema: {
    type: "object",
    properties: {
      payload: { type: "string" },
      signature: { type: "string" },
      secret: { type: "string" }
    },
    required: ["payload", "signature"]
  },
  handler: async ({ payload, signature, secret }) => {
    const crypto = await import("node:crypto");
    const expected = crypto
      .createHmac("sha256", secret)
      .update(payload)
      .digest("hex");
    
    return {
      valid: crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expected)
      )
    };
  }
};

const server = createMcpServer();
server.registerTool(validateWebhookSignature);  // merges into MCP_TOOLS + MCP_TOOL_MAP

```

`registerTool()` automatically updates both the master tool list and the lookup map, ensuring immediate availability through all transports.

---

## Key Files Reference

| File | Purpose |
|------|---------|
| [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) | Core `createMcpServer()` factory and `McpServer` class |
| [`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 with `listen()` binding |
| [`open-sse/mcp-server/schemas/tools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/schemas/tools.ts) | `MCP_TOOLS` aggregation and phase splitting |
| [`open-sse/mcp-server/scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/scopeEnforcement.ts) | Permission validation middleware |
| [`src/app/api/mcp/tools/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/mcp/tools/route.ts) | Runtime tool discovery API |
| [`skills/omni-mcp/SKILL.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/skills/omni-mcp/SKILL.md) | CLI skill documentation |

---

## Summary

- **Initialize** with `createMcpServer()` in [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) (line 618) to load 104 built-in tools
- **Select transport**: `npx omniroute --mcp` for stdio, `HttpTransport` for HTTP, or SSE for streaming
- **Enforce security** through `OMNIROUTE_MCP_SCOPES` claims validated by [`scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scopeEnforcement.ts)
- **Discover tools** via `GET /api/mcp/tools` or introspect `MCP_TOOL_MAP` programmatically
- **Extend** with `registerTool()` using `McpToolDefinition` schemas for custom operations

---

## Frequently Asked Questions

### What is the MCP server in OmniRoute used for?

The MCP server exposes OmniRoute's internal capabilities—routing, caching, health monitoring, agent skills—as callable tools that conform to the Model Context Protocol. LLM clients like Claude, Cursor, and custom agents can invoke these tools through standardized transports without writing HTTP client code.

### How do I choose between stdio, HTTP, and SSE transports?

**stdio** suits local desktop integrations where the LLM spawns OmniRoute as a subprocess. **HTTP** works best for production deployments with remote clients or load balancers. **SSE** is optimal when tools stream partial results or progress updates back to the caller.

### Where are the 104 built-in tools defined?

The master list lives in [`open-sse/mcp-server/schemas/tools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/schemas/tools.ts), assembled from categorized subsets (`CCR_MCP_TOOLS`, `memoryTools`, `skillTools`, etc.). Each tool's handler, schema, and scope requirements are co-located in dedicated files under `open-sse/mcp-server/tools/`.

### How does scope enforcement protect sensitive tools?

[`scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/scopeEnforcement.ts) intercepts every tool invocation and compares the caller's `OMNIROUTE_MCP_SCOPES` against the tool's `scopes` array. Only requests with matching scopes proceed; others receive a 403-equivalent error before the handler executes.