# How to Connect to the OmniRoute MCP Server: 3 Transport Methods Explained

> Learn how to connect to the OmniRoute MCP server using stdio, HTTP SSE, or HTTP Stream. Get the detailed steps for each transport method to integrate seamlessly.

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

---

**You can connect to the OmniRoute MCP server via stdio (local CLI), HTTP SSE (streaming events), or HTTP Stream (request/response) on port 20128 after starting it with `omniroute --mcp` or by setting `OMNIROUTE_MCP_HTTP=true`.**

The OmniRoute repository (`diegosouzapw/OmniRoute`) ships a built-in **MCP (Multi-tool Control Protocol) server** that exposes 87 tools—including memory, skills, provider catalog, routing, compression, and audit capabilities—over multiple transport families. This guide covers how to start the server and connect from Python, Node.js, and custom stdio clients.

---

## Starting the OmniRoute MCP Server

Before connecting, you must start the MCP server using one of two methods.

### Method 1: Stdio Transport (Local Desktop Clients)

For AI desktop clients like Claude Desktop, Cursor, or VS Code Copilot that spawn the server as a child process:

```bash
omniroute --mcp

```

This command prints a startup message and runs the proxy core. The server communicates over the **stdio pipe**, accepting JSON requests via stdin and returning responses via stdout.

### Method 2: HTTP Transports (Network Access)

To expose HTTP endpoints for remote or programmatic access:

```bash
export OMNIROUTE_MCP_HTTP="true"
export OMNIROUTE_MCP_HTTP_PORT="20128"  # Optional, defaults to 20128

omniroute

```

This enables both `/api/mcp/sse` (Server-Sent Events) and `/api/mcp/stream` (plain JSON stream) on the specified port.

---

## Transport Options and Use Cases

OmniRoute supports three transport families, each suited to different integration patterns:

| Transport | Best For | Endpoint/Command |
|-----------|----------|------------------|
| **stdio** | Desktop AI agents spawning child processes | `omniroute --mcp` |
| **HTTP SSE** | Browser-based clients, event-driven architectures | `http://localhost:20128/api/mcp/sse` |
| **HTTP Stream** | CI scripts, Python/Node SDKs, simple HTTP clients | `http://localhost:20128/api/mcp/stream` |

All transports share the same **tool registry** defined in [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts). Scope enforcement, audit logging, and description compression are handled centrally in [`open-sse/mcp-server/scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/scopeEnforcement.ts) and [`open-sse/mcp-server/httpTransport.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/httpTransport.ts).

---

## Connecting from Python (Official MCP SDK)

The Python SDK provides the simplest HTTP Stream integration. Install it via pip and instantiate the client with the stream endpoint:

```python

# pip install omniroute-mcp

from omniroute_mcp import MCPClient

# Connect via HTTP Stream for simple request/response

client = MCPClient(base_url="http://localhost:20128/api/mcp/stream")

# List available tools (requires read:tools scope)

resp = client.call("list_tools")
print(resp["tools"])

```

The SDK automatically injects required headers including `mcp-session-id` (for audit logging) and `Authorization` (if `OMNIROUTE_MCP_API_KEY` is configured).

---

## Connecting from Node.js (HTTP SSE)

For streaming, event-driven tool output, use the SSE endpoint with the `eventsource` package:

```javascript
import { EventSource } from "eventsource";

const sse = new EventSource("http://localhost:20128/api/mcp/sse");

// Subscribe to tool-specific events
sse.addEventListener("tool_result", (e) => {
  const data = JSON.parse(e.data);
  console.log("Tool output:", data);
});

// Send requests via the companion HTTP endpoint
await fetch("http://localhost:20128/api/mcp/stream", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    method: "list_cache",
    params: {}
  })
});

```

SSE delivers incremental `tool_result` events as the server produces output, making it ideal for long-running operations or real-time monitoring.

---

## Connecting via Stdio (Direct Child Process)

For custom integrations or compatibility with MCP-compatible desktop agents, spawn the process directly and handle JSON lines:

```typescript
import { spawn } from "node:child_process";
import { createInterface } from "node:readline";

const mcp = spawn("omniroute", ["--mcp"]);

const rl = createInterface({ input: mcp.stdout });
rl.on("line", (line) => {
  // Each line is a JSON-encoded MCP response
  const msg = JSON.parse(line);
  console.log("MCP:", msg);
});

// Send requests via stdin (must end with newline)
mcp.stdin.write(
  JSON.stringify({ method: "list_memory", params: {} }) + "\n"
);

```

**Critical requirement:** Every JSON request must terminate with a newline (`\n`) character. Without this delimiter, the server will hang waiting for input completion.

---

