# OmniRoute Usage Examples: Complete Guide with Code Samples

> Explore OmniRoute usage examples to connect to 237+ LLM providers via a unified OpenAI compatible API. Get complete guides and code samples for seamless integration.

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

---

**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)](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)](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)](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)](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)](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)](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)](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:

```bash
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)](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:

```javascript
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)](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:

```bash
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:

```bash
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:

```bash
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)](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:

```javascript
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)](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)](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)](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)](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)](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)](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)](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)](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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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)](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)](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)](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.