# How to Integrate OmniRoute with External Tools and Services

> Integrate OmniRoute with 300+ AI providers and custom logic using its REST API, MCP extensions, skill framework, A2A, and CLI. Connect OmniRoute to your favorite tools today.

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

---

**OmniRoute can be integrated with external tools through its REST API, MCP server extensions, skill framework, A2A protocol, and CLI automations, enabling connections to 300+ AI providers and custom business logic.**

The `diegosouzapw/OmniRoute` repository implements a modular, extensible AI proxy architecture designed for plug-and-play interoperability. Whether you are wiring OmniRoute into existing HTTP pipelines, exposing custom commands as callable tools, or building agent-to-agent networks, the platform provides well-defined integration surfaces that require minimal configuration.

## Core Integration Surfaces

OmniRoute exposes seven primary methods for connecting with external systems, each serving distinct automation and orchestration needs.

### REST API Endpoints

The standard OpenAI-compatible HTTP interface in `src/app/api/v1/` accepts inference requests for chat, embeddings, and image generation. Any HTTP client can consume these endpoints without vendor lock-in, making OmniRoute a drop-in replacement for proprietary APIs while routing to multiple backend providers.

### Provider Catalog and Management

Located at [`src/lib/skills/omni-providers/SKILL.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/skills/omni-providers/SKILL.md), the provider management system allows dynamic registration of over 300 AI services. You can configure API keys, base URLs, and model mappings through HTTP calls, enabling runtime switching between OpenAI, Anthropic, or custom self-hosted models without restarting the server.

### MCP Tool Extensions

The Model Context Protocol (MCP) server in `open-sse/mcp-server/` exposes custom commands as first-class callable tools. This integration surface enables automation scripts, CI/CD pipelines, and local development workflows to invoke shell commands, database queries, or internal microservices directly through OmniRoute’s inference API.

### Skill Framework

The skill system in `src/lib/skills/` supports server-side plug-in handlers that preprocess or postprocess requests. Skills are automatically discovered via [`src/lib/skills/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/skills/registry.ts) and can modify headers, enrich context, or apply business logic before the request reaches the routing layer.

### A2A (Agent-to-Agent) Protocol

Implemented in `src/lib/a2a/`, this JSON-RPC interface allows OmniRoute to act as a remote LLM agent that invokes other agents. This enables multi-agent orchestration where OmniRoute handles routing decisions while delegating specific tasks to specialized downstream services.

### CLI Integrations

The built-in CLI supports direct tool invocation and server management through commands documented in `docs/guides/CLI‑INTEGRATIONS.md`. Scripts can start/stop services, trigger custom tools, or execute provider health checks without HTTP overhead, using the same tool definitions as the MCP server.

### Embedded Services

Auxiliary binaries such as Cloudflare Workers proxies or Ollama search instances run as part of the same process tree, detailed in `docs/frameworks/EMBEDDED‑SERVICES.md`. These services expose additional capabilities through the main API surface, co-locating infrastructure that would otherwise require separate deployment.

## How the Integration Pipeline Works

Understanding the request flow clarifies where custom integrations hook into the system.

1. **Request Handling** – Incoming calls hit `open-sse/handlers/` for CORS processing, Zod validation, and optional authentication.
2. **Routing and Resilience** – The **combo routing** engine in `open-sse/services/combo/` selects providers based on cost, latency, or health metrics. Each selection is protected by a **circuit-breaker** ([`src/shared/utils/circuitBreaker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/circuitBreaker.ts)) and **connection-cooldown** mechanisms ([`src/sse/services/auth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/auth.ts)).
3. **Provider Execution** – **Executors** in `open-sse/executors/` translate generic requests into provider-specific HTTP calls.
4. **Response Translation** – Normalization back to OpenAI-compatible schemas occurs in `open-sse/translator/`.
5. **Tool and Skill Invocation** – If the request includes tool calls, the MCP server looks up definitions in `open-sse/mcp-server/tools/` and executes associated handlers, while skills applied via the registry can transform the payload at any stage.

All layers are **plug-and-play**: adding a new provider, tool, or skill requires only dropping a file into the appropriate directory, with automatic discovery handling the rest.

## Practical Integration Examples

### Register a Custom Provider via REST

Add a new AI backend dynamically without modifying configuration files:

