How to Integrate Claude Code, Codex, Cursor, and Cline Using MCP Transport in OmniRoute

OmniRoute exposes a unified MCP (Multi-Client Protocol) server that routes LLM requests through stdio, sse, or streamable-http transports, enabling seamless integration with Claude Code, Cursor, Cline, and Codex via OAuth provider registration.

OmniRoute consolidates AI provider requests through a single routing endpoint. By enabling the MCP transport layer, you can expose this routing engine to external tools as a tool-driven RPC surface, allowing Claude Code, Cursor, Cline, and Codex to authenticate and execute requests through OmniRoute's unified proxy according to the diegosouzapw/OmniRoute source code.

Understanding MCP Transport Modes

OmniRoute supports three distinct transport protocols for the MCP server, defined in src/shared/validation/settingsSchemas.ts around line 200 as a z.enum(["stdio","sse","streamable‑http"]). The transport mode determines how external clients communicate with the routing engine:

• stdio – Used by CLI tools and local scripts via the omniroute mcp command
• sse – Server-Sent Events endpoint at GET /api/mcp/sse for persistent connections
• streamable-http – Standard HTTP POST endpoint at POST /api/mcp/stream for request/response patterns

Each transport route validates that the mcpTransport setting matches the endpoint. For example, src/app/api/mcp/sse/route.ts (line 25) and src/app/api/mcp/stream/route.ts (line 27) both enforce this validation, returning clear errors if the configuration mismatches.

Provider Registration Architecture

Before integrating specific tools, OmniRoute registers Claude Code, Cursor, and Cline as OAuth providers with dedicated entries in the provider constants:

• Claude Code – Defined at line 80 in src/shared/constants/providers/oauth.ts with name: "Claude Code" and OAuth scope "user:mcp_servers"
• Cursor – Defined at line 18 in src/mitm/targets/cursor.ts with name: "Cursor" and specialized header construction
• Cline – Defined at line 174 in src/shared/constants/providers/oauth.ts with name: "Cline" and the buildClineHeaders helper in src/shared/utils/clineAuth.ts that ensures the required workos: prefix

Codex follows the same registration pattern through the default OAuth provider framework, utilizing the standard OpenAI-compatible executor in open-sse/executors/default.ts.

Step-by-Step Integration

Follow these steps to enable MCP transport and route requests to your chosen AI coding tools.

1. Enable MCP in Settings

Toggle the mcpEnabled boolean setting stored in the database-backed settings table (src/lib/db/settings.ts). You can enable this via the Settings API:

curl -X PATCH https://localhost:3000/api/settings \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"mcpEnabled":true}'

Or use the Settings UI at /dashboard/mcp.

2. Select Your Transport Mode

Set the mcpTransport value to match your environment. The default is "stdio", but change it to "sse" or "streamable-http" for networked deployments:

curl -X PATCH https://localhost:3000/api/settings \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"mcpEnabled":true,"mcpTransport":"sse"}'

3. Start the MCP Server

For stdio transport, use the CLI command:

omniroute mcp

This reads your settings and spawns the appropriate transport, registering all available tools via src/app/api/mcp/tools/route.ts.

For HTTP-based transports, the server starts automatically when you call the respective endpoints.

4. Route Requests to Specific Providers

Once running, invoke provider-specific tools through the MCP server. OmniRoute automatically applies the correct OAuth flow for each target:

• Cursor – Uses the executor in open-sse/executors/cursor.ts
• Claude Code – Routes through the default executor in open-sse/executors/default.ts with Claude-specific OAuth handling
• Cline – Leverages buildClineHeaders from src/shared/utils/clineAuth.ts for authentication header construction

Transport Implementation Examples

Using SSE Transport with Claude Code

First, enable SSE transport via the API, then connect to the streaming endpoint:

# Enable MCP with SSE transport

curl -X PATCH https://localhost:3000/api/settings \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"mcpEnabled":true,"mcpTransport":"sse"}'

# Start MCP server (reads settings and switches to SSE)

omniroute mcp

# Connect via SSE and invoke Claude Code

