OmniRoute MCP Server 接入指南16 个智能工具让任何 AI 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本指南以 docs/i18n/fr/docs/frameworks/MCP-SERVER.md 为骨架围绕 OmniRoute 内置的 Model Context ProtocolMCP服务器展开它把网关的健康检查、Combo 路由、配额查询、成本审计等能力封装为 16 个标准化 MCP 工具供 Claude Desktop、Cursor、Copilot、Claude Code 等任意 MCP 客户端调用。读完本文你将掌握 MCP 服务器的启动方式、16 个工具的用途与权限映射、IDE 集成配置、远程访问与审计机制并能在源码层面理解其实现位置。英文权威文档见 docs/frameworks/MCP-SERVER.md其工具清单已随版本演进扩展至 110 个。OmniRoute 为什么需要一个内置的 MCP ServerOmniRoute 是一个统一 AI 网关一个端点接入 350 提供商、1200 模型并提供基于配额的自动回退quota-aware auto-fallback、RTKCaveman 压缩等能力。问题是这些网关智能哪些 provider 健康、哪个 combo 在跑、预算还剩多少、一次请求为什么被路由到某家原本只存在于网关进程内部普通 AI Agent 无法触达。MCPModel Context ProtocolServer 正是为了解决这个问题而内置在仓库中的。它把 OmniRoute 的运维与路由能力以工具tool的形式暴露给 AI Agent让 Agent 能够程序化地监控、控制和优化网关而不再依赖人工登录面板。法语文档开篇即点明其定位Model Context Protocol server with 16 intelligent tools。从架构上看MCP Server 位于 AI Agent / IDE 与 OmniRoute 网关之间Agent 通过 stdio 或 HTTP 的 MCP 协议发起工具调用MCP Server 内部经 Scope 校验后调用网关的 HTTP API默认http://localhost:20128如/v1/chat/completions、/api/combos、/api/usage等。这与 open-sse/mcp-server/README.md 中给出的架构图完全一致。安装与启动内置零安装一条命令拉起MCP Server 是 OmniRoute 的内置组件无需单独安装。法语文档给出的启动方式有两种。方式一stdio 传输直接启动omniroute --mcp这是最直接的启动方式MCP Server 通过标准输入输出stdio与宿主 IDE/Agent 通信适合 Claude Desktop、Cursor 等桌面客户端集成。方式二open-sse 传输HTTP 自动挂载# HTTP streamable transport端口 20130 omniroute --dev # MCP auto-starts on /mcp endpoint以开发模式启动网关时MCP Server 会自动挂载到/mcp端点。更精确地说HTTP 传输由 open-sse/mcp-server/httpTransport.ts 负责它把 MCP Server 运行在 Next.js 进程内部从而可以在设置面板里动态开关而无需重启omniroute --mcp进程。版本提示法语文档对应 16 工具8 essential 8 advanced的早期版本英文权威文档 docs/frameworks/MCP-SERVER.mdv3.8.50已把清单扩充为 110 个唯一工具并指出其数量由countUniqueMcpTools()在 open-sse/mcp-server/server.ts 中计算。迁移到新版本后应以后者为准。三种传输方式与远程访问MCP Server 统一由createMcpServer()工厂open-sse/mcp-server/server.ts创建对外暴露三种传输传输方式位置适用场景stdioopen-sse/mcp-server/server.tsIDE 集成Claude Desktop、Cursor 等ssePOST/GET /api/mcp/sse经httpTransport需要事件流的浏览器/Agent 客户端streamable-httpPOST/GET/DELETE /api/mcp/stream多会话 HTTP 客户端mcp-session-id头当前激活哪种 HTTP 传输由mcpTransport设置决定切换传输会关闭另一条传输上已建立的会话。streamable-http的会话有 5 分钟空闲回收机制MCP_SESSION_IDLE_MS见 httpTransport.ts。远程访问manage scope 绕过/api/mcp/*默认属于 LOCAL_ONLY 层级见src/server/authz/routeGuard.ts只有 loopback 主机localhost、127.0.0.1、::1能访问。从 v3.8.2 起非 loopback 客户端只要携带的 API Key 具备managescope就可以通过隧道、反向代理或公网域名访问远程 MCP Server这也是唯一途径# 先授予 manage scope在 dashboard 的 API Keys 页面打开该 Key 的 # Management Access或在创建 Key 时 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/stream未带 Key 或 Key 无managescope 时返回403 LOCAL_ONLY。注意兄弟前缀/api/cli-tools/runtime/*是刻意不可绕过的。英文文档还补充了一个更窄的权限方案mcp:connect#7895它只授权/api/mcp/的绕过不授予任何其他管理路由访问权是远程 MCP 专用调用的低权限替代由src/shared/constants/managementScopes.ts导出、在src/server/authz/policies/management.ts中校验。IDE 配置法语文档指向的 IDE 配置说明对应英文权威文档中的 MCP Client Configuration 一节原文档内部的integrations/ide-configs.md链接已由仓库现行路径取代覆盖 Claude Desktop、Cursor、Cline 及兼容 MCP 客户端的配置方法。以 Claude Desktop 的claude_desktop_config.json为例来自 open-sse/mcp-server/README.md{ mcpServers: { omniroute: { command: node, args: [path/to/omniroute/open-sse/mcp-server/server.ts], env: { OMNIROUTE_BASE_URL: http://localhost:20128, OMNIROUTE_API_KEY: your-key } } } }Cursor 与 VS Code 的配置大同小异command换成npxargs换成[tsx, open-sse/mcp-server/server.ts]并设置OMNIROUTE_BASE_URL环境变量。16 个智能工具全解析法语文档将工具划分为 Essential8 个与 Advanced8 个两组。这些工具名均带omniroute_前缀命名即作用域。Essential Tools8 个工具说明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_route_request是核心执行工具Agent 传model、messages等参数网关会按路由策略选择 provider 并自动回退。omniroute_list_combos支持includeMetrics参数一次调用即可拿到各 Combo 的实时表现为后续决策提供依据。Advanced Tools8 个工具说明omniroute_simulate_route路由干跑dry-run模拟输出回退树omniroute_set_budget_guard设置会话预算超出后执行降级/拦截/告警动作omniroute_set_resilience_profile应用 conservative/balanced/aggressive 预设omniroute_test_combo用真实上游请求实测 Combo 内所有模型omniroute_get_provider_metrics单个 provider 的详细指标omniroute_best_combo_for_task基于任务适配度推荐 Combo含备选omniroute_explain_route解释某次历史路由决策omniroute_get_session_snapshot完整会话快照成本、Token、错误这两组工具的互补性很强simulate_route可以先于真实调用预估成本与回退路径其输出含fallbackTree.bestCaseCostbest_combo_for_task支持taskType、budgetConstraint、latencyConstraint约束set_budget_guard与get_session_snapshot组合可实现预算内自动降级的自愈 Agent。一次典型的自愈循环可以这样串联参照 open-sse/mcp-server/README.md 的 Python 用例# 1. 拉取健康状态找出熔断器 OPEN 的 provider health await session.call_tool(omniroute_get_health, {}) # 2. 切换到更保守的韧性预设 await session.call_tool(omniroute_set_resilience_profile, {profile: conservative}) # 3. 让网关推荐替代 Combo 并激活 best await session.call_tool(omniroute_best_combo_for_task, {taskType: coding}) combo_id json.loads(best.content[0].text)[recommendedCombo][id] await session.call_tool(omniroute_switch_combo, {comboId: combo_id, active: True})从实现上看Advanced 组全部由 open-sse/mcp-server/tools/advancedTools.ts 提供 handler所有工具的参数 SchemaZod与注册表集中在 open-sse/mcp-server/schemas/tools.ts。认证API Key Scope 细粒度授权MCP 工具通过 API Key 的 scope 进行认证每个工具要求特定 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该表是早期版本映射在现行英文权威文档 docs/frameworks/MCP-SERVER.md 的 Authentication Scopes 一节中scope 体系已细化例如route_request改为execute:completions、预算与韧性拆分为write:budget/write:resilience并新增read:cache、read:compression、read:radar、read:plugins等数十个 scope。无论哪个版本都遵循同样的设计原则校验逻辑集中在 open-sse/mcp-server/scopeEnforcement.ts 的evaluateToolScopes()支持通配符 scoperead:*授予全部读权限*授予全部权限scopeMatches()实现后缀通配匹配调用者的 scope 按authInfo → _meta → OMNIROUTE_MCP_SCOPES 环境变量 → none的优先级解析resolveCallerScopeContext()scope 强制校验默认关闭需显式设置OMNIROUTE_MCP_ENFORCE_SCOPEStrue才生效开启后缺失 scope 的调用会被拒绝并在审计日志中记录scope_denied:reason。在 HTTP/SSE 传输下open-sse/mcp-server/httpTransport.ts 会通过resolveMcpCallerAuthInfo()解析 Bearer Key 的真实api_keys.scopes并传给 MCP SDK 的transport.handleRequest(req, { authInfo })从而让每个工具调用拿到的权限真实反映该 Key 的 scope#7895stdio 传输没有逐调用者身份仍走_meta/环境变量回退链。审计日志每次工具调用都可追溯法语文档明确指出每次工具调用都会记录到mcp_tool_audit包含工具名、参数、结果耗时ms、成功/失败API Key 哈希、时间戳实现位于 open-sse/mcp-server/audit.ts。源码注释进一步揭示了隐私处理细节输入按 SHA-256 哈希存储绝不保存明文 prompt输出截断为 200 字符。Scope 拒绝也会以scope_denied:reason形式连同缺失 scope 列表一并入库。审计数据可通过面板或 REST 端点/api/mcp/audit、/api/mcp/audit/stats查询后者给出totalCalls、successRate、avgDurationMs、top tools 聚合。附带的管理 REST APIMCP 传输层之外还配套了一批管理端点源码在src/app/api/mcp/{status,tools,sse,stream,audit,audit/stats}/route.ts端点方法说明认证/api/mcp/statusGET服务状态心跳、HTTP 传输状态、审计活动摘要Management/api/mcp/toolsGET工具目录名称、描述、scopes、阶段、来源端点Management/api/mcp/sseGET/POSTSSE 传输端点受mcpEnabledmcpTransportsse门控API Key scopes/api/mcp/streamPOST/GET/DELETEStreamable HTTP 传输mcp-session-id头DELETE 结束会话API Key scopes/api/mcp/auditGET审计日志查询limit/offset/tool/success/apiKeyId过滤Management/api/mcp/audit/statsGET审计聚合统计Management注意SSE 与 Streamable HTTP 两条传输都要求先在设置中开启mcpEnabled并选择正确的mcpTransport配置错传输时路由返回 HTTP 400 并提示切换设置。常用环境变量速查以下变量来自英文权威文档用于进程级配置变量默认值用途OMNIROUTE_BASE_URLhttp://localhost:20128MCP Server 调用内部 API 的基础 URLOMNIROUTE_API_KEY空以Authorization: Bearer转发给内部 API 调用的 KeyOMNIROUTE_MCP_ENFORCE_SCOPESfalse仅true开启开启后缺失 scope 即拒绝并记录scope_denied:reasonOMNIROUTE_MCP_SCOPES空逗号分隔的默认可用 scope 白名单OMNIROUTE_MCP_COMPRESS_DESCRIPTIONS未设置开启设为0/false/off/no关闭描述压缩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未设置不过滤逗号分隔的要丢弃的工具名黑名单MCP_TOOL_ALLOW未设置不过滤逗号分隔的仅保留工具名白名单DATA_DIR~/.omniroute心跳文件写入${DATA_DIR}/runtime/mcp-heartbeat.json面向大模型客户端的两个压缩机制英文权威文档还详细介绍了两个与减少模型上下文负担直接相关的机制对 16 工具时代之后的新版本尤其重要描述压缩Description Compression在注册/列举时压缩工具、prompt、resource 的描述文本采用 Caveman 规则集getRulesForContext(all, full)并保留代码块等结构化内容。实现位于 open-sse/mcp-server/descriptionCompressor.ts通过设置项compression.mcpDescriptionCompressionEnabled默认开启或环境变量关闭。工具数量约简Tool Cardinality Reduction进一步减少tools/list中宣布的工具数量。它是纯函数 open-sse/mcp-server/toolCardinality.ts 的reduceToolManifest()默认关闭、显式设置MCP_TOOL_DENY或MCP_TOOL_ALLOW才生效且deny优先于allow# 从目录中剔除两个工具 MCP_TOOL_DENYomniroute_get_health,omniroute_list_combos omniroute --mcp # 只宣布路由与配额工具白名单模式 MCP_TOOL_ALLOWomniroute_route_request,omniroute_check_quota omniroute --mcp被过滤的工具注册照常进行只是在 MCP SDK 句柄上.disable()因此不会出现在tools/list中而连线保持完整。运行时心跳与在线判定stdio 传输每 5 秒将存活状态写入${DATA_DIR}/runtime/mcp-heartbeat.json写入器为 open-sse/mcp-server/runtimeHeartbeat.ts仪表盘通过/api/mcp/status读取该文件加 PID 存活来判定online。HTTP 传输则直接由进程内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 入口、带 scope 的工具注册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/resource 注册表描述压缩open-sse/mcp-server/toolCardinality.ts工具清单约简reduceToolManifestopen-sse/mcp-server/schemas/tools.tsZod Schema 工具注册表MCP_TOOLSopen-sse/mcp-server/tools/advancedTools.tsAdvanced 组工具 handleropen-sse/mcp-server/tools/memoryTools.ts / skillTools.ts / notionTools.ts 等各领域工具定义新版本扩展src/app/api/mcp/{status,tools,sse,stream,audit,audit/stats}/route.ts管理 REST 端点法语文档列出的transport.ts与auth.ts在现行仓库中已分别演化为httpTransport.ts与scopeEnforcement.ts新增工具族memory、skills、Notion、Radar、插件、Obsidian 等详见英文权威文档的 Files 一节及 open-sse/mcp-server/README.md。小结从 16 工具到 110 工具的演进主线法语文档描绘的是 MCP Server 的成熟骨架内置启动 → 16 个工具8 基础 8 进阶→ API Key Scope 细粒度认证 → 全量审计 → 清晰的文件布局。这一设计主线在英文权威文档 v3.8.50 中并未改变只是在工具数量110、Scope 粒度execute:*、write:budget、read:radar等、传输能力streamable-http 多会话、远程访问mcp:connect窄权限绕过和面向大模型上下文的优化描述压缩、工具数量约简、MCP 无障碍树过滤上持续深化。无论接入的是 16 工具还是 110 工具的版本这套监控—决策—执行—审计闭环都让 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/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考