## Authentication and Scope Enforcement

Management-level tools (e.g., `write:combos`) require authentication and explicit permission scopes.

### API Key Configuration

Set the environment variable or pass the `Authorization: Bearer <key>` header:

```bash
export OMNIROUTE_MCP_API_KEY="your-secret-key"

```

### Scope Configuration

Scope enforcement is declarative and configurable via environment variables:

```bash
export OMNIROUTE_MCP_ENFORCE_SCOPES="true"  # Enable enforcement

export OMNIROUTE_MCP_SCOPES="read:tools,read:cache,execute:completions"

```

The [`open-sse/mcp-server/scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/scopeEnforcement.ts) file handles validation against these scopes. Common scopes include `read:tools`, `read:cache`, `write:combos`, and `execute:completions`.

---

## Troubleshooting Common Connection Issues

| Symptom | Root Cause | Solution |
|---------|------------|----------|
| `GET /api/mcp/sse` returns 404 | HTTP transport not enabled | Set `OMNIROUTE_MCP_HTTP=true` before starting |
| "Missing `mcp-session-id` header" | Client omitted required audit header | Add `mcp-session-id: <uuid>` or use the SDK |
| "Scope `write:combos` denied" | Insufficient permissions | Provide valid API key or expand `OMNIROUTE_MCP_SCOPES` |
| Stdio client hangs after request | Missing newline terminator | Ensure each JSON line ends with `\n` |

---

## Quick Reference: Transport Cheat Sheet

| Transport | Start Command | URL | Primary Use |
|-----------|---------------|-----|-------------|
| **stdio** | `omniroute --mcp` | — | Desktop AI agents (Claude Desktop, Cursor) |
| **HTTP SSE** | `OMNIROUTE_MCP_HTTP=true omniroute` | `http://localhost:20128/api/mcp/sse` | Real-time streaming, browsers |
| **HTTP Stream** | Same as SSE | `http://localhost:20128/api/mcp/stream` | SDKs, scripts, simple HTTP clients |

**Key Source Files:**
- [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) — Server initialization and tool registration
- [`open-sse/mcp-server/httpTransport.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/httpTransport.ts) — HTTP transport implementation
- [`open-sse/mcp-server/scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/scopeEnforcement.ts) — Permission handling
- `open-sse/mcp-server/tools/*.ts` — Individual tool implementations (memory, skill, compression, etc.)

---

## Summary

To **connect to the OmniRoute MCP server**, choose your transport based on your integration needs:

- Use **stdio** (`omniroute --mcp`) for desktop AI agents that spawn the server as a child process
- Use **HTTP SSE** (`http://localhost:20128/api/mcp/sse`) for real-time, event-driven streaming from browsers or Node.js applications
- Use **HTTP Stream** (`http://localhost:20128/api/mcp/stream`) for simple request/response patterns in Python, CI scripts, or HTTP clients

Enable HTTP transports by setting `OMNIROUTE_MCP_HTTP=true`, configure authentication via `OMNIROUTE_MCP_API_KEY`, and control access through `OMNIROUTE_MCP_SCOPES`. All 87 tools are registered in [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) and accessible through any transport once the server is running on port 20128.

---

## Frequently Asked Questions

### What is the default port for the OmniRoute MCP server?

The default port is **20128**. You can customize it by setting the `OMNIROUTE_MCP_HTTP_PORT` environment variable before starting the server. Both HTTP SSE and HTTP Stream endpoints are served on this port when `OMNIROUTE_MCP_HTTP` is enabled.

### How do I enable the HTTP transport for the OmniRoute MCP server?

Set the environment variable `OMNIROUTE_MCP_HTTP="true"` before running the `omniroute` command. This exposes both `/api/mcp/sse` and `/api/mcp/stream` endpoints. Without this variable, the HTTP transport remains disabled and requests to these endpoints will return 404 errors.

### Why does my stdio client hang when sending requests?

Stdio transport requires each JSON request to terminate with a newline character (`\n`). The server in [`open-sse/mcp-server/server.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) reads lines from stdin, so if your client omits the newline, the server waits indefinitely for the message to complete. Always append `\n` to your JSON strings when writing to `mcp.stdin`.

### Which tools require an API key and special scopes?

Tools that modify state—such as those requiring `write:combos` or management-level operations—require both an API key (set via `OMNIROUTE_MCP_API_KEY`) and explicit scopes in `OMNIROUTE_MCP_SCOPES`. Read-only operations like `list_tools` or `list_cache` typically only need basic `read:tools` or `read:cache` scopes. The [`open-sse/mcp-server/scopeEnforcement.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/scopeEnforcement.ts) file validates these permissions centrally for all transports.