OmniRoute Usage Examples: Complete Guide with Code Samples

OmniRoute provides a unified OpenAI-compatible API endpoint that lets you route requests to 237+ LLM providers using simple HTTP calls, CLI commands, or JSON-RPC messages.

OmniRoute is a unified AI proxy and router that abstracts away provider-specific authentication, model names, and request formats. The repository diegosouzapw/OmniRoute exposes a single API surface built on Next.js, allowing developers to interact with multiple LLM providers through one consistent interface. Whether you are making direct HTTP requests, using the CLI tool, or integrating via the MCP or A2A protocols, OmniRoute simplifies multi-provider AI integration.

Architecture Overview

Understanding how OmniRoute processes requests helps you leverage its full capabilities. The system consists of several interconnected layers that handle routing, tool execution, and protocol translation.

Core Routing Engine

The routing engine combines multiple provider targets into a combo and selects the optimal provider using 17 different strategies (priority, weighted random, cost-optimized, etc.). This logic is implemented in [src/lib/db/combos.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/combos.ts) and orchestrated through [open-sse/services/combo.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts). When a request arrives, the handler in [open-sse/handlers/chatCore.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts) validates the input, applies any configured guardrails, and delegates to the routing engine.

MCP and A2A Servers

OmniRoute exposes 94 built-in tools via the Model Context Protocol (MCP) server located at [open-sse/mcp-server/server.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts). These tools support health checks, combo management, and request compression. For agent-to-agent communication, the A2A server in [src/lib/a2a/server.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/a2a/server.ts) implements the JSON-RPC 2.0 protocol.

Guardrails and Compression

Before requests reach upstream providers, they pass through guardrails for PII masking and prompt-injection protection ([src/lib/guardrails/pii-masker.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/pii-masker.ts)). Optional prompt compression using lite, caveman, or RTK engines ([open-sse/services/compression/strategies/lite.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/compression/strategies/lite.ts)) reduces token usage.

HTTP API Usage Examples

The primary interface exposes OpenAI-compatible endpoints on localhost:3000. You can interact with these using standard HTTP clients.

cURL Request Example

Send a chat completion request to the unified endpoint:

curl -X POST http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

This endpoint is defined in [src/app/api/v1/chat/completions/route.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts) and processes requests through the core handler chain.

Node.js Fetch Example

For programmatic access, use the native fetch API in Node.js:

const fetch = require('node-fetch');

async function callOmniRoute() {
  const response = await fetch('http://localhost:3000/v1/chat/completions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      model: 'gpt-4o',
      messages: [{ role: 'user', content: 'Hello' }]
    })
  });
  
  const data = await response.json();
  console.log(data);
}

callOmniRoute();

The request flows through [open-sse/executors/default.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts), which builds the provider-specific URL and headers before executing the upstream request.

CLI Usage Examples

OmniRoute provides a global CLI tool for setup and service management.

Installation and Setup

Install the package globally and initialize the configuration:

npm i -g omniroute
omniroute --setup

The --setup command generates a configuration template at ~/.omniroute/.env where you can define provider API keys and routing preferences.

Starting the Server

Launch the router service locally:

omniroute serve

This starts the Next.js application on http://localhost:3000, exposing all API endpoints and the MCP server.

MCP Tool Examples

The MCP interface allows you to manage combos and inspect system health programmatically.

Listing Available Combos

Query the MCP server to see configured provider combinations:

omniroute --mcp list_combos

This command communicates with the MCP server implementation in [open-sse/mcp-server/server.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts), which exposes 94 built-in tools including combo management and compression controls.

A2A Protocol Examples

For agent-to-agent communication, OmniRoute supports the A2A v0.3 JSON-RPC protocol.

Sending Agent Messages

POST a JSON-RPC 2.0 message to the A2A endpoint:

const fetch = require('node-fetch');

const payload = {
  jsonrpc: '2.0',
  method: 'message/send',
  params: { 
    target: 'agent-xyz', 
    body: 'Hello from OmniRoute!' 
  },
  id: 1
};

fetch('http://localhost:3000/a2a', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payload)
})
  .then(res => res.json())
  .then(console.log);

The A2A server handles these requests through [src/lib/a2a/server.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/a2a/server.ts), enabling inter-agent messaging alongside standard LLM routing.

Key Implementation Files

Understanding these source files helps you customize and debug OmniRoute behavior:

• [src/app/api/v1/chat/completions/route.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/chat/completions/route.ts) – Next.js API route receiving OpenAI-style chat requests
• [open-sse/handlers/chatCore.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts) – Central handler for request validation and translation
• [open-sse/services/combo.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) – Combo resolution and routing strategy implementation
• [open-sse/executors/default.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/default.ts) – Default executor for OpenAI-compatible provider requests
• [open-sse/mcp-server/server.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts) – MCP server with 94 tooling endpoints
• [src/lib/a2a/server.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/a2a/server.ts) – JSON-RPC entry point for agent communication
• [docs/reference/API_REFERENCE.md](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/API_REFERENCE.md) – Complete endpoint documentation and request schemas

Summary

• OmniRoute provides a unified OpenAI-compatible endpoint for 237+ LLM providers through a Next.js-based proxy
• HTTP API allows direct integration using cURL or fetch, with the main endpoint at /v1/chat/completions
• CLI tool (omniroute) handles installation, configuration setup, and server startup
• MCP server exposes 94 tools for combo management, health checks, and request optimization
• A2A protocol enables JSON-RPC 2.0 agent-to-agent communication on the same port
• Routing engine uses 17 strategies defined in src/lib/db/combos.ts to select optimal providers
• Guardrails and compression protect data and reduce token usage before upstream requests

Frequently Asked Questions

How do I configure multiple providers in OmniRoute?

Run omniroute --setup to generate a configuration template at ~/.omniroute/.env. Add your provider API keys (OpenAI, Anthropic, Gemini, etc.) to this file. The routing engine in [open-sse/services/combo.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) automatically uses these credentials when building requests to upstream providers.

Can I use OmniRoute with existing OpenAI client libraries?

Yes. Because OmniRoute exposes a fully OpenAI-compatible API at http://localhost:3000/v1, you can point any OpenAI SDK to this URL. Simply change the baseURL parameter in your client configuration to http://localhost:3000/v1 and keep using the same request formats.

What is the difference between MCP and A2A interfaces in OmniRoute?

The MCP (Model Context Protocol) interface ([open-sse/mcp-server/server.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts)) exposes tools for managing the router itself—combos, compression settings, and health monitoring. The A2A (Agent-to-Agent) interface ([src/lib/a2a/server.ts](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/a2a/server.ts)) uses JSON-RPC 2.0 for sending messages between AI agents, enabling multi-agent workflows rather than just LLM routing.

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