OmniRoute MCP Server 实战指南把 AI 网关的路由、配额与成本能力暴露给 Agent【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRouteOmniRoute 内置了一个 Model Context ProtocolMCP服务器将网关的核心智能——组合Combo管理、配额检查、路由请求、成本分析——封装为一组可供任意 AI AgentClaude Desktop、Cursor、Copilot 等调用的工具。本篇指南围绕 MCP Server 的启动方式、核心与进阶工具清单、基于 API Key 作用域scope的鉴权模型和工具调用审计日志展开并结合open-sse/mcp-server/下的源码实现说明其调用链与底层机制读完即可在本地把 OmniRoute 变成你可编程控制的 AI 网关控制面。快速启动OmniRoute 的 MCP 服务器是内置组件无需单独安装有两种启动方式# 方式一stdio 传输供 IDE 的 MCP 客户端直接拉起 omniroute --mcp# 方式二HTTP streamable 传输端口 20130 # MCP 服务随开发服务自动启动挂载在 /mcp 端点 omniroute --dev从源码结构看两种传输共用同一个工厂函数createMcpServer()stdio 入口在 server.ts 中通过StdioServerTransport建立连接HTTP 侧则走POST/GET/DELETE /api/mcp/stream与POST/GET /api/mcp/sse两个路由源码见 httpTransport.ts 与src/app/api/mcp/下的各 route 文件。工具总数不是硬编码的而是由 toolCount.ts 中的countUniqueMcpTools()在注册时动态统计——当前仓库版本统计出110 个唯一工具覆盖路由、缓存、压缩、记忆、技能、代理池、Radar 等域远超本文档基线版本的 16 个工具本文以文档定义的 8 个 Essential 8 个 Advanced 工具为主干讲解它们至今仍是日常使用频率最高的核心集合。核心工具Essential Tools8 个工具说明omniroute_get_health网关健康状态、熔断器、运行时长omniroute_list_combos列出所有已配置的组合及其模型omniroute_get_combo_metrics查看指定组合的性能指标omniroute_switch_combo按 ID 或名称切换激活的组合omniroute_check_quota查看单个或全部供应商的配额状态omniroute_route_request通过 OmniRoute 发送一次聊天补全请求omniroute_cost_report按时间段生成成本分析报表omniroute_list_models_catalog带能力信息的完整模型目录这些工具覆盖了监控—切换—执行—核算的完整闭环omniroute_get_health让你了解网关状态omniroute_list_combos/omniroute_get_combo_metrics观察组合表现omniroute_switch_combo做运行时切换omniroute_route_request直接走网关路由发请求最后用omniroute_check_quota和omniroute_cost_report核账。每个工具的输入参数都由 Zod schema 定义并集中注册在 schemas/tools.ts 的MCP_TOOLS表中例如 server.ts 顶部导入了getHealthInput、listCombosInput、routeRequestInput、costReportInput等十余个 schema保证客户端收到的工具定义与运行时校验完全一致。进阶工具Advanced Tools8 个工具说明omniroute_simulate_route干跑dry-run路由模拟返回回退树omniroute_set_budget_guard设置会话级预算支持降级/阻断/告警动作omniroute_set_resilience_profile应用保守/均衡/激进弹性预设omniroute_test_combo通过真实上游请求逐一实测组合内的所有模型omniroute_get_provider_metrics查看单个供应商的详细指标omniroute_best_combo_for_task基于任务适配度推荐组合及备选方案omniroute_explain_route解释一次历史路由决策的原因omniroute_get_session_snapshot获取完整会话状态成本、token、错误这 8 个进阶工具的处理器统一实现在 advancedTools.ts 中如handleSimulateRoute、handleSetBudgetGuard、handleTestCombo、handleGetProviderMetrics、handleExplainRoute、handleGetSessionSnapshot等见 server.ts 的导入清单。几个值得注意的实现细节omniroute_route_request等需要等待上游供应商响应的工具使用独立的中断预算OMNIROUTE_MCP_UPSTREAM_TIMEOUT_MS默认 60000 ms而内部管理类读取健康、组合、配额、用量使用OMNIROUTE_MCP_FETCH_TIMEOUT_MS默认 10000 ms实现位于 fetchTimeout.ts 的mcpFetchTimeoutSignalMCP 工具内部调用 OmniRoute 网关自身的 REST API/api/combos、/api/usage等基础地址由OMNIROUTE_BASE_URL默认http://localhost:20128解析见 server.ts。鉴权基于 API Key 作用域Scope的细粒度控制MCP 工具通过 API Key 的作用域鉴权每个工具要求特定 scopeScope覆盖的工具read:healthget_health, get_provider_metricsread:comboslist_combos, get_combo_metricswrite:combosswitch_comboread:quotacheck_quotawrite:routeroute_request, simulate_route, test_comboread:usagecost_report, get_session_snapshot, explain_routewrite:configset_budget_guard, set_resilience_profileread:modelslist_models_catalog, best_combo_for_task作用域裁决的集中实现在 scopeEnforcement.tsresolveCallerScopeContext()按authInfo _meta 环境变量的优先级解析调用方身份与 scope 集合evaluateToolScopes()则在每次工具调用前判定是否放行。是否强制鉴权由环境变量OMNIROUTE_MCP_ENFORCE_SCOPES控制——默认关闭server.ts 中仅当值精确为true时才启用开启后缺失 scope 的调用会被拒绝并记入审计日志。当前仓库版本中还引入了mcp:connect这一窄作用域远程非回环地址客户端访问/api/mcp/*时持有manage/admin或mcp:connectscope 的 Bearer Key 即可通过避免为纯 MCP 客户端发放过宽的管理权限。一个典型的本地 stdio 配置如下摘自 open-sse/mcp-server/README.md# 必填MCP 服务访问 OmniRoute 内部 API 的基础地址 export OMNIROUTE_BASE_URLhttp://localhost:20128 # 可选作为 Authorization: Bearer 转发的 API Key export OMNIROUTE_API_KEYyour-api-key # 可选启用 scope 强制校验默认关闭 export OMNIROUTE_MCP_ENFORCE_SCOPEStrue export OMNIROUTE_MCP_SCOPESread:health,read:combos,read:quota,read:usage,read:models,execute:completions其中OMNIROUTE_MCP_SCOPES是调用方未自带 scope 时的兜底白名单逗号分隔OMNIROUTE_MCP_SCOPES为空且调用方无 scope 时工具按未强制模式运行。审计日志每次工具调用都留痕每一次 MCP 工具调用都会被写入 SQLite 的mcp_tool_audit表记录内容包括工具名、参数、结果耗时毫秒、成功/失败标志API Key 哈希、时间戳实现位于 audit.ts从源码头部注释和实现可以确认其隐私设计输入参数经过 SHA-256 哈希后存储避免落盘敏感提示词输出摘要被截断到 200 字符scope 拒绝事件以scope_denied:reason形式单独记录并附缺失的 scope 列表。该模块同时适配better-sqlite3与 Node 内置node:sqlite两种驱动见 audit.ts 中的createNodeSqliteAuditAdapter保证在不同运行环境下审计不中断。排查某次调用被拒时应同时检查 MCP 审计日志的scope_denied:*条目——这能区分鉴权层拒绝与请求在执行中失败。源码结构对照文档中列出的关键文件与仓库实际位置的对应关系如下当前仓库中 HTTP 传输已拆分为独立模块比文档基线更清晰文件职责open-sse/mcp-server/server.tsMCP 服务器工厂、stdio 入口、带 scope 的工具注册open-sse/mcp-server/httpTransport.tsSSE Streamable HTTP 传输与会话管理open-sse/mcp-server/scopeEnforcement.ts工具 scope 判定与调用方解析open-sse/mcp-server/audit.ts工具调用审计日志mcp_tool_audit表open-sse/mcp-server/tools/advancedTools.ts8 个进阶工具的处理器实现open-sse/mcp-server/schemas/tools.ts工具的 Zod schema 与MCP_TOOLS注册表MCP 服务器的整体架构在 open-sse/mcp-server/README.md 中有图示AI Agent/IDE 通过 MCP 协议stdio 或 HTTP连接 OmniRoute MCP Server服务器内部经过 Scope Enforcement → 工具执行 → Audit Logger 三层处理再以内部 HTTP 调用落到 20128 端口网关的/v1/chat/completions、/api/combos、/api/usage等端点。IDE 配置将上述 MCP 服务器接入 IDE 客户端时参考 SETUP_GUIDE 中的 MCP Client Configuration 章节其中给出了 Claude Desktop、Cursor、Cline 等客户端的具体配置方式更完整的 MCP 客户端接入示例含claude_desktop_config.json写法见 open-sse/mcp-server/README.md。小结OmniRoute 的 MCP Server 用16 个基础工具当前仓库已扩展至 110 个 scope 鉴权 SQLite 审计三件套把网关的路由、配额、成本能力开放给任意 Agent。落地要点本地集成用omniroute --mcpstdio最省事需要多客户端共享或远程接入时启用 HTTP 传输并注意/api/mcp/*默认仅回环可达需带manage/mcp:connectscope 的 Key生产环境建议显式打开OMNIROUTE_MCP_ENFORCE_SCOPEStrue为不同 Agent 发放最小 scope 的 Key并定期通过审计日志复核工具调用行为。【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
