OmniRoute MCP Server把 352 个 Provider 的 AI 网关接入任意 Agent 的 110 个工具编程控制面【免费下载链接】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服务器把网关的路由、配额、预算、压缩、记忆等运行时能力暴露为可编程工具让 Claude Desktop、Cursor、Copilot 或任意自定义 Agent 能以tools/call的方式监控和控制网关。本文基于仓库内 MCP Server 文档 及其 Portuguese (Portugal) 版本 的骨架展开并结合open-sse/mcp-server/源码印证启动方式、传输层、Scope 鉴权、审计日志与元数据压缩的完整实现。一、安装与启动内置零额外安装OmniRoute MCP 不需要单独安装它随网关一起启动。文档给出的两种启动方式# 方式 1stdio 传输IDE 集成推荐 omniroute --mcp # 方式 2HTTP 传输端口 20130自动挂载 /mcp 端点 omniroute --dev # MCP 自动在 /mcp 端点启动从源码看stdio 入口在 open-sse/mcp-server/server.ts约 1570 行文件尾部的启动流程会调用createMcpServer()并连接StdioServerTransport。IDE 侧也可以直接以子进程方式拉起该入口文件例如 Cursor 的.cursor/mcp.json{ mcpServers: { omniroute: { command: npx, args: [tsx, open-sse/mcp-server/server.ts], env: { OMNIROUTE_BASE_URL: http://localhost:20128, OMNIROUTE_API_KEY: your-key } } } }更完整的 Claude Desktop、VS Code 配置示例见 open-sse/mcp-server/README.md 与 docs/guides/SETUP_GUIDE.md。二、三种传输层同一个工厂三种出口MCP 服务器暴露三种传输全部由同一个createMcpServer()工厂open-sse/mcp-server/server.ts#L737创建传输入口适用场景stdioopen-sse/mcp-server/server.tsIDE 集成Claude Desktop、Cursor 等ssePOST/GET /api/mcp/ssehttpTransport.ts需要事件流的浏览器 / Agent 客户端streamable-httpPOST/GET/DELETE /api/mcp/streammcp-session-id头管理会话DELETE结束会话多会话 HTTP 客户端当前激活的 HTTP 传输由mcpTransport设置项决定切换传输时会关闭另一传输上已有的会话SSE 与 Streamable HTTP 路由都被mcpEnabled设置门控配置错误的传输时路由返回 HTTP 400 并提示去切换设置。远程访问manage-scope 旁路/api/mcp/*属于 LOCAL_ONLY 路由层级docs/security/ROUTE_GUARD_TIERS.md默认只有回环地址localhost、127.0.0.1、::1可以访问。要经隧道、反向代理或公网主机连接远程 MCP客户端必须携带具有managescope 的 API keycurl -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/stream非 manage key 或无 Bearer 会收到403 LOCAL_ONLY。此外mcp:connect是一个更窄的替代 scopedocs/frameworks/MCP-SERVER.md 的 “Per-key HTTP scope binding” 一节它只授权/api/mcp/旁路不授予任何其它管理路由权限HTTP/SSE 路径下open-sse/mcp-server/httpAuthContext.ts 会解析 Bearer key 的真实api_keys.scopes并传入 MCP SDK 的transport.handleRequest(req, { authInfo })使每次工具调用看到的都是该 key 自身的 scope。三、工具目录从文档的 16 个核心工具到当前 110 个Portuguese (Portugal) 文档docs/i18n/pt/docs/frameworks/MCP-SERVER.md记录了网关控制面的 16 个核心工具它们至今仍是目录的主体骨架Essential Tools8工具说明omniroute_get_health网关健康、熔断器、运行时长、内存、限流、缓存统计omniroute_list_combos列出全部已配置 combo模型链及其策略omniroute_get_combo_metrics指定 combo 的性能指标omniroute_switch_combo按 ID/名称切换激活的 comboomniroute_check_quota单 provider 或全部 provider 的配额状态omniroute_route_request经 OmniRoute 路由发送一次 chat completionomniroute_cost_report按时间段session/day/week/month的成本分析omniroute_list_models_catalog完整模型目录含能力与定价Advanced Tools8工具说明omniroute_simulate_route干跑路由模拟输出 fallback 树与预估成本omniroute_set_budget_guard会话预算守卫超限后执行 degrade/block/alertomniroute_set_resilience_profile应用 conservative/balanced/aggressive 弹性预设omniroute_test_combo用真实上游请求实测 combo 内所有模型omniroute_get_provider_metrics单 provider 指标p50/p95/p99 延迟、熔断状态omniroute_best_combo_for_task按任务类型 预算/延迟约束推荐 comboomniroute_explain_route解释某次历史路由决策评分因子 fallbackomniroute_get_session_snapshot完整会话快照成本、token、错误、预算状态在这 16 个工具之上当前目录已扩展为110 个唯一工具覆盖 cache、compression/CCR、memory、skills、plugins、pool、gamification、Notion/Obsidian、local corpus、Radar 与 web search/fetch 等分组。工具总数不是手工维护的数字而是由 open-sse/mcp-server/toolCount.ts 的countUniqueMcpTools()在 server.ts 中对全部 12 个工具集合MCP_TOOLS、memoryTools、skillTools、compressionTools、poolTools等做名字去重后计算——因为部分工具如 agent-skills 三件套会被有意定义在多个集合中直接累加会重复计数。各分组工具定义分别位于 open-sse/mcp-server/tools/ 下的memoryTools.ts、skillTools.ts、compressionTools.ts、notionTools.ts、obsidianTools.ts、poolTools.ts、pluginTools.ts、gamificationTools.ts等文件。工具自发现omniroute_tool_search目录扩张带来的问题是 Agent 如何找到工具。MCP 服务器注册了omniroute_tool_searchopen-sse/mcp-server/toolSearch/register.tsread:toolsscope跨全部已注册工具做关键词搜索返回紧凑的单行签名让新增能力在运行时保持可发现Agent 无需读文档。四、Scope 鉴权集中式评估与四级解析链MCP 工具通过 API key 的 scope 鉴权。每个工具声明所需 scope例如以当前权威映射为准早期文档中write:route/write:config等命名已演进Scope工具示例read:healthget_health、get_provider_metrics、simulate_route、explain_route、db_health_checkread:comboslist_combos、get_combo_metrics、test_combo、best_combo_for_taskwrite:combosswitch_combo、create_combo、set_routing_strategyread:quotacheck_quotaread:usagecost_report、get_session_snapshot、explain_routeread:modelslist_models_catalogexecute:completionsroute_request、test_comboexecute:searchweb_search、x_search、web_fetchwrite:budgetset_budget_guardwrite:resilienceset_resilience_profile、db_health_checkread:cache/write:cachecache_stats/cache_flushread:compression/write:compressioncompression_status等 /compression_configure、set_compression_engineread:notion/write:notionNotion 读写工具read:memory/write:memorymemory_search/memory_add、memory_clearread:skills/write:skills/execute:skillsskills 列表 / 启停 / 执行read:catalogagent_skills_list、agent_skills_get、agent_skills_coverage支持通配 scoperead:*授予全部读 scope*授予完全访问。源码层面评估逻辑集中在 open-sse/mcp-server/scopeEnforcement.ts135 行resolveCallerScopeContext()按固定优先级解析调用方 scopeauthInfoHTTP 传输注入的真实 key scope→_metastdio 客户端可附带→ 环境变量兜底 →noneevaluateToolScopes()对照MCP_TOOL_MAP中每个工具声明的 scope 做匹配scopeMatches()实现精确匹配与read:*风格前缀通配强制开关默认关闭server.ts#L104 中MCP_ENFORCE_SCOPES process.env.OMNIROUTE_MCP_ENFORCE_SCOPES true只有显式设为true才会拒绝缺失 scope 的调用并把拒绝记为scope_denied:reason审计条目。五、审计日志每一次工具调用都落库每次工具调用都会由 open-sse/mcp-server/audit.ts497 行写入 SQLite 的mcp_tool_audit表记录工具名、参数按每工具auditLevel哈希/截断——输入做 SHA-256 哈希不存原始 prompt、结果截断耗时ms、成功/失败标志、错误信息如有API key 哈希、时间戳scope 拒绝以scope_denied:reason记录缺失的 scope 列表。配套 REST 端点路由实现在 src/app/api/mcp/ 下目录已确认包含status、tools、sse、stream、audit端点方法说明鉴权/api/mcp/statusGET服务器状态心跳、HTTP 传输状态、审计活动摘要Management/api/mcp/toolsGET工具目录名称、描述、scope、来源端点Management/api/mcp/auditGET审计条目查询limit/offset/tool/success/apiKeyId过滤Management/api/mcp/audit/statsGET聚合统计totalCalls、successRate、avgDurationMs、top toolsManagement六、运行时心跳与元数据瘦身心跳文件stdio 传输每 5 秒把存活状态写入${DATA_DIR}/runtime/mcp-heartbeat.jsonopen-sse/mcp-server/runtimeHeartbeat.ts快照包含 pid、startedAt、lastHeartbeatAt、version、transport、scopesEnforced、allowedScopes与toolCount/api/mcp/status读取该文件加 PID 存活判断得出online。HTTP 传输则直接从进程内getMcpHttpStatus()汇报状态不写文件。描述压缩与工具基数缩减目录越大tools/list元数据占用的客户端 prompt 上下文越多。仓库提供两层“第 5 层”压缩描述压缩open-sse/mcp-server/descriptionCompressor.ts在注册/列举时用 Caveman 规则集压缩工具、prompt、resource 的描述文本同时保留代码块等结构性内容不被改写。开关优先级key_value表compression.mcpDescriptionCompressionEnabledUI 暴露于 Analytics 页→OMNIROUTE_MCP_COMPRESS_DESCRIPTIONS/OMNIROUTE_MCP_DESCRIPTION_COMPRESSION环境变量。实现上它被织入createMcpServer()对registerTool的包装server.ts#L760-L788。工具基数缩减open-sse/mcp-server/toolCardinality.ts减少有多少工具被宣告。通过MCP_TOOL_DENY黑名单或MCP_TOOL_ALLOW白名单环境变量启用deny优先于allow两变量都不设时全部工具照常宣告。关键细节注册永远成功被 profile 拒绝的工具随后在 MCP SDK handle 上被.disable()因此它不会出现在tools/list但接线保持完整——可干净地启停而无需重注册。# 从目录中剔除两个工具 MCP_TOOL_DENYomniroute_get_health,omniroute_list_combos omniroute --mcp # 只宣告路由 配额工具白名单模式 MCP_TOOL_ALLOWomniroute_route_request,omniroute_check_quota omniroute --mcp七、关键环境变量变量默认作用OMNIROUTE_BASE_URLhttp://localhost:20128MCP 调用 OmniRoute 内部 API 的基址OMNIROUTE_API_KEY空内部 API 调用转发的 Bearer keyOMNIROUTE_MCP_ENFORCE_SCOPESfalse仅true生效开启后缺失 scope 拒绝调用并记scope_deniedOMNIROUTE_MCP_SCOPES空逗号分隔的默认 scope 白名单调用方未自带 scope 时使用OMNIROUTE_MCP_FETCH_TIMEOUT_MS10000内部管理读health、combos、quota 等的超时预算OMNIROUTE_MCP_UPSTREAM_TIMEOUT_MS60000等待 provider 的 hoproute_request、web_search等超时预算MCP_TOOL_DENY/MCP_TOOL_ALLOW未设 不过滤工具基数缩减的黑/白名单DATA_DIR~/.omniroute心跳文件写至${DATA_DIR}/runtime/mcp-heartbeat.json八、源码文件地图文档中的文件表含 pt 版本引用的transport.ts/auth.ts在当前仓库中已演进以下为确认存在的实际布局文件职责open-sse/mcp-server/server.tscreateMcpServer()工厂、stdio 入口、全部 scope 化工具注册open-sse/mcp-server/httpTransport.tsSSE Streamable HTTP 传输与会话管理open-sse/mcp-server/scopeEnforcement.ts调用方解析 工具 scope 评估open-sse/mcp-server/audit.tsmcp_tool_audit审计写入与查询open-sse/mcp-server/runtimeHeartbeat.tsstdio 心跳写入open-sse/mcp-server/descriptionCompressor.ts注册/列举期描述压缩open-sse/mcp-server/toolCardinality.ts工具基数缩减过滤器open-sse/mcp-server/toolCount.tscountUniqueMcpTools()去重计数open-sse/mcp-server/httpAuthContext.tsHTTP 传输的 per-key scope 解析open-sse/mcp-server/tools/advancedTools.tsPhase 2 cache 1proxy 工具 handler1118 行open-sse/mcp-server/tools/memory、skill、compression、notion、obsidian、pool、plugin、gamification 等分组定义九、测试佐证MCP 子系统的行为有大量单测锁定可作进一步阅读入口tests/unit/mcp-server-entry.test.ts、tests/unit/t08-mcp-scope-enforcement.test.tsscope 强制语义、tests/unit/mcp-tool-count-dedup-6854.test.ts去重计数、tests/unit/mcp-connect-scope.test.tsmcp:connect旁路open-sse/mcp-server/tests/ 下的essentialTools.test.ts、advancedTools.test.ts、audit.test.ts、cacheTools.test.ts、httpAuthContext.test.ts等直接覆盖工具 handler 与传输层行为。小结OmniRoute MCP Server 的设计要点可以归纳为四条入口零安装omniroute --mcp或随--dev自动挂载一个工厂createMcpServer()支撑 stdio/SSE/Streamable HTTP 三种传输远程访问受 LOCAL_ONLY 层级与manage/mcp:connectscope 双重约束工具目录由countUniqueMcpTools()动态去重计数当前 110 个配合描述压缩与MCP_TOOL_DENY/ALLOW基数缩减控制元数据成本所有调用经 scopeEnforcement.ts 评估并落库mcp_tool_audit拒绝行为同样可审计。这套组合让任意 Agent 既能“用网关”route_request、test_combo也能“管网关”switch_combo、set_budget_guard、set_resilience_profile且每一步操作都有 scope 边界与审计留痕。【免费下载链接】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），仅供参考