curl -N https://localhost:3000/api/mcp/sse \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"tool":"chat_completion","provider":"claude-code","payload":{"model":"claude-3-5-sonnet","messages":[{"role":"user","content":"Hello"}]}}'

Using Streamable-HTTP Transport with Cursor

For programmatic access from Node.js applications:

import fetch from "node-fetch";

const response = await fetch("https://localhost:3000/api/mcp/stream", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    tool: "chat_completion",
    provider: "cursor",
    payload: { 
      model: "claude-sonnet-4.5", 
      messages: [{ role: "user", content: "Hello" }] 
    },
  }),
});

const result = await response.json();
console.log(result);

Using STDIO Transport for Local Scripts

For local CLI integration where you need to pipe commands:

# List available models for Cline via STDIO

omniroute mcp --tool list_models --provider cline

The MCP server translates this request into the appropriate OAuth-authenticated call using the header helpers defined in the provider registration files.

Key Source Files Reference

Feature	File Path	Implementation Detail
Provider registration	src/shared/constants/providers/oauth.ts	Claude Code (line 80), Cline (line 174) OAuth entries
Cursor MITM target	src/mitm/targets/cursor.ts	Cursor provider definition (line 18)
Settings schema	src/shared/validation/settingsSchemas.ts	mcpEnabled & mcpTransport validation (line ~200)
MCP tools endpoint	src/app/api/mcp/tools/route.ts	Tool registration and dispatch
SSE transport	src/app/api/mcp/sse/route.ts	Transport validation (line 25)
HTTP stream	src/app/api/mcp/stream/route.ts	Transport validation (line 27)
Cline auth	src/shared/utils/clineAuth.ts	buildClineHeaders helper
Cursor execution	open-sse/executors/cursor.ts	Core request handling
Default execution	open-sse/executors/default.ts	Claude Code OAuth flow

Summary

• Enable MCP by setting mcpEnabled to true in the database settings via the API or dashboard
• Choose a transport (stdio, sse, or streamable-http) using the mcpTransport setting validated in src/shared/validation/settingsSchemas.ts
• Register providers through OAuth entries in src/shared/constants/providers/oauth.ts for Claude Code and Cline, or src/mitm/targets/cursor.ts for Cursor
• Start the server using omniroute mcp for stdio, or direct HTTP requests to /api/mcp/sse or /api/mcp/stream
• Authenticate automatically using provider-specific helpers like buildClineHeaders that handle OAuth scopes and header construction

Frequently Asked Questions

What is the difference between SSE and streamable-http transports in OmniRoute?

SSE (Server-Sent Events) establishes a persistent connection where the server pushes data to the client over time, ideal for streaming LLM responses. The endpoint /api/mcp/sse maintains an open connection validated at line 25 of src/app/api/mcp/sse/route.ts. Streamable-http uses standard HTTP POST requests to /api/mcp/stream with response streaming, better suited for stateless clients that need request/response semantics. Both are validated against the mcpTransport setting to prevent transport mismatches.

How does OmniRoute handle authentication for Cline specifically?

Cline uses a specialized authentication helper called buildClineHeaders located in src/shared/utils/clineAuth.ts. This function ensures that authentication tokens include the required workos: prefix, which is specific to Cline's OAuth implementation. The provider entry at line 174 of src/shared/constants/providers/oauth.ts includes the OAuth scope "user:mcp_servers" and references this header builder for all outgoing requests.

Can I switch between transports without restarting OmniRoute?

Yes. The mcpTransport setting is database-backed in src/lib/db/settings.ts and can be updated via the Settings API (PATCH /api/settings) or the dashboard at /dashboard/mcp. The transport routes in src/app/api/mcp/sse/route.ts and src/app/api/mcp/stream/route.ts validate the current setting on each request, allowing you to switch from stdio to sse to streamable-http dynamically without restarting the server.

Where is Cursor-specific request handling implemented?

Cursor-specific execution logic resides in open-sse/executors/cursor.ts, while its provider registration appears at line 18 of src/mitm/targets/cursor.ts. This separation allows OmniRoute to handle Cursor's unique authentication flows and API formatting separately from the default OpenAI-compatible executor used for Claude Code and Codex.

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