How to Integrate OmniRoute with External Tools and Services

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, 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 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) and connection-cooldown mechanisms (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:

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:

{
  "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 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:

// 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 to activate it on every incoming request.

Automate with CLI Tool Invocation

Execute tools directly from bash scripts without HTTP latency:

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:

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) 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) and connection-cooldown logic (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.

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