OmniRoute MCP Server 完全指南内置 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 Code、Cursor、Claude Desktop、Cline 等 MCP 客户端可以直接把网关的路由、配额、成本、模型目录、压缩、缓存、记忆、技能、代理池与上下文源能力暴露为可调用的工具。本篇指南以官方 MCP Server 文档为核心结合仓库源码逐层讲解其安装方式、三大传输通道、工具目录、API Key 权限体系、审计机制与调优手段读完即可在任意 MCP 客户端中安全地接入并驾驭这套工具集。本指南对应的官方文档为 docs/frameworks/MCP-SERVER.md英文权威版本文引用细节以其为准社区西班牙语翻译版见 docs/i18n/es/docs/frameworks/MCP-SERVER.md核心内容安装方式、工具表、认证 Scope、审计日志、文件清单保持一致。OmniRoute MCP Server 是什么OmniRoute 本身是一个统一的多提供商 AI 网关一个端点背后聚合了数百个提供商与上千个模型负责智能路由、配额感知的自动回退、语义缓存与上下文压缩。MCP Server 则把这张网关的管理面变成一组结构化工具——Agent 不再需要手动 curl 管理 API而是通过标准的 MCP 工具调用直接查询网关健康状态、切换 Combo、检查配额、发起一次经过路由器的补全请求或解释上一次路由决策。从源码看这一切都汇聚在createMcpServer()工厂函数open-sse/mcp-server/server.ts中。该工厂基于modelcontextprotocol/sdk构建服务器实例并完成三类注册工具registerTool全部走withScopeEnforcement()包装先做权限校验再执行提示registerPrompt与资源registerResource注册时同样经过描述压缩动态工具根据 skills 表中启用的技能以skill_name命名动态注册并预留RESERVED_MCP_NAMES集合防止命名冲突server.ts。工具数量随版本演进持续扩充。早期版本即西班牙语文档快照内置 16 个工具而当前英文主文档与源码中的countUniqueMcpTools()open-sse/mcp-server/toolCount.ts统计结果为110 个唯一工具45 个规范定义含六个 CCR 生命周期工具、agent-skills 三件套、omniroute_radar_catalog与omniroute_x_search再加上记忆3、技能4、GitHub 技能3、代理池6、游戏化8、插件8、Notion6、Obsidian22、本地语料3以及两个仅限 RTK 的压缩工具。安装与启动MCP Server 随 OmniRoute 内置无需额外安装。启动方式有两种# 方式一独立 stdio 进程 omniroute --mcp# 方式二通过 open-sse 传输层 omniroute --dev # MCP 自动在 /mcp 端点启动HTTP streamable transport端口 20130第一条命令进入startMcpStdio()server.ts初始化数据库后创建服务器实例用StdioServerTransport连接并通过startMcpHeartbeat()周期写入心跳文件同时在SIGINT/SIGTERM时优雅地 checkpoint 并关闭审计数据库。需要特别说明的是stdio 模式下stdout 被保留给 JSON-RPC 协议进程内的console.log/warn会在模块加载前被重定向到 stderr避免污染协议流。IDE 接入配置Claude Desktop、Cursor、Cline 等参见 SETUP_GUIDE.md 的 MCP Client Configuration 章节。传输层stdio、SSE 与 Streamable HTTPMCP Server 同时暴露三种传输方式全部由同一个createMcpServer()工厂支撑传输方式位置适用场景stdioopen-sse/mcp-server/server.tsIDE 集成Claude Desktop、Cursor 等ssePOST/GET /api/mcp/sse需要事件流的浏览器/Agent 客户端streamable-httpPOST/GET/DELETE /api/mcp/stream多会话 HTTP 客户端使用mcp-session-id头HTTP 传输的实际形态由mcpTransport设置决定切换传输方式会关闭另一侧的既有会话。从 httpTransport.ts 的源码看其实现细节包括SSE 模式是单例ensureSseServer()只维护一个McpServer实例新客户端initialize时先关闭旧单例再重建Streamable HTTP 是每会话一个实例会话以mcp-session-id头关联Map中保存会话句柄空闲超过 5 分钟会被后台清扫器回收MCP_SESSION_IDLE_MS 5 * 60 * 1000会话过期自动恢复客户端带着失效的会话 ID 发起initialize时服务端视作全新初始化并返回新的mcp-session-id符合规范对 404 再初始化的要求见 httpTransport.tsHTTP 状态上报走进程内getMcpHttpStatus()不写文件DELETE /api/mcp/stream用于主动结束会话。远程访问manage 作用域旁路/api/mcp/*属于 LOCAL_ONLY 层级——默认只有回环地址localhost、127.0.0.1、::1可以访问。自 v3.8.2 起非回环客户端只要携带Authorization: Bearer api-key且该 Key 带有manage作用域即可连接这是通过隧道、反向代理或公网域名访问远程 MCP Server 的唯一途径# 授予 manage 作用域在仪表盘 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非 manage 作用域的 Key或不带 Bearer会被返回403 LOCAL_ONLY。值得一提的细节是manage或admin作用域对只想使用 MCP 的调用方来说过宽因此新增了窄权限作用域mcp:connect由src/shared/constants/managementScopes.ts导出它只授权/api/mcp/旁路不授予任何其他管理路由权限并且刻意不加入MANAGEMENT_API_KEY_SCOPES。而/api/cli-tools/runtime/*前缀故意不可旁路——详见路由守卫层级文档。核心工具Essential ToolsPhase 1核心工具面向日常运维与路由查询是西班牙语文档中首批 8 个工具在当前版本中该集合已扩为 14 个见下文扩展清单。每个工具都封装了一个或多个 OmniRoute 内部 API 端点输入输出由 Zod schema 严格约束定义于 open-sse/mcp-server/schemas/tools.ts。工具说明omniroute_get_health网关健康状态运行时间、内存、熔断器、限流、缓存统计omniroute_list_combos列出所有已配置的 Combo模型链及其策略与可选指标omniroute_get_combo_metrics某个 Combo 的性能指标请求数、成功率、延迟、成本omniroute_switch_combo按 ID/名称激活或停用 Comboomniroute_check_quota单个或全部提供商的配额状态已用/总量/剩余百分比/重置时间/token 健康度omniroute_route_request通过 OmniRoute 智能路由发送一次聊天补全请求omniroute_cost_report指定时间段的成本分析会话/日/周/月omniroute_list_models_catalog完整模型目录能力、状态、价格源码级的实现细节omniroute_get_healthserver.ts并发拉取/api/monitoring/health、/api/resilience、/api/rate-limits三个端点并做防御性归一化Promise.allSettled保证单个端点失败不影响整体若某数据源取不到会显式列入degraded数组而不是伪装成空/零值。健康输出还附带自适应准入控制adaptive admission的压缩视图——按排队成本排序取前 10 个租户。omniroute_route_requestserver.ts将请求转发到/v1/chat/completions强制stream: falseMCP 工具总是返回非流式结果可通过combo参数携带x-combo头显式指定路由返回结果同时包含模型响应内容、token 用量与路由元数据实际提供商、触发的回退次数、成本、延迟、路由解释。omniroute_check_quota通过provider或connectionId参数路由到/api/usage/quota返回结果经normalizeQuotaResponse()统一契约。omniroute_cost_report的period参数映射为内部时间范围session/day → 1d、week → 7d、month → 30d聚合totalCost、请求数、token 用量、按提供商/按模型的分布以及预算余量。当前版本的扩展工具当前版本的核心工具已从 8 个扩展到 14 个新增了创建 Comboomniroute_create_combo走既有 Combo API 校验、Radar 目录查询omniroute_radar_catalog本地签名目录可带提供商/模型族过滤、工具发现omniroute_tool_search、Web 搜索omniroute_web_search走配置的搜索提供商不包含 X/Twitter、X 搜索omniroute_x_search通过 xAI/SuperGrok 或xquik-search需要对应后端凭据与网页抓取omniroute_web_fetchFirecrawl/Jina Reader/Tavily 等支持 markdown/html/links/screenshot 格式。高级工具Advanced ToolsPhase 2高级工具提供模拟、治理与诊断能力对应西班牙语文档中的第二批 8 个工具当前版本该集合已扩为 11 个。它们定义在 open-sse/mcp-server/tools/advancedTools.ts。工具说明omniroute_simulate_route路由干跑模拟不实际执行输出完整回退树omniroute_set_budget_guard会话预算守卫超限时执行 degrade/block/alert 动作omniroute_set_resilience_profile应用 conservative / balanced / aggressive 预设omniroute_test_combo通过真实上游请求在线测试 Combo 中所有模型omniroute_get_provider_metrics单个提供商的详细指标p50/p95/p99 延迟与熔断器状态omniroute_best_combo_for_task任务适配度推荐带预算/延迟约束的候选与备选omniroute_explain_route解释某次历史路由决策评分因子与回退链omniroute_get_session_snapshot完整会话状态成本、token、错误、预算守卫状态当前版本还加入了运行时切换路由策略omniroute_set_routing_strategy支持 priority/weighted/round-robin/auto 等、数据库健康诊断omniroute_db_health_check可检测并可选自动修复 Combo 悬空引用、孤儿行等数据库漂移以及定价同步omniroute_sync_pricing从 LiteLLM 等外部来源同步价格支持dryRun。另外还有omniroute_pick_fastest_model从实时遥测中选择最快的可用提供商-模型组合。认证与作用域Scopes体系所有 MCP 工具都通过 API Key 的作用域Scope完成认证与授权判定逻辑集中在 open-sse/mcp-server/scopeEnforcement.ts并以装饰器withScopeEnforcement()server.ts统一包装每个工具处理器调用resolveCallerScopeContext()解析调用方身份与作用域来源再经evaluateToolScopes()比对必需作用域不满足时返回Insufficient MCP scopes错误并把拒绝记录以scope_denied:reason写入审计。西班牙语文档给出了早期 8 组作用域映射如下表当前版本的映射已细化到近 30 组例如模拟路由现在要求read:healthread:combos实时测试要求execute:completionsread:combos见英文主文档 docs/frameworks/MCP-SERVER.md作用域工具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注意早期快照中的write:route与write:config在当前版本中已细化为execute:completions、write:budget、write:resilience等更精确的作用域请以英文主文档的最新表格为准。作用域解析的优先级与通配符resolveCallerScopeContext()按以下优先级解析调用方可用的作用域scopeEnforcement.tsextra.authInfo.scopes——HTTP 传输下由resolveMcpCallerAuthInfo()从真实api_keys.scopes行解析参见 httpAuthContext.ts最高优先级extra._meta中的scopes/auth.scopes/omniroute.scopes字段——stdio 等无请求对象的场景使用环境变量OMNIROUTE_MCP_SCOPES提供的兜底清单全空则视为anonymous。作用域匹配支持通配符read:*匹配任意read:x*表示完全授权。每个工具要求的精确作用域定义在schemas/tools.ts的MCP_TOOL_MAP中。强制开关与 per-key 绑定作用域默认不强制需显式设置OMNIROUTE_MCP_ENFORCE_SCOPEStrue才会拒绝缺权的调用并记录scope_denied:reason。HTTP/SSE 传输还实现了 per-key 的 HTTP 作用域绑定#7895httpTransport.ts通过handleRequestWithAuthInfo()把真实 Key 的作用域随{ authInfo }传给 MCP SDK使每个工具调用拿到的extra.authInfo.scopes反映 Bearer Key 自身的权限——stdio 没有 per-caller 身份仍然走_meta/env 回退链。审计日志每一次工具调用都会被写入 SQLite 的mcp_tool_audit表实现在 open-sse/mcp-server/audit.ts记录内容包括工具名、参数SHA-256 哈希绝不落盘明文敏感输入、结果截断为 200 字符摘要耗时毫秒、成功/失败标志与错误信息API Key 哈希来自OMNIROUTE_API_KEY_ID、时间戳作用域拒绝以scope_denied:reason记入error_code。审计实现上有两个值得一提的健壮性设计数据库驱动按better-sqlite3→node:sqliteNode ≥ 22.5的顺序回退原生绑定缺失时审计能力自动降级而非崩溃见 audit.ts审计写入失败绝不会破坏工具执行Never let audit failure break tool execution。查询侧提供queryAuditEntries()支持tool/success/apiKeyId过滤limit 上限 500与getAuditStats()24 小时窗口内的总调用数、成功率、平均耗时、Top 10 工具并暴露为 REST 端点/api/mcp/audit与/api/mcp/audit/stats。环境变量与调优变量默认值作用OMNIROUTE_BASE_URLhttp://localhost:20128MCP Server 调用 OmniRoute 内部 API 的基础地址OMNIROUTE_API_KEY空转发为内部 API 调用的Authorization: BearerOMNIROUTE_MCP_ENFORCE_SCOPESfalse仅true开启开启后缺失作用域的工具调用被拒绝并记录scope_denied:reasonOMNIROUTE_MCP_SCOPES空逗号分隔的默认可用作用域白名单调用方未提供自身作用域时使用OMNIROUTE_MCP_COMPRESS_DESCRIPTIONS未设置 开启设为0/false/off/no时禁用 MCP 描述压缩OMNIROUTE_MCP_DESCRIPTION_COMPRESSION未设置 开启同上开关的别名OMNIROUTE_MCP_FETCH_TIMEOUT_MS10000内部管理读取健康、弹性、Combo、配额、用量的中止预算OMNIROUTE_MCP_UPSTREAM_TIMEOUT_MS60000等待上游提供商的中止预算route_request、web_search、web_fetchMCP_TOOL_DENY未设置 不过滤逗号分隔的要从tools/list中移除的工具名黑名单MCP_TOOL_ALLOW未设置 不过滤逗号分隔的保留工具名白名单模式DATA_DIR~/.omniroute心跳文件写入${DATA_DIR}/runtime/mcp-heartbeat.json超时预算在 fetchTimeout.ts 中实现管理读请求走OMNIROUTE_MCP_FETCH_TIMEOUT_MS而会等待上游提供商的请求路由、搜索、抓取显式改用OMNIROUTE_MCP_UPSTREAM_TIMEOUT_MS——如handleRouteRequest中的注释所述#9717这类跳转绝不能继承管理读的短预算。描述压缩Description CompressionMCP 工具、提示词与资源的描述可以在注册/列出的过程中压缩以减小暴露给客户端的元数据体积从而降低模型为工具目录付出的提示词上下文成本。实现位于 open-sse/mcp-server/descriptionCompressor.ts通过createMcpServer()内的compressMcpRegistryMetadata接入。压缩使用 Caveman 规则集getRulesForContext(all, full)并做保留块提取代码片段、围栏块等确保结构性内容不被改写。开关方式有三设置表key_value中的compression.mcpDescriptionCompressionEnabled仪表盘 UI 为Analytics → MCP description compression、进程级环境变量OMNIROUTE_MCP_COMPRESS_DESCRIPTIONSfalse或OMNIROUTE_MCP_DESCRIPTION_COMPRESSIONfalse。实时统计通过omniroute_compression_status的analytics.mcpDescriptionCompression字段暴露并标注source: mcp_metadata_estimate以区别于真实提供商用量账单。工具基数缩减Tool Cardinality Reduction描述压缩缩小每个工具的元数据而工具基数缩减更进一步减少向客户端公布多少个工具——tools/list清单里的工具越少客户端模型为目录付出的每请求 token 成本越低即第 5 层压缩。这是位于 open-sse/mcp-server/toolCardinality.ts 的纯函数过滤器reduceToolManifest接入注册循环。默认关闭、显式开启只有设置了下面两个环境变量之一才生效否则 110 个工具原样公布变量模式MCP_TOOL_DENY黑名单——列出的工具始终从tools/list移除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被过滤工具的处理方式是注册照常成功然后对 SDK 句柄调用.disable()因此它不会出现在tools/list中但接线保持不变干净的启用/禁用无需重新注册。readMcpToolProfileFromEnv(process.env)toolCardinality.ts解析环境变量两变量皆空时返回null不过滤。更丰富的ToolProfile结构还支持作用域交集过滤allowScopes含read:*通配匹配与确定性的maxTools上限但这两个旋钮需要完整清单参与注册目前未通过环境变量暴露estimateManifestTokens()可用于对比缩减前后的清单 token 成本。MCP 可访问性树过滤器v3.8.0独立于上述压缩工具OmniRoute 还内置了一个执行后过滤器对 MCP 浏览器/可访问性工具的返回结果做压缩后再交还给 Agent。它不是工具而是透明运行在任意包含冗长可访问性树/浏览器快照文本≥ 2000 字符的工具结果上。关键行为将 ≥ 30 行连续重复的同级行折叠为头部 尾部摘要保留 Playwright/computer-use 所需的[refeXX]锚点对超大文本 50,000 字符硬截断并给出导航提示浏览器快照负载预期节省 60%–80%。配置项为全局设置中的compression.mcpAccessibility迁移 056实现位于open-sse/services/compression/engines/mcpAccessibility/详细文档见 COMPRESSION_ENGINES.md 的 MCP Accessibility Tree Filter 章节。运行时心跳与 REST 管理端点stdio 传输每 5 秒把存活状态写入${DATA_DIR}/runtime/mcp-heartbeat.json仪表盘/api/mcp/status读取该文件并结合 PID 存活判定online。心跳快照形如{ 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 }配套的 REST 管理端点源码位于src/app/api/mcp/{status,tools,sse,stream,audit,audit/stats}/route.ts端点方法说明认证/api/mcp/statusGET服务器状态心跳、HTTP 传输状态、审计活动摘要Managementsession/admin/api/mcp/toolsGET工具目录名称、描述、作用域、阶段、来源端点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/auditGETmcp_tool_audit审计条目过滤limit、offset、tool、success、apiKeyIdManagement/api/mcp/audit/statsGET聚合审计统计totalCalls、successRate、avgDurationMs、Top 工具Management注意SSE 与 Streamable HTTP 两种传输在设置中启用mcpEnabled并选中对应mcpTransport之前都会被阻塞配置了错误的传输方式时路由返回 HTTP 400 并附带切换设置的提示。相关文件清单文件用途open-sse/mcp-server/server.tsMCP 服务器工厂、stdio 入口、带作用域的工具注册open-sse/mcp-server/httpTransport.tsSSE Streamable HTTP 传输会话管理open-sse/mcp-server/scopeEnforcement.ts工具作用域评估与调用方解析open-sse/mcp-server/httpAuthContext.tsHTTP 调用方身份解析与内部转发头构造open-sse/mcp-server/audit.ts工具调用审计日志mcp_tool_auditopen-sse/mcp-server/runtimeHeartbeat.tsstdio 心跳写入mcp-heartbeat.jsonopen-sse/mcp-server/descriptionCompressor.ts工具/提示词/资源注册元数据压缩open-sse/mcp-server/toolCardinality.ts工具清单缩减MCP_TOOL_DENY/MCP_TOOL_ALLOWopen-sse/mcp-server/schemas/tools.tsZod schema 与工具注册表MCP_TOOLS45 条open-sse/mcp-server/tools/advancedTools.tsPhase 2 缓存 1proxy 工具处理器open-sse/mcp-server/tools/compressionTools.ts压缩工具处理器open-sse/mcp-server/tools/memoryTools.ts记忆工具定义3 个open-sse/mcp-server/tools/skillTools.ts技能工具定义4 个open-sse/mcp-server/tools/notionTools.tsNotion 上下文源工具定义6 个src/app/api/mcp/{status,tools,sse,stream,audit,audit/stats}/route.ts上述 REST 管理端点src/lib/notion/api.ts、src/lib/db/notion.tsNotion REST 客户端与 token 持久化tests/unit/notion-api.test.ts、tests/unit/notion-tools.test.tsNotion 客户端与作用域强制测试调试提示MCP 调用被莫名拦截时当一个 MCP 调用看起来被拦截且无合理解释时请同时检查两处MCP 审计日志/api/mcp/audit是否有scope_denied:*条目以及error_code列中的具体拒绝原因Guardrails 审计轨迹vision-bridge、pii-masker、prompt-injection 等护栏实现于src/lib/guardrails/运行在聊天管线中会在进入 MCP 工具/路由层之前处理请求并输出结构化违规记录——一次请求完全可能在触及 MCP 作用域强制层之前就被护栏拒绝。此外MCP 之外还有两个同版发布的相邻框架需要区分Cloud Agentscodex-cloud、cursor-cloud、devin、jules 等进程外 AI 编码代理通过独立的/api/v1/agents/*REST 面暴露不属于 MCP 工具目录调用它们不消耗 MCP 作用域参见 CLOUD_AGENT.mdGuardrails 则作为前/后执行过滤器在聊天管线内生效参见 docs/security/GUARDRAILS.md。这些框架相关的完整 MCP 扩展工具记忆、技能、Notion/Obsidian 上下文源、本地语料等的详细说明可以继续阅读英文主文档 docs/frameworks/MCP-SERVER.md 与 AGENT-SKILLS.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），仅供参考