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

> Explore OmniRoute MCP server tools for health metrics, routing combos, quotas, and knowledge base integration. Discover essential and advanced capabilities in this complete guide.

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

---

**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](https://github.com/diegosouzapw/OmniRoute) repository ships a comprehensive MCP server implementation that centralizes tool definitions in [`open-sse/mcp-server/schemas/tools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/tools.ts).

### Health and Monitoring

- **`omniroute_get_health`** – Returns uptime, memory usage, and version information ([definition L74](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L74))
- **`omniroute_db_health_check`** – Verifies SQLite health, database size, and migration status ([definition L908](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L908))
- **`omniroute_get_session_snapshot`** – Dumps the current session’s internal state including context and token usage ([definition L864](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L864))

### Combo and Routing Management

- **`omniroute_list_combos`** – Lists all defined combo configurations ([definition L120](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L120))
- **`omniroute_get_combo_metrics`** – Provides summary statistics including success/failure rates and latency for specific combos ([definition L156](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L156))
- **`omniroute_switch_combo`** – Switches the active combo for the caller ([definition L184](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L184))
- **`omniroute_route_request`** – Executes arbitrary requests through the routing engine ([definition L286](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L286))
- **`omniroute_simulate_route`** – Simulates routing decisions without forwarding the actual request ([definition L542](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L542))
- **`omniroute_set_routing_strategy`** – Changes the active auto-combo strategy ([definition L611](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L611))
- **`omniroute_set_resilience_profile`** – Switches between resilience profiles such as cost-optimized or latency-optimized ([definition L643](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L643))
- **`omniroute_test_combo`** – Runs one-off combo tests and returns detailed reports ([definition L681](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L681))
- **`omniroute_best_combo_for_task`** – Recommends optimal combos for specific task descriptions ([definition L769](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L769))
- **`omniroute_explain_route`** – Generates human-readable explanations for routing decisions ([definition L815](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L815))

### Quota and Cost Management

- **`omniroute_check_quota`** – Displays current quota usage per provider ([definition L232](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L232))
- **`omniroute_cost_report`** – Generates detailed cost breakdowns per provider ([definition L335](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L335))
- **`omniroute_set_budget_guard`** – Installs per-request token and price budgets ([definition L576](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L576))
- **`omniroute_sync_pricing`** – Pulls latest provider pricing from LiteLLM ([definition L944](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L944))

### Web Operations and Model Catalog

- **`omniroute_list_models_catalog`** – Lists all registered models with metadata ([definition L377](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L377))
- **`omniroute_web_search`** – Performs web searches using built-in providers ([definition L440](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L440))
- **`omniroute_web_fetch`** – Fetches URLs via GET and returns raw body plus headers ([definition L499](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L499))

### Cache and Performance

- **`omniroute_cache_stats`** – Inspects in-memory cache hit/miss counters ([definition L991](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L991))
- **`omniroute_cache_flush`** – Flushes all in-memory caches ([definition L1014](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L1014))
- **`omniroute_get_provider_metrics`** – Aggregates latency and error statistics per provider ([definition L724](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#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](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L1084))
- **`omniroute_compression_configure`** – Modifies compression modes and thresholds ([definition L1153](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L1153))
- **`omniroute_set_compression_engine`** – Selects active engines such as `caveman` or `RTK` ([definition L1180](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L1180))
- **`omniroute_list_compression_combos`** – Lists configured compression combos ([definition L1199](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L1199))
- **`omniroute_compression_combo_stats`** – Provides usage statistics per compression combo ([definition L1220](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#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](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L1261))
- **`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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L1377))
- **`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](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/tools.ts#L36))
- **`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](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/toolSearch.ts#L28))
- **`omniroute_pick_fastest_model`** – Returns the fastest responding model from a combo, used internally by auto-combo logic ([definition L96](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/open-sse/mcp-server/schemas/pickFastestModel.ts#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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/server.ts).

### CLI Invocation

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

```bash

# 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/httpTransport.ts).

### HTTP/SSE Endpoint

All tools accept POST requests at the MCP SSE endpoint:

```http
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

```javascript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/scopeEnforcement.ts) and audit logging through [`open-sse/mcp-server/audit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/audit.ts).

## Tool Configuration and Security

Each tool definition in [`open-sse/mcp-server/schemas/toolDefinition.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/scopeEnforcement.ts) and audits all invocations through [`audit.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.