Complete Guide to OmniRoute MCP Server Tools: Essential and Advanced Capabilities

OmniRoute exposes 104 RPC-style tools through its Multi-Client Protocol (MCP) server, enabling clients to query health metrics, manage routing combos, inspect quotas, and integrate with external knowledge bases like Obsidian and Notion.

The diegosouzapw/OmniRoute repository ships a comprehensive MCP server implementation that centralizes tool definitions in open-sse/mcp-server/schemas/tools.ts. Each tool specifies required scopes for access control, audit levels for logging granularity, and a phase designation that determines whether it loads automatically or on demand.

Essential Phase 1 Tools

Phase 1 tools are essential capabilities always loaded by the MCP server. These 24 tools cover server health, routing operations, quota management, and diagnostics according to the source definitions in tools.ts.

Health and Monitoring

• omniroute_get_health – Returns uptime, memory usage, and version information (definition L74)
• omniroute_db_health_check – Verifies SQLite health, database size, and migration status (definition L908)
• omniroute_get_session_snapshot – Dumps the current session’s internal state including context and token usage (definition L864)

Combo and Routing Management

• omniroute_list_combos – Lists all defined combo configurations (definition L120)
• omniroute_get_combo_metrics – Provides summary statistics including success/failure rates and latency for specific combos (definition L156)
• omniroute_switch_combo – Switches the active combo for the caller (definition L184)
• omniroute_route_request – Executes arbitrary requests through the routing engine (definition L286)
• omniroute_simulate_route – Simulates routing decisions without forwarding the actual request (definition L542)
• omniroute_set_routing_strategy – Changes the active auto-combo strategy (definition L611)
• omniroute_set_resilience_profile – Switches between resilience profiles such as cost-optimized or latency-optimized (definition L643)
• omniroute_test_combo – Runs one-off combo tests and returns detailed reports (definition L681)
• omniroute_best_combo_for_task – Recommends optimal combos for specific task descriptions (definition L769)
• omniroute_explain_route – Generates human-readable explanations for routing decisions (definition L815)

Quota and Cost Management

• omniroute_check_quota – Displays current quota usage per provider (definition L232)
• omniroute_cost_report – Generates detailed cost breakdowns per provider (definition L335)
• omniroute_set_budget_guard – Installs per-request token and price budgets (definition L576)
• omniroute_sync_pricing – Pulls latest provider pricing from LiteLLM (definition L944)

Web Operations and Model Catalog

• omniroute_list_models_catalog – Lists all registered models with metadata (definition L377)
• omniroute_web_search – Performs web searches using built-in providers (definition L440)
• omniroute_web_fetch – Fetches URLs via GET and returns raw body plus headers (definition L499)

Cache and Performance

• omniroute_cache_stats – Inspects in-memory cache hit/miss counters (definition L991)
• omniroute_cache_flush – Flushes all in-memory caches (definition L1014)
• omniroute_get_provider_metrics – Aggregates latency and error statistics per provider (definition L724)

Advanced Phase 2 Tools

Phase 2 tools are optional capabilities loaded on demand, bringing the total OmniRoute MCP server tool count to 104. These advanced tools handle prompt compression, connection pooling, third-party integrations, and plugin lifecycle management.

Prompt Compression Engine

The compression toolkit enables runtime prompt optimization through multiple engines:

• omniroute_compression_status – Returns current compression engine statistics (definition L1084)
• omniroute_compression_configure – Modifies compression modes and thresholds (definition L1153)
• omniroute_set_compression_engine – Selects active engines such as caveman or RTK (definition L1180)
• omniroute_list_compression_combos – Lists configured compression combos (definition L1199)
• omniroute_compression_combo_stats – Provides usage statistics per compression combo (definition L1220)

CCR Cache and One-Proxy Transport

Low-level infrastructure tools for advanced users:

• omniroute_ccr_* – Six tools (store, retrieve, inspect, list, delete, stats) providing CRUD operations on the Compression Container Runtime store (definitions L1261-L1444)
• omniroute_oneproxy_* – Three tools (fetch, rotate, stats) for interacting with the built-in one-proxy transport layer

Knowledge Base Integrations

OmniRoute MCP tools support direct integration with popular knowledge management platforms:

Obsidian Vault Tools (obsidian_*) – Defined between lines 42-314 in tools.ts:

• obsidian_check_status, obsidian_search_simple, obsidian_search_structured
• obsidian_read_note, obsidian_write_note, obsidian_sync_resolve_conflict
• Remote command execution and vault synchronization capabilities

Notion API Tools (notion_*) – Defined between lines 13-94:

• notion_search, notion_get_page, notion_list_block_children
• notion_query_database, notion_get_database, notion_append_blocks

Skill and Agent Management

• omniroute_agent_skills_* – Three tools (list, get, coverage) for discovering OmniRoute-hosted agent skills (definitions L1377-L1444)
• omniroute_skills_* – Four tools (list, enable, execute, executions) for managing user-defined skills
• omniroute_github_skills_* – Three tools (search, scan, install) for the GitHub skill marketplace
• gamification_* – Eight tools covering leaderboards, XP, token transfers, and server-wide statistics

