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

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:

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:

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. Scope enforcement, audit logging, and description compression are handled centrally in open-sse/mcp-server/scopeEnforcement.ts and 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:

# 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:

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:

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:

export OMNIROUTE_MCP_API_KEY="your-secret-key"

Scope Configuration

Scope enforcement is declarative and configurable via environment variables:

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 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 — Server initialization and tool registration
• open-sse/mcp-server/httpTransport.ts — HTTP transport implementation
• 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 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 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 file validates these permissions centrally for all transports.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}