```http
POST /v1/providers
Content-Type: application/json

{
  "providerId": "my-custom-ai",
  "type": "apiKey",
  "baseUrl": "https://api.my-custom-ai.com/v1",
  "modelMap": { "gpt-4": "text-gen-v4" },
  "auth": { "apiKeyEnv": "MY_CUSTOM_API_KEY" }
}

```

The provider catalog at `src/lib/skills/omni-providers` immediately stores the record and makes it available for combo routing strategies.

### Invoke an MCP Tool from Chat Completions

Trigger shell commands or external scripts through the inference API:

```json
{
  "model": "gpt-4o",
  "messages": [
    { "role": "user", "content": "Run `ls -la` in the current directory." }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "execShell",
        "arguments": { "cmd": "ls -la" }
      }
    }
  ]
}

```

The `execShell` tool handler in [`open-sse/mcp-server/tools/execShell.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/tools/execShell.ts) executes the command and returns output as a standardized tool result.

### Build a Custom Skill for Request Enrichment

Modify incoming requests with business logic before routing:

```typescript
// src/lib/skills/omni-my-skill/mySkill.ts
import { SkillHandler } from '@/lib/skills/types';

export const mySkill: SkillHandler = async (ctx) => {
  const extra = await fetch('https://api.myservice.com/info')
    .then(r => r.json());
  ctx.request.headers.set('x-my-info', extra.id);
  return ctx.next();
};

```

Register the skill in [`src/lib/skills/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/skills/registry.ts) to activate it on every incoming request.

### Automate with CLI Tool Invocation

Execute tools directly from bash scripts without HTTP latency:

```bash
omniroute cli-tools invoke execShell --args '{"cmd":"date"}'

```

The CLI reads tool definitions from the same registry as the MCP server, ensuring consistency across interfaces.

### Implement Multi-Provider Fusion

Combine responses from multiple providers for redundancy or consensus:

```http
POST /v1/combo
Content-Type: application/json

{
  "strategy": "fusion",
  "targets": ["openai-gpt-4o", "anthropic-claude-3-sonnet"],
  "judgeModel": "gpt-4o"
}

```

The fusion service in `open-sse/services/combo/` fans out the request, aggregates responses, and uses the specified judge model to synthesize a final answer.

## Summary

- **OmniRoute integration** supports REST APIs, MCP tools, skills, A2A protocols, CLI extensions, and embedded services for comprehensive connectivity.
- The **provider catalog** in `src/lib/skills/omni-providers` enables runtime registration of 300+ AI backends without restarts.
- **MCP tools** in `open-sse/mcp-server/` expose shell commands and scripts as callable functions within chat completions.
- **Skills** in `src/lib/skills/` provide server-side middleware for request transformation and enrichment.
- **Combo routing** with circuit-breakers ([`src/shared/utils/circuitBreaker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/circuitBreaker.ts)) ensures resilient multi-provider failover.
- **CLI integrations** allow scripts to invoke tools and manage servers using the same definitions as the HTTP API.

## Frequently Asked Questions

### How do I add a new AI provider to OmniRoute without restarting the server?

You register providers dynamically through the REST API by posting to `/v1/providers` with your base URL, authentication details, and model mappings. The `src/lib/skills/omni-providers` module stores this configuration immediately, making the provider available for combo routing strategies without service interruption.

### Can OmniRoute execute local shell commands or scripts as part of an AI conversation?

Yes. The MCP server in `open-sse/mcp-server/` exposes local commands as tools that the LLM can invoke during chat completions. You define tools in `open-sse/mcp-server/tools/` and call them by name in the `tools` array of your API request, with execution results returned as function outputs to the conversation context.

### What is the difference between an MCP tool and a Skill in OmniRoute?

**MCP tools** are callable actions triggered by the LLM during inference (like executing shell commands or querying databases), while **Skills** are server-side middleware that preprocess every incoming request (like adding authentication headers or enriching context). Skills reside in `src/lib/skills/` and execute automatically, whereas MCP tools execute only when explicitly invoked.

### How does OmniRoute handle failures when integrating with multiple external providers?

OmniRoute implements **combo routing** in `open-sse/services/combo/` with built-in resilience mechanisms. Each provider call is wrapped by a circuit-breaker ([`src/shared/utils/circuitBreaker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/circuitBreaker.ts)) and connection-cooldown logic ([`src/sse/services/auth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/auth.ts)) to prevent cascade failures. You can configure strategies like "priority" for failover or "fusion" for consensus to maintain availability across unreliable external services.