OmniRoute MCP Server Documentation

Model Context Protocol server with 16 intelligent tools

Installation

OmniRoute MCP is built-in. Start it with:

omniroute --mcp

Or via the open-sse transport:

# HTTP streamable transport (port 20130)
omniroute --dev  # MCP auto-starts on /mcp endpoint

See IDE Configs for Antigravity, Cursor, Copilot, and Claude Desktop setup.

Tool	Description
`omniroute_get_health`	Gateway health, circuit breakers, uptime
`omniroute_list_combos`	All configured combos with models
`omniroute_get_combo_metrics`	Performance metrics for a specific combo
`omniroute_switch_combo`	Switch active combo by ID/name
`omniroute_check_quota`	Quota status per provider or all
`omniroute_route_request`	Send a chat completion through OmniRoute
`omniroute_cost_report`	Cost analytics for a time period
`omniroute_list_models_catalog`	Full model catalog with capabilities

Tool	Description
`omniroute_simulate_route`	Dry-run routing simulation with fallback tree
`omniroute_set_budget_guard`	Session budget with degrade/block/alert actions
`omniroute_set_resilience_profile`	Apply conservative/balanced/aggressive preset
`omniroute_test_combo`	Live-test all models in a combo via a real upstream request
`omniroute_get_provider_metrics`	Detailed metrics for one provider
`omniroute_best_combo_for_task`	Task-fitness recommendation with alternatives
`omniroute_explain_route`	Explain a past routing decision
`omniroute_get_session_snapshot`	Full session state: costs, tokens, errors

MCP tools are authenticated via API key scopes. Each tool requires specific scopes:

Scope	Tools
`read:health`	get_health, get_provider_metrics
`read:combos`	list_combos, get_combo_metrics
`write:combos`	switch_combo
`read:quota`	check_quota
`write:route`	route_request, simulate_route, test_combo
`read:usage`	cost_report, get_session_snapshot, explain_route
`write:config`	set_budget_guard, set_resilience_profile
`read:models`	list_models_catalog, best_combo_for_task

Every tool call is logged to mcp_tool_audit with:

File	Purpose
`open-sse/mcp-server/server.ts`	MCP server creation + 16 tool registrations
`open-sse/mcp-server/transport.ts`	Stdio + HTTP transport
`open-sse/mcp-server/auth.ts`	API key + scope validation
`open-sse/mcp-server/audit.ts`	Tool call audit logging
`open-sse/mcp-server/tools/advancedTools.ts`	8 advanced tool handlers