OmniRoute MCP Server 深度指南内置 110 智能工具网关让 Agent 直接监控与操控 AI 路由【免费下载链接】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本文以 OmniRoute 仓库中挪威语版 MCP-SERVER.md 为骨架并对照其英文原文 MCP-SERVER.md 及open-sse/mcp-server/目录下的源码系统讲解 OmniRoute 内建 MCP Server 的安装启动、传输方式、工具分类、权限模型、审计机制与源码结构。读完本文你将掌握如何让 Claude Desktop、Cursor、Copilot 等 MCP 客户端通过 16 个核心工具与完整工具目录程序化地监控健康状态、切换路由组合Combo、检查配额、模拟路由、设置预算护栏并理解其细粒度 scope 鉴权与 SQLite 审计的实现原理。一、OmniRoute MCP Server 是什么OmniRoute 是一个免费MIT 协议的 AI 网关本身提供统一 API 端点对接数百个 Provider 与上千个模型。而MCP ServerModel Context Protocol Server是它面向 AI Agent 的控制面任何遵循 MCP 协议的客户端——Claude Desktop、Cursor、VS Code Copilot乃至自研 Agent——都可以像调用工具一样监控、控制和优化 OmniRoute 网关而不需要人工打开仪表盘。挪威语版文档给出的定义是一句话Model Context Protocol server with 16 intelligent tools带 16 个智能工具的 MCP Server。英文原文则给出了更完整的口径MCP 服务器通过open-sse/mcp-server/server.ts中的countUniqueMcpTools()计算得到110 个唯一工具——包括 45 个规范定义含 CCR 生命周期六工具、agent-skills 三件套、omniroute_radar_catalog、omniroute_x_search外加 memory3、skills4、GitHub skills3、pool6、gamification8、plugins8、Notion6、Obsidian22、local corpus3以及两个仅 RTK 模式可用的压缩工具。因此本文的16 个智能工具对应 Essential8 Advanced8两个核心阶段其余工具属于缓存、压缩、记忆、技能、代理池、上下文源等扩展面。从源码结构看open-sse/mcp-server/整个 MCP Server 被拆成 server 工厂、HTTP 传输、scope 校验、审计、心跳、描述压缩、工具注册等独立模块工具定义集中在schemas/tools.tsZod 模式 MCP_TOOLS注册表45 条处理逻辑按领域分散在tools/下多个文件。二、安装与启动内置无需单独部署MCP Server 是OmniRoute 内置能力不需要额外安装任何插件。启动方式有两种1. 通过 CLI 直接启动stdioomniroute --mcp这条命令以stdio 传输方式启动 MCP 服务适合在 IDE/桌面客户端的配置文件中声明为子进程启动命令。2. 通过 open-sse 传输HTTP# HTTP streamable transport端口 20130 omniroute --dev # MCP 自动挂载到 /mcp 端点omniroute --dev开发模式下MCP 服务会自动在/mcp端点启动采用HTTP streamable transport方便浏览器端或需要事件流的远程 Agent 连接。3. 直接运行 MCP Server 源码也可以不经过 CLI直接用 tsx 运行服务器入口见 open-sse/mcp-server/README.mdnpx tsx open-sse/mcp-server/server.ts三种方式的入口最终都汇聚到同一个工厂函数createMcpServer()open-sse/mcp-server/server.ts保证工具目录、scope 校验、审计逻辑完全一致。IDE 配置Claude Desktop、Cursor、Antigravity、Copilot 等客户端的具体接入配置挪威语文档指向integrations/ide-configs.md该文件为文档站内引用英文原文指向 SETUP_GUIDE.md 中的 MCP Client Configuration 一节。此外 open-sse/mcp-server/README.md 提供了 Claude Desktopclaude_desktop_config.json、Cursor.cursor/mcp.json、VS Code.vscode/settings.json三种可直接复制的 JSON 配置示例。三、核心工具Essential Tools8 个Phase 1文档给出了第一梯队 8 个核心工具它们覆盖了网关最常用的看健康、列组合、查配额、发请求操作工具说明omniroute_get_health网关健康状态熔断器、运行时长omniroute_list_combos列出所有已配置的 Combo 及其模型omniroute_get_combo_metrics指定 Combo 的性能指标omniroute_switch_combo按 ID/名称切换当前激活的 Comboomniroute_check_quota按 Provider 或全部查看配额状态omniroute_route_request通过 OmniRoute 发送一次聊天补全请求omniroute_cost_report指定时间段的成本分析omniroute_list_models_catalog完整模型目录含能力、状态、定价英文原文对其中部分工具补充了更精确的能力说明例如omniroute_get_health除 uptime/memory/circuit breakers 外还包含rate limits 与 cache stats并可返回自适应准入车道adaptive admission的压力数据详见 open-sse/mcp-server/README.md 的 Adaptive Admission Lane Data 小节字段包括virtualLanes、pressure、utilization、laneQueuedCount等omniroute_switch_combo支持激活或停用omniroute_route_request走的是智能路由管线含 fallback。四、高级工具Advanced Tools8 个Phase 2第二梯队 8 个高级工具把能力从查询提升到规划与治理工具说明omniroute_simulate_route干跑dry-run路由模拟输出 fallback 树omniroute_set_budget_guard会话预算护栏超支时执行 degrade/block/alert 动作omniroute_set_resilience_profile应用 conservative / balanced / aggressive 弹性预设omniroute_test_combo通过真实上游请求对 Combo 内所有模型做在线测试omniroute_get_provider_metrics单个 Provider 的详细指标omniroute_best_combo_for_task面向任务类型的模型推荐附备选方案omniroute_explain_route解释过去某次路由决策omniroute_get_session_snapshot完整会话快照成本、token、错误英文原文为高级工具补充了两个额外的演进工具合计 Phase 2 为 11 个omniroute_set_routing_strategy运行时更新 Combo 策略priority / weighted / auto 等scopewrite:combos与omniroute_db_health_check诊断并可选自动修复数据库漂移如损坏的 combo 引用、孤儿行scoperead:healthwrite:resilience。这些工具的处理逻辑集中在 open-sse/mcp-server/tools/advancedTools.ts输入模式定义在 open-sse/mcp-server/schemas/tools.ts。omniroute_best_combo_for_task接收taskType如coding、budgetConstraint、latencyConstraint参数可在预算与延迟双重约束下给出推荐。五、权限模型API Key Scope 细粒度鉴权MCP 工具通过API Key scope鉴权挪威语文档给出了 8 个 scope 与工具的对应关系Scope覆盖工具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英文原文中的 scope 表更细execute:completions、write:budget、write:resilience、pricing:write、read:cache、read:compression、read:proxies、read:notion、read:memory、read:skills、read:catalog、read:radar、read:gamification、read:plugins、read:obsidian、read:local-corpus等并且明确指出支持通配符 scoperead:*授予所有读权限*授予全部权限。实现层面的 scope 判定scope 校验集中在 open-sse/mcp-server/scopeEnforcement.tsresolveCallerScopeContext()按优先级解析调用者身份与 scopeauthInfoHTTP 下由 Bearer key 的真实 scopes 填充→_meta可携带scopes/auth.scopes/omniroute.scopes→OMNIROUTE_MCP_SCOPES环境变量 → 空evaluateToolScopes()在OMNIROUTE_MCP_ENFORCE_SCOPEStrue时才强制校验匹配规则支持精确匹配、*全通配与read:*前缀通配缺失 scope 时返回allowed:false并给出missing列表审计日志中记录scope_denied:reason。远程访问与mcp:connect窄权限 scope/api/mcp/*默认处于LOCAL_ONLY层见 ROUTE_GUARD_TIERS.md只允许 loopbacklocalhost、127.0.0.1、::1访问。自 v3.8.2 起非 loopback 客户端只要携带一个带managescope 的 Bearer key 即可连接——这是通过隧道、反向代理或公网域名访问远程 MCP 的唯一途径# 授予 manage scope在仪表盘 API Keys 页面打开该 key 的 # Management Access或在创建时 POST scopes:[manage]。 # 然后从远程 MCP 客户端连接 curl -i \ -H Host: your-public-host.example \ -H Authorization: Bearer sk-… \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2025-03-26,capabilities:{},clientInfo:{name:my-client,version:0}}} \ https://your-public-host.example/api/mcp/streammanagescope 对只谈 MCP 的调用者来说过于宽泛因此 src/shared/constants/managementScopes.ts 导出了更窄的附加 scopemcp:connectMCP_CONNECT_SCOPE mcp:connect它只授权/api/mcp/这一个 LOCAL_ONLY 例外不授予任何其他管理路由权限并被刻意排除在MANAGEMENT_API_KEY_SCOPES之外——这是远程 MCP-only 调用者的低权限替代方案。非managekey或没有 Bearer访问返回403 LOCAL_ONLY。注意兄弟前缀/api/cli-tools/runtime/*故意不可绕过。六、审计日志每次工具调用都可追溯每次工具调用都会被写入 SQLite 的mcp_tool_audit表实现见 open-sse/mcp-server/audit.ts记录字段包括工具名、参数、结果耗时毫秒、成功/失败标志、错误信息如有API key 哈希、时间戳。出于安全考虑输入参数以 SHA-256 哈希存储绝不保存明文 prompt输出截断为 200 字符摘要。scope 拒绝会以scope_denied:reason形式连同缺失的 scope 列表一并记录。审计写入失败不会中断工具执行Never let audit failure break tool execution。英文原文还指出审计数据库的驱动选择有优先级优先使用 better-sqlite3 原生绑定若原生二进制缺失如部分全局安装 / Docker 场景会自动回退到 Node 22.5 内置的node:sqlite。数据库路径为${DATA_DIR}/storage.sqlite默认~/.omniroute/storage.sqlite。配套 REST 审计接口端点方法说明/api/mcp/auditGET审计日志查询过滤limit、offset、tool、success、apiKeyId/api/mcp/audit/statsGET聚合统计totalCalls、successRate、avgDurationMs、top tools七、环境变量速查变量默认值作用OMNIROUTE_BASE_URLhttp://localhost:20128MCP Server 调用 OmniRoute 内部 API 的基础地址OMNIROUTE_API_KEY空以Authorization: Bearer转发给内部 API 的 keyOMNIROUTE_MCP_ENFORCE_SCOPESfalse仅true启用启用后缺失 scope 会拒绝工具调用并在审计日志记scope_denied:reasonOMNIROUTE_MCP_SCOPES空逗号分隔的可用 scope白名单调用方未自带 scope 时使用OMNIROUTE_MCP_COMPRESS_DESCRIPTIONS未设置开启设为0/false/off/no时禁用 MCP 描述压缩OMNIROUTE_MCP_DESCRIPTION_COMPRESSION未设置开启同一开关的别名OMNIROUTE_MCP_FETCH_TIMEOUT_MS10000内部管理读取health/resilience/combos/quota/usage的中止预算OMNIROUTE_MCP_UPSTREAM_TIMEOUT_MS60000等待 Provider 的跳点route_request、web_search、web_fetch的中止预算MCP_TOOL_DENY未设置不过滤逗号分隔的、从tools/list中剔除的工具名黑名单MCP_TOOL_ALLOW未设置不过滤逗号分隔的、仅保留的工具名白名单模式DATA_DIR~/.omniroute心跳文件写入${DATA_DIR}/runtime/mcp-heartbeat.json其中 scope 解析逻辑OMNIROUTE_MCP_SCOPES、OMNIROUTE_MCP_ENFORCE_SCOPES的读取可以直接在 open-sse/mcp-server/server.ts 顶部看到const MCP_ENFORCE_SCOPES process.env.OMNIROUTE_MCP_ENFORCE_SCOPES true; const MCP_ALLOWED_SCOPES new Set( (process.env.OMNIROUTE_MCP_SCOPES || ) .split(,) .map((s) s.trim()) .filter(Boolean) );八、工具目录瘦身Tool Cardinality ReductionF4.3描述压缩减小的是每个工具的元数据体积而工具基数缩减更进一步——直接减少tools/list清单里宣告的工具数量从而降低客户端模型为工具目录付出的每请求 token 成本即第 5 层压缩。该能力是默认关闭、显式开启的只有当MCP_TOOL_DENY或MCP_TOOL_ALLOW任一环境变量被设置时才会生效两者都未设置时110 个工具原样宣告。# 从目录中剔除两个工具 MCP_TOOL_DENYomniroute_get_health,omniroute_list_combos omniroute --mcp # 白名单模式只宣告路由 配额两个工具 MCP_TOOL_ALLOWomniroute_route_request,omniroute_check_quota omniroute --mcp规则语义见 open-sse/mcp-server/toolCardinality.ts 中的reduceToolManifest与readMcpToolProfileFromEnvdeny 优先于 allow工具名以逗号分隔、去空白、忽略空项被过滤工具的移除方式是注册始终成功被 profile 拒绝的工具随后被.disable()从而不出现在tools/list中但接线保持不变干净的启停无需重新注册更完整的ToolProfile还支持allowScopes按 scope 交集过滤支持read:*通配和确定性的maxTools上限但这两个旋钮需要注册时的完整 manifest目前未通过环境变量暴露tools/list级别钩子是已跟踪的后续工作estimateManifestTokens()可用于对比缩减前后的 manifest token 成本。九、运行时心跳与在线状态stdio 传输每 5 秒将存活状态写入${DATA_DIR}/runtime/mcp-heartbeat.json实现见 open-sse/mcp-server/runtimeHeartbeat.ts。仪表盘/api/mcp/status读取该文件并结合 PID 存活判断onlineHTTP 传输则改为读取进程内的getMcpHttpStatus()不写文件。心跳快照示例{ pid: 12345, startedAt: 2026-05-13T12:34:56.000Z, lastHeartbeatAt: 2026-05-13T12:35:01.000Z, version: 1.8.1, transport: stdio, scopesEnforced: false, allowedScopes: [], toolCount: 110 }十、源码文件地图便于深入阅读文件职责open-sse/mcp-server/server.tsMCP Server 工厂、stdio 入口、全部工具注册createMcpServer()open-sse/mcp-server/httpTransport.tsSSE Streamable HTTP 传输会话管理、空闲回收open-sse/mcp-server/scopeEnforcement.ts工具 scope 评估与调用者解析open-sse/mcp-server/audit.ts工具调用审计日志mcp_tool_auditopen-sse/mcp-server/runtimeHeartbeat.tsstdio 心跳写入mcp-heartbeat.jsonopen-sse/mcp-server/descriptionCompressor.ts工具 / prompt / 资源注册表的描述压缩open-sse/mcp-server/toolCardinality.ts工具基数缩减MCP_TOOL_DENY/MCP_TOOL_ALLOWopen-sse/mcp-server/schemas/tools.tsZod 模式 工具注册表MCP_TOOLS45 条open-sse/mcp-server/tools/advancedTools.tsPhase 2 高级工具 缓存 1proxy 处理器open-sse/mcp-server/tools/memoryTools.ts记忆工具3 个open-sse/mcp-server/tools/skillTools.ts技能工具4 个open-sse/mcp-server/tools/notionTools.tsNotion 上下文源工具6 个open-sse/mcp-server/tests/essentialTools / advancedTools / audit / scope 等单测十一、典型用法一个 Python Agent 的完整工作流下面基于 open-sse/mcp-server/README.md 中的官方 Python 示例演示如何用 MCP SDK 走完查健康 → 列组合 → 推荐 → 设预算 → 发请求 → 取快照全流程pip install mcpimport asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): server StdioServerParameters( commandnpx, args[tsx, open-sse/mcp-server/server.ts], env{ OMNIROUTE_BASE_URL: http://localhost:20128, OMNIROUTE_API_KEY: your-key, }, ) async with stdio_client(server) as (read, write): async with ClientSession(read, write) as session: await session.initialize() # 1. 检查网关健康 health await session.call_tool(omniroute_get_health, {}) print(Health:, health.content[0].text) # 2. 列出带指标的组合 combos await session.call_tool(omniroute_list_combos, { includeMetrics: True }) print(Combos:, combos.content[0].text) # 3. 为编码任务推荐最优组合预算 ≤ $0.50延迟 ≤ 5000ms best await session.call_tool(omniroute_best_combo_for_task, { taskType: coding, budgetConstraint: 0.50, latencyConstraint: 5000, }) print(Best combo:, best.content[0].text) # 4. 设置会话预算护栏超支降级到廉价档 budget await session.call_tool(omniroute_set_budget_guard, { maxCost: 1.00, action: degrade, degradeToTier: cheap, }) print(Budget guard:, budget.content[0].text) # 5. 走智能路由发送请求 response await session.call_tool(omniroute_route_request, { model: claude-sonnet-4, messages: [ {role: user, content: Write a Python hello world} ], role: coding, }) print(Response:, response.content[0].text) # 6. 获取会话快照 snapshot await session.call_tool(omniroute_get_session_snapshot, {}) print(Session:, snapshot.content[0].text) asyncio.run(main())该 README 还提供了TypeScriptMCP SDK Client StdioClientTransport、Go直连/api/monitoring/health、/api/combos、/api/usage/quota、/v1/models等 REST 接口示例以及自愈 Agent监测熔断器 → 切换弹性预设 → 自动切换组合、预算感知编码 Agent、组合基准测试 Agent、路由事后剖析 Agent、模型发现 Agent等场景均可作为扩展阅读。十二、小结开箱即用omniroute --mcp或omniroute --dev/mcp端点即可启动无需独立安装工具齐全Essential 8 Advanced 8 共 16 个核心智能工具完整目录达 110 个含缓存、压缩、记忆、技能、代理池、上下文源等权限可控所有工具按 API Key scope 鉴权支持read:*/*通配远程访问需manage或窄权限mcp:connectscope可观测每次调用写入 SQLitemcp_tool_audit输入 SHA-256 哈希、输出 200 字截断另提供/api/mcp/audit与/api/mcp/audit/stats查询接口可瘦身MCP_TOOL_DENY/MCP_TOOL_ALLOW环境变量可在宣告层削减工具数量为上下文窗口省 token源码清晰scope、审计、心跳、描述压缩、工具注册各司其职全部位于open-sse/mcp-server/下配有完整单测。如需了解更多关联框架可继续阅读英文原文 MCP-SERVER.md 中列出的 Cloud Agentssrc/lib/cloudAgent/与 GuardrailsGUARDRAILS.md两节以及压缩引擎 COMPRESSION_ENGINES.md 与 RTK_COMPRESSION.md。【免费下载链接】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），仅供参考