OmniRoute MCP Server 使用指南16 个智能工具、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/OmniRouteOmniRoute 内置的 MCPModel Context Protocol服务器将 AI 网关的路由、配额、成本、模型目录与弹性策略等核心能力以 16 个标准化工具的形式暴露给任意 AI AgentClaude Desktop、Cursor、Copilot 等。读完本文你将掌握如何启动 MCP 服务、在 IDE 中接入客户端、按 Scope 授权工具调用、利用审计日志追踪每一次工具执行并理解底层源码的实现原理。概述为什么用 MCP Server 管理 AI 网关OmniRoute 是一个单端点、多提供商352 providers、1200 模型的免费 MIT AI 网关。当它内置的 MCP 服务器启动后任何兼容 MCP 协议的客户端都能以统一接口调用网关能力例如查看网关健康状态与熔断器circuit breaker状态查询 Combo模型链的配置与性能指标检查各提供商的配额剩余量直接通过智能路由发送一次 chat completion模拟路由、设置预算护栏、切换弹性配置等高级运维操作。从源码看open-sse/mcp-server/server.ts是 MCP 服务器工厂与工具注册的唯一事实来源source of truth所有工具通过server.registerTool()注册并统一经过withScopeEnforcement()的 Scope 校验包装层后才到达具体 handler见 server.ts。安装与启动OmniRoute MCP 服务器内置于项目中无需额外安装依赖直接启动即可。方式一stdio 直接启动omniroute --mcp该命令以 stdio 方式运行 MCP 服务器适合 Claude Desktop、Cursor 等 IDE 客户端通过子进程方式拉起。方式二通过 open-sse 传输层启动HTTP# HTTP streamable transport (port 20130) omniroute --dev # MCP auto-starts on /mcp endpoint在--dev模式下MCP 服务器随开发服务自动在/mcp端点启动客户端通过 HTTP 方式访问。如果你希望直接运行源码入口例如在 IDE 客户端配置中引用也可以使用npx tsx open-sse/mcp-server/server.ts传输方式TransportMCP 服务器基于同一个createMcpServer()工厂server.ts支持三种传输方式覆盖不同客户端场景传输方式位置适用场景stdioopen-sse/mcp-server/server.tsIDE 集成Claude Desktop、Cursor 等sseGET/POST /api/mcp/sse通过httpTransport需要事件流的浏览器 / Agent 客户端streamable-httpPOST/GET/DELETE /api/mcp/stream多会话 HTTP 客户端使用mcp-session-id头HTTP 传输方式由mcpTransport设置项决定sse或streamable-http切换传输方式会关闭另一传输的现有会话。实现细节见 httpTransport.tsSSE 传输以单例方式复用streamable-http 每个会话创建独立的McpServer实例并带有 5 分钟空闲回收机制MCP_SESSION_IDLE_MS。远程访问manage-scope 绕过/api/mcp/*默认位于LOCAL_ONLY层级见src/server/authz/routeGuard.ts仅回环地址localhost、127.0.0.1、::1可访问。自 v3.8.2 起非回环客户端在携带Authorization: Bearer api-key且该密钥具有managescope时可连接。这是通过隧道、反向代理或公网主机名访问远程 MCP 服务器的唯一途径# 为密钥授予 manage scope在 Dashboard 的 API Keys 页面打开 # 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/stream无manage密钥或未携带 Bearer会返回403 LOCAL_ONLY。注意兄弟前缀/api/cli-tools/runtime/*是刻意不可绕过的。IDE 客户端配置MCP 服务器通过 stdio 与 IDE 集成。以下是三种主流 IDE 的配置示例完整配置说明可参考 MCP Client Configuration。Claude Desktopclaude_desktop_config.json{ 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.cursor/mcp.json{ mcpServers: { omniroute: { command: npx, args: [tsx, open-sse/mcp-server/server.ts], env: { OMNIROUTE_BASE_URL: http://localhost:20128 } } } }VS Code.vscode/settings.json{ mcp: { servers: { omniroute: { command: npx, args: [tsx, open-sse/mcp-server/server.ts], env: { OMNIROUTE_BASE_URL: http://localhost:20128 } } } } }工具清单Essential Tools8 个核心工具工具描述omniroute_get_health网关健康状态、熔断器状态、运行时长uptimeomniroute_list_combos列出所有已配置的 Combo 及其模型链omniroute_get_combo_metrics获取指定 Combo 的性能指标omniroute_switch_combo按 ID/名称切换活跃 Comboomniroute_check_quota查询单个或全部提供商的配额状态omniroute_route_request通过 OmniRoute 智能路由发送一次 chat completionomniroute_cost_report按时间周期生成成本分析omniroute_list_models_catalog完整模型目录含能力、状态、定价源码验证这些工具的 handler 直接定义在 server.ts 中。例如handleRouteRequest会向网关的/v1/chat/completions发起非流式请求并返回包含routing字段provider、combo、fallbacksTriggered、cost、latencyMs、routingExplanation的结构化结果handleCheckQuota会调用/api/usage/quota并经过normalizeQuotaResponse归一化。工具清单Advanced Tools8 个高级工具工具描述omniroute_simulate_route干跑dry-run路由模拟输出 fallback 树omniroute_set_budget_guard设置会话预算超限时执行 degrade/block/alert 动作omniroute_set_resilience_profile应用 conservative / balanced / aggressive 弹性预设omniroute_test_combo通过真实上游请求对所有模型进行组合实测omniroute_get_provider_metrics单个提供商的详细指标omniroute_best_combo_for_task按任务类型推荐最合适的 Combo 及备选方案omniroute_explain_route解释过去的某次路由决策omniroute_get_session_snapshot完整会话状态成本、token、错误等源码验证这 8 个工具的 handler 集中在 advancedTools.ts并在 server.ts 中注册。其中omniroute_test_combo需要execute:completions与read:combos双 Scope——因为它会真实调用上游提供商。认证与 Scope 权限模型MCP 工具的认证基于API key scopes权限范围。每个工具要求特定 scopescope 校验集中实现在 scopeEnforcement.ts。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_taskScope 解析优先级从 scopeEnforcement.ts 源码可以看出调用者的 scope 按以下优先级解析authInfo.scopesHTTP 传输下由 Bearer 密钥解析出的真实api_keys.scopes见open-sse/mcp-server/httpAuthContext.ts—— 优先级最高_meta.scopes/_meta.auth.scopes/_meta.omniroute.scopes环境变量OMNIROUTE_MCP_SCOPES默认允许列表都没有时视为anonymousscopes 为空数组。通配符 Scope支持通配符匹配read:*授予所有read:前缀的 scope*授予全部权限。匹配逻辑scopeMatches()位于 scopeEnforcement.ts精确相等、*或后缀通配grantedScope.endsWith(*)且requiredScope.startsWith(prefix)均视为匹配。作用域强制执行开关Scope 校验是否真正拦截调用由环境变量OMNIROUTE_MCP_ENFORCE_SCOPES控制默认关闭仅true启用。启用后缺少 scope 的调用会被拒绝并在审计日志中记录scope_denied:reasonreason 包括missing_scopes或tool_definition_missing。参见 server.ts 与evaluateToolScopes()。审计日志Audit Logging每一次工具调用都会写入 SQLite 的mcp_tool_audit表由 audit.ts 负责记录内容包括工具名称、参数、结果耗时ms、成功/失败标记API key 哈希、时间戳。安全设计输入永不落明文入参通过 SHA-256 哈希后存储hashInput()见 schemas/audit.ts输出截断结果摘要仅保留前 200 字符summarizeOutput()scope 拒绝日志权限不足的调用记录为scope_denied:reason并附上缺失 scope 列表审计失败不影响工具执行logToolCall()内部 try/catch数据库不可用如找不到storage.sqlite时打印错误并跳过绝不阻断业务。审计库驱动优先级better-sqlite3原生绑定→node:sqliteNode 22.5 内置作为透明降级方案。可以通过getRecentAuditEntries()与getAuditStats()返回totalCalls、successRate、avgDurationMs、topTools编程查询审计数据也可通过 Dashboard 查看。环境变量参考变量默认值用途OMNIROUTE_BASE_URLhttp://localhost:20128MCP 服务器调用 OmniRoute 内部 API 时的基础 URLOMNIROUTE_API_KEY空转发为内部 API 调用的Authorization: Bearer密钥OMNIROUTE_MCP_ENFORCE_SCOPESfalse仅true启用启用后缺失 scope 会拒绝工具调用并记录scope_denied:reasonOMNIROUTE_MCP_SCOPES空逗号分隔的默认可用 scope 允许列表调用者未提供自身 scopes 时使用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等待上游提供商的跳转route_request、web_search、web_fetch的中止预算MCP_TOOL_DENY未设置 不过滤逗号分隔的黑名单工具名从tools/list中剔除MCP_TOOL_ALLOW未设置 不过滤逗号分隔的白名单工具名仅保留这些工具allow-list 模式DATA_DIR~/.omniroute心跳文件写入${DATA_DIR}/runtime/mcp-heartbeat.json其中超时预算通过 fetchTimeout.ts 的mcpFetchTimeoutSignal()实现——管理读操作走management档10s等待上游提供商的操作走upstream档60s。运行时心跳Runtime Heartbeatstdio 传输每 5 秒将进程存活状态写入${DATA_DIR}/runtime/mcp-heartbeat.json实现见 runtimeHeartbeat.ts。Dashboard 的/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 }isMcpHeartbeatOnline()依据 3 个心跳周期默认 15 秒判定过期并校验进程 PID 是否存活。核心源码文件文件职责open-sse/mcp-server/server.tsMCP 服务器工厂 16 个工具注册 essential 工具 handleropen-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/runtimeHeartbeat.tsstdio 心跳写入mcp-heartbeat.jsonopen-sse/mcp-server/descriptionCompressor.ts工具/提示词/资源注册表的描述压缩open-sse/mcp-server/toolCardinality.ts工具清单基数缩减reduceToolManifestopen-sse/mcp-server/schemas/tools.tsZod schema 工具注册表MCP_TOOLSopen-sse/mcp-server/tools/advancedTools.ts8 个高级工具 handleropen-sse/mcp-server/tests/单元测试essential/advanced/audit/httpAuth 等进阶描述压缩与工具清单瘦身为了降低 MCP 工具目录对模型上下文prompt的成本项目提供了两层优化1. 描述压缩Description Compression工具/提示词/资源的描述文本在注册/列举时使用 Caveman 压缩规则集压缩同时通过 preserve-block 机制保留代码块等结构化内容不被破坏。可通过key_value设置表中的compression.mcpDescriptionCompressionEnabled默认开启UI 对应 Analytics → MCP description compression或环境变量OMNIROUTE_MCP_COMPRESS_DESCRIPTIONSfalse关闭。2. 工具基数缩减Tool Cardinality Reduction, F4.3默认情况下所有 110 个工具都会在tools/list中公告。通过环境变量可控制公告数量从而节省客户端模型为工具目录付出的 token 成本# 从目录中剔除两个工具黑名单 MCP_TOOL_DENYomniroute_get_health,omniroute_list_combos omniroute --mcp # 仅公告路由 配额工具白名单模式 MCP_TOOL_ALLOWomniroute_route_request,omniroute_check_quota omniroute --mcp该功能默认关闭两个变量均未设置时不过滤deny优先于allow。实现位于 toolCardinality.ts 的reduceToolManifest()与readMcpToolProfileFromEnv()被过滤工具在注册时正常成功随后调用 MCP SDK 的.disable()从而不出现在tools/list中但保持内部接线完整。estimateManifestTokens()可估算缩减前后的清单 token 成本对比。附REST API 端点端点方法描述认证/api/mcp/statusGET服务器状态心跳、HTTP 传输状态、审计活动摘要Managementsession/admin/api/mcp/toolsGET工具目录名称、描述、scopes、phase、源端点Management/api/mcp/sseGET/POSTSSE 传输端点由mcpEnabledmcpTransport sse门控API key scopes/api/mcp/streamPOST/GET/DELETEStreamable HTTP 传输使用mcp-session-id头DELETE结束会话API key scopes/api/mcp/auditGET审计日志查询过滤limit、offset、tool、success、apiKeyIdManagement/api/mcp/audit/statsGET聚合审计统计totalCalls、successRate、avgDurationMs、top toolsManagement对应路由文件位于src/app/api/mcp/{status,tools,sse,stream,audit,audit/stats}/route.ts。SSE 与 Streamable HTTP 传输在 Settings 中启用mcpEnabled并选定正确的mcpTransport之前会被拦截传输方式配置错误时路由返回 HTTP 400 并提示切换设置。常见使用场景MCP 工具天然适合构建自动化运维 Agent典型闭环如下健康巡检omniroute_get_health检查熔断器与缓存状态配额感知omniroute_check_quota在决策前确认各提供商剩余配额路由预演omniroute_simulate_route以 dry-run 方式预览路由路径与成本不产生真实调用预算控制omniroute_set_budget_guard设置会话预算与超限动作决策解释omniroute_explain_route复盘某次请求为何路由到特定提供商含评分因子与 fallback 链会话复盘omniroute_get_session_snapshot汇总成本、token、错误与预算状态。这套能力组合使 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），仅供参考