Infrastructure and Pool Management

• omniroute_pool_* – Six tools (status, sessions, reset, warm, health, browser_status) for introspecting and controlling OpenAI-compatible connection pools
• omniroute_memory_* – Three tools (search, add, clear) for CRUD operations on the per-API-key memory store (definitions L36-L101)
• plugin_* – Eight tools (list, install, activate, deactivate, uninstall, configure, executions, scan) for full plugin lifecycle management

Utility and Discovery

• omniroute_tool_search – Searches the catalog for tools matching specific queries, enabling dynamic client discovery (definition L28)
• omniroute_pick_fastest_model – Returns the fastest responding model from a combo, used internally by auto-combo logic (definition L96)

How to Invoke OmniRoute MCP Tools

The MCP server supports three transport mechanisms for tool invocation, all routing through the central dispatcher in open-sse/mcp-server/server.ts.

CLI Invocation

The built-in MCP client provides direct command-line access:

# Check server health

omniroute --mcp call omniroute_get_health

# List available combos (requires read:combos scope)

omniroute --mcp call omniroute_list_combos

# Fetch a URL via the web tool

omniroute --mcp call omniroute_web_fetch --args '{"url": "https://api.example.com"}'

The CLI uses the HTTP transport layer defined in open-sse/mcp-server/httpTransport.ts.

HTTP/SSE Endpoint

All tools accept POST requests at the MCP SSE endpoint:

POST /api/mcp/sse
Content-Type: application/json
Authorization: Bearer <api-key>

{
  "tool": "omniroute_get_combo_metrics",
  "args": {
    "combo_id": "gpt-4-priority"
  }
}

Responses stream as Server-Sent Events (data: {...}), which is essential for tools returning large payloads like obsidian_search_structured.

Programmatic Node.js Client

import { createMcpClient } from '@omniroute/open-sse/mcp-server';

const client = await createMcpClient({
  baseUrl: 'http://localhost:3000/api/mcp/sse',
  auth: { 
    apiKey: process.env.OMNIROUTE_API_KEY  // Must match tool scopes
  }
});

// Execute tool with automatic scope enforcement
const result = await client.callTool({
  name: 'omniroute_check_quota',
  arguments: { provider: 'openai' }
});

console.log(result.usage);

The client automatically handles scope enforcement via open-sse/mcp-server/scopeEnforcement.ts and audit logging through open-sse/mcp-server/audit.ts.

Tool Configuration and Security

Each tool definition in open-sse/mcp-server/schemas/toolDefinition.ts specifies:

• Scopes: Required API key permissions (e.g., read:combos, write:memory)
• Audit Level: Logging granularity for compliance and debugging
• Phase: Loading strategy (1 for essential, 2 for on-demand)

The test suite in open-sse/mcp-server/__tests__/essentialTools.test.ts validates the exact count and presence of essential tools, ensuring catalog consistency across releases.

Summary

• OmniRoute MCP server tools total 104 RPC-style endpoints divided into 24 essential (Phase 1) and 80 advanced (Phase 2) capabilities.
• Core functions include health monitoring (omniroute_get_health), combo routing (omniroute_route_request), quota management (omniroute_check_quota), and cost reporting (omniroute_cost_report).
• Advanced integrations support Obsidian vault manipulation, Notion API operations, prompt compression engines, and plugin lifecycle management.
• Security model enforces API key scopes per tool via scopeEnforcement.ts and audits all invocations through audit.ts.
• Transport options include CLI, HTTP/SSE streaming, and programmatic Node.js clients.

Frequently Asked Questions

How do I authenticate when calling OmniRoute MCP tools?

Authentication requires an API key with scopes matching the target tool's requirements. The server validates permissions in open-sse/mcp-server/scopeEnforcement.ts before executing any tool handler. Pass the key via the Authorization: Bearer header for HTTP requests or the auth configuration object for programmatic clients.

What is the difference between Phase 1 and Phase 2 tools?

Phase 1 tools are essential capabilities always loaded at server startup, covering health checks, basic routing, and quota management. Phase 2 tools are advanced features loaded on demand, including Obsidian/Notion integrations, compression engines, and gamification features. This distinction optimizes memory usage while maintaining access to specialized functions.

Which OmniRoute MCP tools support external knowledge base integrations?

The server provides comprehensive integration tools for Obsidian (obsidian_* prefix) and Notion (notion_* prefix). Obsidian tools support vault searching, note reading/writing, and conflict resolution, while Notion tools enable page searches, database queries, and block-level manipulation. These are defined in tools.ts lines 13-94 (Notion) and lines 42-314 (Obsidian).

How can I discover available tools programmatically?

Use the omniroute_tool_search tool defined in open-sse/mcp-server/schemas/toolSearch.ts (line 28) to query the catalog dynamically. This returns matching tools with their descriptions, required scopes, and audit levels, enabling clients to adapt their behavior without hardcoding tool names.

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