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/OmniRoute本文是 OmniRoute 内置 Model Context ProtocolMCP服务器的技术实战指南。OmniRoute 在发行包中内置了一个完整的 MCP 服务器允许 Claude Desktop、Cursor、Cline、OpenCode 等 MCP 客户端通过统一网关操作路由、组合combo、配额、压缩、内存、技能、代理池与上下文源等能力。读完本文你将掌握omniroute --mcp的启动方式、stdio / SSE / Streamable HTTP 三种传输层的选型、核心与高级工具的调用语义、API Key 作用域scope认证模型以及描述压缩、工具基数削减与审计日志等生产级运行机制。英文原版权威文档见 docs/frameworks/MCP-SERVER.md本文以该文档及其德文镜像 docs/i18n/de/docs/frameworks/MCP-SERVER.md为骨架结合仓库源码展开。安装与启动OmniRoute MCP 服务器是内置能力无需单独安装。启动方式有两种# 方式一独立 stdio 进程IDE 集成首选 omniroute --mcp# 方式二通过 open-sse 传输层HTTP # MCP 会自动挂载在 /mcp 端点默认端口 20130 omniroute --dev方式二下 MCP 服务器运行在 Next.js 进程内部对应源码 open-sse/mcp-server/httpTransport.ts 中“Runs the MCP server inside the Next.js process”的设计因此可以不经--mcp独立进程、直接通过仪表盘开关来启用/停用。需要说明的是--dev形态下 MCP 实际上挂载于/api/mcp/sse与/api/mcp/stream两个 HTTP 路由源码路径 src/app/api/mcp/sse/route.ts 与 src/app/api/mcp/stream/route.ts仪表盘“Settings → MCP”中的mcpEnabled开关与mcpTransport选择控制其启停与传输模式未启用或传输模式不匹配时路由返回 HTTP 400 并提示切换设置。三种传输层stdio、SSE 与 Streamable HTTP所有传输层共享同一个createMcpServer()工厂open-sse/mcp-server/server.ts因此工具集、作用域与审计行为完全一致差异只在传输通道传输层位置适用场景stdioopen-sse/mcp-server/server.ts 中的startMcpStdio()Claude Desktop、Cursor 等本地 IDE 集成进程生命周期由客户端拉起sseGET/POST /api/mcp/sse经httpTransport需要事件流的浏览器/Agent 客户端streamable-httpPOST/GET/DELETE /api/mcp/stream使用mcp-session-id头多会话 HTTP 客户端DELETE结束会话mcpTransport设置决定激活的是sse还是streamable-http切换传输模式会关闭另一传输上的既有会话。从源码看SSE 与 Streamable HTTP 两种模式互斥启动 SSE 单例会关闭全部 streamable 会话ensureSseServer()创建 streamable 会话则先关闭 SSE 单例createStreamableSession()。Streamable HTTP 还实现了 MCP 规范的会话管理语义携带未知mcp-session-id的非初始化请求返回404 Not Found规范要求客户端据此重新初始化若客户端携带过期会话 ID 发来initialize则自动创建新会话完成“失忆恢复”避免服务器重启后手动重启客户端。会话默认空闲 5 分钟即被回收MCP_SESSION_IDLE_MS 5 * 60 * 1000扫描间隔 60 秒。远程访问与 manage 作用域旁路/api/mcp/*属于 LOCAL_ONLY 层级见 docs/security/ROUTE_GUARD_TIERS.md——默认仅回环地址localhost、127.0.0.1、::1可访问。自 v3.8.2 起非回环客户端只要携带Authorization: Bearer api-key且该 Key 带有manage作用域即可连接这也是通过隧道、反向代理或公网主机名访问远程 MCP 服务器的唯一途径# 授予 manage 作用域在仪表盘 API Keys 页面勾选 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。注意相邻的/api/cli-tools/runtime/*前缀故意不可旁路二者不可混淆。核心工具Essential ToolsMCP 服务器以omniroute_为前缀暴露一组网关运维工具全部通过内部 API 转发执行omniRouteFetch()统一注入Authorization与内部服务认证头。下表为 16 个核心工具中的前 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为例其实现open-sse/mcp-server/server.ts 的handleGetHealth()并行拉取/api/monitoring/health、/api/resilience、/api/rate-limits三个内部接口聚合出 uptime、memoryUsage、circuitBreakers、rateLimits、cacheStats、cryptography、adaptiveAdmission含按排队成本排序的前 10 个 lane 租户等字段若某个内部源拉取失败会显式写入degraded数组而不假装数据为零——这正是源码注释所强调的“区分‘无数据’与‘源不可达’”。高级工具Advanced Tools工具说明omniroute_simulate_route路由干跑模拟dry-run输出含 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按任务类型给出任务适配推荐及备选方案omniroute_explain_route解释一次历史路由决策评分因子 fallbackomniroute_get_session_snapshot完整会话状态成本、token、错误、预算守卫这些工具并非空壳omniroute_simulate_route走路由评分管线做 dry-run 并返回 fallback 树omniroute_test_combo会对 combo 内每个 Provider 发起真实调用并逐项报告延迟/成本/成败omniroute_set_budget_guard与会话预算系统联动omniroute_set_resilience_profile直接调整熔断、重试、超时与 fallback 深度对应handleSetResilienceProfile的“circuit breakers, retries, timeouts, fallback depth”描述。从 16 到 110当前仓库的完整工具全景德文镜像文档发布于 16 工具版本当前仓库已演进为110 个唯一工具由 open-sse/mcp-server/toolCount.ts 的countUniqueMcpTools()统计45 个规范定义含 6 个 CCR 生命周期工具、3 个 Agent 技能工具、omniroute_radar_catalog、omniroute_x_search、omniroute_tool_search等叠加 memory3、skills4、GitHub skills3、pool6、gamification8、plugins8、Notion6、Obsidian22、local corpus3与 2 个仅 RTK 的压缩工具以及动态注册的skill_*工具server.ts 中按skill_name规则从技能表动态注册已启用技能。扩展工具族概览缓存2omniroute_cache_stats/omniroute_cache_flush覆盖语义缓存、prompt-cache 与幂等层统计支持按 signature/model 定向清除。压缩13omniroute_compression_status、omniroute_compression_configure、omniroute_set_compression_engineoff/caveman/rtk/stacked、omniroute_list_compression_combos、omniroute_compression_combo_stats以及 6 个 CCR 内存块工具omniroute_ccr_*和 2 个 RTK 学习工具。CCR 块仅存内存、重启即失单块上限 2 MiB、单主体 16 MiB、全局 64 MiB默认 24 小时 TTL最长 7 天且按认证 API Key 主体隔离存取。1Proxy3omniroute_oneproxy_fetch/rotate/stats代理市场拉取与按random/quality/sequential策略轮换。内存3omniroute_memory_search/add/clear记忆按factual/episodic/procedural/semantic类型管理带 token 预算约束定义于 open-sse/mcp-server/tools/memoryTools.ts。技能4omniroute_skills_list/enable/execute/executions由 src/lib/skills/registry.ts 与 src/lib/skills/executor.ts 支撑。上下文源Notion6 个notion_*工具、Obsidian13 读 9 写、本地语料3 个local_corpus_*分别定义于 open-sse/mcp-server/tools/notionTools.ts、open-sse/mcp-server/tools/obsidianTools.ts、open-sse/mcp-server/tools/localCorpusTools.ts。搜索omniroute_web_search非 X/Twitter 的 Web 搜索多 Provider 自动故障转移、omniroute_x_search经 xAI/SuperGrok 或xquik-search搜索 X、omniroute_web_fetchFirecrawl/Jina Reader/Tavily 等抓取网关支持 markdown/html/links/screenshot。Radar / 工具发现omniroute_radar_catalog本地签名 Radar 目录与omniroute_tool_search从已注册 MCP 目录中发现工具。Notion 集成令牌既可在 Endpoint 仪表盘的Context Sources标签页配置也可走 REST API# 设置令牌 curl -X POST http://localhost:20128/api/settings/notion \ -H Content-Type: application/json \ -d {token: ntn_...} # 查看状态 curl http://localhost:20128/api/settings/notion # 断开连接 curl -X DELETE http://localhost:20128/api/settings/notion认证与作用域Authentication ScopesMCP 工具通过 API Key 作用域认证集中式校验实现在 open-sse/mcp-server/scopeEnforcement.ts。每个工具要求特定 scopeScope工具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上表为德文镜像文档所列的精简作用域矩阵当前仓库的完整映射已扩展至 30 作用域例如execute:completionsroute_request、test_combo、execute:searchweb_search、x_search、web_fetch、write:budget、write:resilience、read/write:cache、read/write:compression、read:radar、read:tools、read:gamification、read/write:plugins、read:local-corpus等完整清单见 docs/frameworks/MCP-SERVER.md。关键机制源码级通配符作用域read:*授予全部读作用域*授予全部权限。匹配逻辑见scopeMatches()——grantedScope为*或精确等于所需 scope 即通过以*结尾的作用域按前缀匹配。强制开关OMNIROUTE_MCP_ENFORCE_SCOPEStrue才启用强制校验默认关闭启用后缺失作用域的调用被拒绝并在审计日志中记录scope_denied:reason及缺失列表见 scopeEnforcement.ts 的evaluateToolScopes()与 server.ts 的withScopeEnforcement()包装器。调用者作用域解析优先级authInfoHTTP 下按 Bearer Key 的api_keys.scopes解析→_metameta.scopes / meta.auth.scopes / meta.omniroute.scopes→OMNIROUTE_MCP_SCOPES环境变量回退 → 空集source 标记为none。窄化远程连接#7895src/shared/constants/managementScopes.ts导出mcp:connect一个只授权/api/mcp/旁路、不授予任何其他管理路由权限的增量窄作用域它刻意排除在MANAGEMENT_API_KEY_SCOPES之外是manage/admin之外的“仅 MCP 远程调用”低权限替代经hasMcpConnectOrManageScope()校验。审计日志每一次工具调用都会写入 SQLite 的mcp_tool_audit表实现在 open-sse/mcp-server/audit.ts记录工具名、参数、结果耗时毫秒、成功/失败标记、错误信息如适用API Key 哈希、时间戳作用域拒绝记录为scope_denied:reason附缺失作用域列表出于安全考虑输入参数经 SHA-256 哈希存储而非明文输出仅保留截断摘要hashInput/summarizeOutput见 open-sse/mcp-server/schemas/audit.ts。审计数据库驱动做了双路径设计优先better-sqlite3原生绑定绑定缺失时如某些全局安装/Docker 场景自动回退到 Node 22.5 内置的node:sqlite审计写失败绝不阻断工具执行。仪表盘或/api/mcp/audit、/api/mcp/audit/stats两个 REST 端点可检索近期调用记录支持limit、offset、tool、success、apiKeyId过滤。生产级运行机制描述压缩Description CompressionMCP 的工具/提示/资源注册表在注册与列举时压缩描述文本以降低暴露给客户端的元数据体量进而降低提示词上下文成本。实现见 open-sse/mcp-server/descriptionCompressor.ts通过createMcpServer()内的compressMcpRegistryMetadata接入使用 Caveman 规则集getRulesForContext(all, full)并提取代码跨度、围栏块等保真块不破坏结构内容。按部署切换key_value表中的compression.mcpDescriptionCompressionEnabled默认开启仪表盘对应Analytics → MCP description compression。进程级切换OMNIROUTE_MCP_COMPRESS_DESCRIPTIONSfalse或OMNIROUTE_MCP_DESCRIPTION_COMPRESSIONfalse。实时统计经omniroute_compression_status的analytics.mcpDescriptionCompression暴露标记source: mcp_metadata_estimate与真实 Provider 用量凭证区分。MCP 可访问性树过滤v3.8.0与压缩工具不同这是一个透明的后执行过滤器作用于 MCP 浏览器/可访问性工具的返回结果非独立工具任何包含冗长可访问性树或浏览器快照文本≥2000 字符的工具结果都会经过它处理。关键行为将 ≥30 行连续重复兄弟行折叠为首部 尾部摘要保留 Playwright/computer-use 必需的[refeXX]锚点对超过 50,000 字符的超大文本硬截断并附加导航提示预期对浏览器快照负载节省60–80%。配置项为全局设置中的compression.mcpAccessibilitymigration 056实现在 open-sse/services/compression/engines/mcpAccessibility/ 目录完整文档见 docs/compression/COMPRESSION_ENGINES.md。工具基数削减Tool Cardinality ReductionF4.3描述压缩缩小单个工具的元数据工具基数削减进一步减少“宣布多少个工具”——在tools/list清单中少宣布工具直接降低客户端模型为工具目录支付的每请求 token 成本“layer 5”压缩。实现为 open-sse/mcp-server/toolCardinality.ts 的纯函数reduceToolManifest接入 server.ts 注册循环。默认关闭、显式开启只有设置两个环境变量之一才生效否则 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被剔除工具的注册仍成功随后对 MCP SDK 句柄调用.disable()因此既不出现在tools/list中、又保持注册接线完整干净的 enable/disable无需重注册。readMcpToolProfileFromEnv()在两者均为空时返回null不过滤。estimateManifestTokens()可用于对比削减前后的清单 token 成本ToolProfile还预留了作用域交集过滤allowScopes支持read:*通配与确定性maxTools上限但这两者需要完整清单在注册期参与目前未通过环境变量暴露。运行时心跳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 }isMcpHeartbeatOnline()还实现了陈旧判定默认超过 3 个心跳周期视为离线与可选的 PID 存活校验。环境变量速查变量默认值作用OMNIROUTE_BASE_URLhttp://localhost:20128MCP 调用 OmniRoute 内部 API 的基础地址OMNIROUTE_API_KEY空转发为内部 API 调用的Authorization: Bearer静态回退被按调用者的 MCP 身份头覆盖OMNIROUTE_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内部管理读取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超时预算在 open-sse/mcp-server/fetchTimeout.ts 中按“management / upstream”两类信号区分route_request这类等上游 Provider 的跳转绝不继承管理读取的 10 秒预算见 server.ts 中 #9717 的注释说明。REST API 端点除 MCP 协议本身外还暴露一组管理端点端点方法说明认证/api/mcp/statusGET服务器状态心跳、HTTP 传输状态、审计活动摘要Managementsession/admin/api/mcp/toolsGET工具目录名称、描述、作用域、阶段、源端点Management/api/mcp/sseGET/POSTSSE 传输端点受mcpEnabledmcpTransport sse门控API Key 作用域/api/mcp/streamPOST/GET/DELETEStreamable HTTP 传输mcp-session-id头DELETE结束会话API Key 作用域/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。文件索引文件作用open-sse/mcp-server/server.tsMCP 服务器工厂、stdio 入口、作用域化工具注册110 工具open-sse/mcp-server/httpTransport.tsSSE Streamable HTTP 传输会话管理open-sse/mcp-server/scopeEnforcement.ts工具作用域求值与调用者解析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工具清单基数削减reduceToolManifestopen-sse/mcp-server/schemas/tools.tsZod 模式 工具注册表MCP_TOOLSopen-sse/mcp-server/tools/advancedTools.tsPhase 2 缓存 1proxy 工具处理器open-sse/mcp-server/tools/compressionTools.ts压缩工具处理器open-sse/mcp-server/tools/memoryTools.ts内存工具定义3open-sse/mcp-server/tools/skillTools.ts技能工具定义4open-sse/mcp-server/tools/notionTools.tsNotion 上下文源工具6src/app/api/mcp//api/mcp/*REST 路由status/tools/sse/stream/audit/audit/statssrc/lib/notion/api.tsNotion REST 客户端重试、超时、错误分类src/lib/db/notion.tsNotion 令牌持久化key_value表tests/unit/notion-api.test.tsNotion API 客户端测试tests/unit/notion-tools.test.tsNotion 工具作用域强制测试相关框架与排错提示MCP 工具清单刻意限定在运行时路由/缓存/压缩/内存/技能/代理/上下文源操作范围内。两个相邻框架随 v3.8.0 一并发布但不属于 MCP 工具目录Cloud Agentscodex-cloud、cursor-cloud、devin、jules进程外 AI 编码代理经独立 REST 面/api/v1/agents/*暴露调用不消耗 MCP 作用域。实现见 src/lib/cloudAgent/文档见 docs/frameworks/CLOUD_AGENT.md。Guardrailsvision-bridge、pii-masker、prompt-injection聊天管线内的前后置过滤器运行于 MCP 工具/路由层之前违规以结构化形式进入审计管线不作为 MCP 工具被调用。文档见 docs/security/GUARDRAILS.md。调试被“阻止”的 MCP 调用时请同时检查 MCP 审计日志scope_denied:*条目与 Guardrails 审计轨迹——请求可能先被 Guardrail 拒绝根本未到达 MCP 作用域强制层。关于 IDE 集成Claude Desktop、Cursor、Cline 及兼容 MCP 客户端的详细配置见 docs/guides/SETUP_GUIDE.md 的 “MCP Client Configuration” 小节OpenCode 场景另见 docs/frameworks/OPENCODE.md。压缩模型与 RTK 的运行时原理分别见 docs/compression/COMPRESSION_ENGINES.md 与 docs/compression/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），仅供参考 OmniRoute MCP Server 深度指南：从启动到 110 个智能工具的模型上下文协议网关
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/OmniRoute本文是 OmniRoute 内置 Model Context ProtocolMCP服务器的技术实战指南。OmniRoute 在发行包中内置了一个完整的 MCP 服务器允许 Claude Desktop、Cursor、Cline、OpenCode 等 MCP 客户端通过统一网关操作路由、组合combo、配额、压缩、内存、技能、代理池与上下文源等能力。读完本文你将掌握omniroute --mcp的启动方式、stdio / SSE / Streamable HTTP 三种传输层的选型、核心与高级工具的调用语义、API Key 作用域scope认证模型以及描述压缩、工具基数削减与审计日志等生产级运行机制。英文原版权威文档见 docs/frameworks/MCP-SERVER.md本文以该文档及其德文镜像 docs/i18n/de/docs/frameworks/MCP-SERVER.md为骨架结合仓库源码展开。安装与启动OmniRoute MCP 服务器是内置能力无需单独安装。启动方式有两种# 方式一独立 stdio 进程IDE 集成首选 omniroute --mcp# 方式二通过 open-sse 传输层HTTP # MCP 会自动挂载在 /mcp 端点默认端口 20130 omniroute --dev方式二下 MCP 服务器运行在 Next.js 进程内部对应源码 open-sse/mcp-server/httpTransport.ts 中“Runs the MCP server inside the Next.js process”的设计因此可以不经--mcp独立进程、直接通过仪表盘开关来启用/停用。需要说明的是--dev形态下 MCP 实际上挂载于/api/mcp/sse与/api/mcp/stream两个 HTTP 路由源码路径 src/app/api/mcp/sse/route.ts 与 src/app/api/mcp/stream/route.ts仪表盘“Settings → MCP”中的mcpEnabled开关与mcpTransport选择控制其启停与传输模式未启用或传输模式不匹配时路由返回 HTTP 400 并提示切换设置。三种传输层stdio、SSE 与 Streamable HTTP所有传输层共享同一个createMcpServer()工厂open-sse/mcp-server/server.ts因此工具集、作用域与审计行为完全一致差异只在传输通道传输层位置适用场景stdioopen-sse/mcp-server/server.ts 中的startMcpStdio()Claude Desktop、Cursor 等本地 IDE 集成进程生命周期由客户端拉起sseGET/POST /api/mcp/sse经httpTransport需要事件流的浏览器/Agent 客户端streamable-httpPOST/GET/DELETE /api/mcp/stream使用mcp-session-id头多会话 HTTP 客户端DELETE结束会话mcpTransport设置决定激活的是sse还是streamable-http切换传输模式会关闭另一传输上的既有会话。从源码看SSE 与 Streamable HTTP 两种模式互斥启动 SSE 单例会关闭全部 streamable 会话ensureSseServer()创建 streamable 会话则先关闭 SSE 单例createStreamableSession()。Streamable HTTP 还实现了 MCP 规范的会话管理语义携带未知mcp-session-id的非初始化请求返回404 Not Found规范要求客户端据此重新初始化若客户端携带过期会话 ID 发来initialize则自动创建新会话完成“失忆恢复”避免服务器重启后手动重启客户端。会话默认空闲 5 分钟即被回收MCP_SESSION_IDLE_MS 5 * 60 * 1000扫描间隔 60 秒。远程访问与 manage 作用域旁路/api/mcp/*属于 LOCAL_ONLY 层级见 docs/security/ROUTE_GUARD_TIERS.md——默认仅回环地址localhost、127.0.0.1、::1可访问。自 v3.8.2 起非回环客户端只要携带Authorization: Bearer api-key且该 Key 带有manage作用域即可连接这也是通过隧道、反向代理或公网主机名访问远程 MCP 服务器的唯一途径# 授予 manage 作用域在仪表盘 API Keys 页面勾选 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。注意相邻的/api/cli-tools/runtime/*前缀故意不可旁路二者不可混淆。核心工具Essential ToolsMCP 服务器以omniroute_为前缀暴露一组网关运维工具全部通过内部 API 转发执行omniRouteFetch()统一注入Authorization与内部服务认证头。下表为 16 个核心工具中的前 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为例其实现open-sse/mcp-server/server.ts 的handleGetHealth()并行拉取/api/monitoring/health、/api/resilience、/api/rate-limits三个内部接口聚合出 uptime、memoryUsage、circuitBreakers、rateLimits、cacheStats、cryptography、adaptiveAdmission含按排队成本排序的前 10 个 lane 租户等字段若某个内部源拉取失败会显式写入degraded数组而不假装数据为零——这正是源码注释所强调的“区分‘无数据’与‘源不可达’”。高级工具Advanced Tools工具说明omniroute_simulate_route路由干跑模拟dry-run输出含 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按任务类型给出任务适配推荐及备选方案omniroute_explain_route解释一次历史路由决策评分因子 fallbackomniroute_get_session_snapshot完整会话状态成本、token、错误、预算守卫这些工具并非空壳omniroute_simulate_route走路由评分管线做 dry-run 并返回 fallback 树omniroute_test_combo会对 combo 内每个 Provider 发起真实调用并逐项报告延迟/成本/成败omniroute_set_budget_guard与会话预算系统联动omniroute_set_resilience_profile直接调整熔断、重试、超时与 fallback 深度对应handleSetResilienceProfile的“circuit breakers, retries, timeouts, fallback depth”描述。从 16 到 110当前仓库的完整工具全景德文镜像文档发布于 16 工具版本当前仓库已演进为110 个唯一工具由 open-sse/mcp-server/toolCount.ts 的countUniqueMcpTools()统计45 个规范定义含 6 个 CCR 生命周期工具、3 个 Agent 技能工具、omniroute_radar_catalog、omniroute_x_search、omniroute_tool_search等叠加 memory3、skills4、GitHub skills3、pool6、gamification8、plugins8、Notion6、Obsidian22、local corpus3与 2 个仅 RTK 的压缩工具以及动态注册的skill_*工具server.ts 中按skill_name规则从技能表动态注册已启用技能。扩展工具族概览缓存2omniroute_cache_stats/omniroute_cache_flush覆盖语义缓存、prompt-cache 与幂等层统计支持按 signature/model 定向清除。压缩13omniroute_compression_status、omniroute_compression_configure、omniroute_set_compression_engineoff/caveman/rtk/stacked、omniroute_list_compression_combos、omniroute_compression_combo_stats以及 6 个 CCR 内存块工具omniroute_ccr_*和 2 个 RTK 学习工具。CCR 块仅存内存、重启即失单块上限 2 MiB、单主体 16 MiB、全局 64 MiB默认 24 小时 TTL最长 7 天且按认证 API Key 主体隔离存取。1Proxy3omniroute_oneproxy_fetch/rotate/stats代理市场拉取与按random/quality/sequential策略轮换。内存3omniroute_memory_search/add/clear记忆按factual/episodic/procedural/semantic类型管理带 token 预算约束定义于 open-sse/mcp-server/tools/memoryTools.ts。技能4omniroute_skills_list/enable/execute/executions由 src/lib/skills/registry.ts 与 src/lib/skills/executor.ts 支撑。上下文源Notion6 个notion_*工具、Obsidian13 读 9 写、本地语料3 个local_corpus_*分别定义于 open-sse/mcp-server/tools/notionTools.ts、open-sse/mcp-server/tools/obsidianTools.ts、open-sse/mcp-server/tools/localCorpusTools.ts。搜索omniroute_web_search非 X/Twitter 的 Web 搜索多 Provider 自动故障转移、omniroute_x_search经 xAI/SuperGrok 或xquik-search搜索 X、omniroute_web_fetchFirecrawl/Jina Reader/Tavily 等抓取网关支持 markdown/html/links/screenshot。Radar / 工具发现omniroute_radar_catalog本地签名 Radar 目录与omniroute_tool_search从已注册 MCP 目录中发现工具。Notion 集成令牌既可在 Endpoint 仪表盘的Context Sources标签页配置也可走 REST API# 设置令牌 curl -X POST http://localhost:20128/api/settings/notion \ -H Content-Type: application/json \ -d {token: ntn_...} # 查看状态 curl http://localhost:20128/api/settings/notion # 断开连接 curl -X DELETE http://localhost:20128/api/settings/notion认证与作用域Authentication ScopesMCP 工具通过 API Key 作用域认证集中式校验实现在 open-sse/mcp-server/scopeEnforcement.ts。每个工具要求特定 scopeScope工具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上表为德文镜像文档所列的精简作用域矩阵当前仓库的完整映射已扩展至 30 作用域例如execute:completionsroute_request、test_combo、execute:searchweb_search、x_search、web_fetch、write:budget、write:resilience、read/write:cache、read/write:compression、read:radar、read:tools、read:gamification、read/write:plugins、read:local-corpus等完整清单见 docs/frameworks/MCP-SERVER.md。关键机制源码级通配符作用域read:*授予全部读作用域*授予全部权限。匹配逻辑见scopeMatches()——grantedScope为*或精确等于所需 scope 即通过以*结尾的作用域按前缀匹配。强制开关OMNIROUTE_MCP_ENFORCE_SCOPEStrue才启用强制校验默认关闭启用后缺失作用域的调用被拒绝并在审计日志中记录scope_denied:reason及缺失列表见 scopeEnforcement.ts 的evaluateToolScopes()与 server.ts 的withScopeEnforcement()包装器。调用者作用域解析优先级authInfoHTTP 下按 Bearer Key 的api_keys.scopes解析→_metameta.scopes / meta.auth.scopes / meta.omniroute.scopes→OMNIROUTE_MCP_SCOPES环境变量回退 → 空集source 标记为none。窄化远程连接#7895src/shared/constants/managementScopes.ts导出mcp:connect一个只授权/api/mcp/旁路、不授予任何其他管理路由权限的增量窄作用域它刻意排除在MANAGEMENT_API_KEY_SCOPES之外是manage/admin之外的“仅 MCP 远程调用”低权限替代经hasMcpConnectOrManageScope()校验。审计日志每一次工具调用都会写入 SQLite 的mcp_tool_audit表实现在 open-sse/mcp-server/audit.ts记录工具名、参数、结果耗时毫秒、成功/失败标记、错误信息如适用API Key 哈希、时间戳作用域拒绝记录为scope_denied:reason附缺失作用域列表出于安全考虑输入参数经 SHA-256 哈希存储而非明文输出仅保留截断摘要hashInput/summarizeOutput见 open-sse/mcp-server/schemas/audit.ts。审计数据库驱动做了双路径设计优先better-sqlite3原生绑定绑定缺失时如某些全局安装/Docker 场景自动回退到 Node 22.5 内置的node:sqlite审计写失败绝不阻断工具执行。仪表盘或/api/mcp/audit、/api/mcp/audit/stats两个 REST 端点可检索近期调用记录支持limit、offset、tool、success、apiKeyId过滤。生产级运行机制描述压缩Description CompressionMCP 的工具/提示/资源注册表在注册与列举时压缩描述文本以降低暴露给客户端的元数据体量进而降低提示词上下文成本。实现见 open-sse/mcp-server/descriptionCompressor.ts通过createMcpServer()内的compressMcpRegistryMetadata接入使用 Caveman 规则集getRulesForContext(all, full)并提取代码跨度、围栏块等保真块不破坏结构内容。按部署切换key_value表中的compression.mcpDescriptionCompressionEnabled默认开启仪表盘对应Analytics → MCP description compression。进程级切换OMNIROUTE_MCP_COMPRESS_DESCRIPTIONSfalse或OMNIROUTE_MCP_DESCRIPTION_COMPRESSIONfalse。实时统计经omniroute_compression_status的analytics.mcpDescriptionCompression暴露标记source: mcp_metadata_estimate与真实 Provider 用量凭证区分。MCP 可访问性树过滤v3.8.0与压缩工具不同这是一个透明的后执行过滤器作用于 MCP 浏览器/可访问性工具的返回结果非独立工具任何包含冗长可访问性树或浏览器快照文本≥2000 字符的工具结果都会经过它处理。关键行为将 ≥30 行连续重复兄弟行折叠为首部 尾部摘要保留 Playwright/computer-use 必需的[refeXX]锚点对超过 50,000 字符的超大文本硬截断并附加导航提示预期对浏览器快照负载节省60–80%。配置项为全局设置中的compression.mcpAccessibilitymigration 056实现在 open-sse/services/compression/engines/mcpAccessibility/ 目录完整文档见 docs/compression/COMPRESSION_ENGINES.md。工具基数削减Tool Cardinality ReductionF4.3描述压缩缩小单个工具的元数据工具基数削减进一步减少“宣布多少个工具”——在tools/list清单中少宣布工具直接降低客户端模型为工具目录支付的每请求 token 成本“layer 5”压缩。实现为 open-sse/mcp-server/toolCardinality.ts 的纯函数reduceToolManifest接入 server.ts 注册循环。默认关闭、显式开启只有设置两个环境变量之一才生效否则 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被剔除工具的注册仍成功随后对 MCP SDK 句柄调用.disable()因此既不出现在tools/list中、又保持注册接线完整干净的 enable/disable无需重注册。readMcpToolProfileFromEnv()在两者均为空时返回null不过滤。estimateManifestTokens()可用于对比削减前后的清单 token 成本ToolProfile还预留了作用域交集过滤allowScopes支持read:*通配与确定性maxTools上限但这两者需要完整清单在注册期参与目前未通过环境变量暴露。运行时心跳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 }isMcpHeartbeatOnline()还实现了陈旧判定默认超过 3 个心跳周期视为离线与可选的 PID 存活校验。环境变量速查变量默认值作用OMNIROUTE_BASE_URLhttp://localhost:20128MCP 调用 OmniRoute 内部 API 的基础地址OMNIROUTE_API_KEY空转发为内部 API 调用的Authorization: Bearer静态回退被按调用者的 MCP 身份头覆盖OMNIROUTE_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内部管理读取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超时预算在 open-sse/mcp-server/fetchTimeout.ts 中按“management / upstream”两类信号区分route_request这类等上游 Provider 的跳转绝不继承管理读取的 10 秒预算见 server.ts 中 #9717 的注释说明。REST API 端点除 MCP 协议本身外还暴露一组管理端点端点方法说明认证/api/mcp/statusGET服务器状态心跳、HTTP 传输状态、审计活动摘要Managementsession/admin/api/mcp/toolsGET工具目录名称、描述、作用域、阶段、源端点Management/api/mcp/sseGET/POSTSSE 传输端点受mcpEnabledmcpTransport sse门控API Key 作用域/api/mcp/streamPOST/GET/DELETEStreamable HTTP 传输mcp-session-id头DELETE结束会话API Key 作用域/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。文件索引文件作用open-sse/mcp-server/server.tsMCP 服务器工厂、stdio 入口、作用域化工具注册110 工具open-sse/mcp-server/httpTransport.tsSSE Streamable HTTP 传输会话管理open-sse/mcp-server/scopeEnforcement.ts工具作用域求值与调用者解析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工具清单基数削减reduceToolManifestopen-sse/mcp-server/schemas/tools.tsZod 模式 工具注册表MCP_TOOLSopen-sse/mcp-server/tools/advancedTools.tsPhase 2 缓存 1proxy 工具处理器open-sse/mcp-server/tools/compressionTools.ts压缩工具处理器open-sse/mcp-server/tools/memoryTools.ts内存工具定义3open-sse/mcp-server/tools/skillTools.ts技能工具定义4open-sse/mcp-server/tools/notionTools.tsNotion 上下文源工具6src/app/api/mcp//api/mcp/*REST 路由status/tools/sse/stream/audit/audit/statssrc/lib/notion/api.tsNotion REST 客户端重试、超时、错误分类src/lib/db/notion.tsNotion 令牌持久化key_value表tests/unit/notion-api.test.tsNotion API 客户端测试tests/unit/notion-tools.test.tsNotion 工具作用域强制测试相关框架与排错提示MCP 工具清单刻意限定在运行时路由/缓存/压缩/内存/技能/代理/上下文源操作范围内。两个相邻框架随 v3.8.0 一并发布但不属于 MCP 工具目录Cloud Agentscodex-cloud、cursor-cloud、devin、jules进程外 AI 编码代理经独立 REST 面/api/v1/agents/*暴露调用不消耗 MCP 作用域。实现见 src/lib/cloudAgent/文档见 docs/frameworks/CLOUD_AGENT.md。Guardrailsvision-bridge、pii-masker、prompt-injection聊天管线内的前后置过滤器运行于 MCP 工具/路由层之前违规以结构化形式进入审计管线不作为 MCP 工具被调用。文档见 docs/security/GUARDRAILS.md。调试被“阻止”的 MCP 调用时请同时检查 MCP 审计日志scope_denied:*条目与 Guardrails 审计轨迹——请求可能先被 Guardrail 拒绝根本未到达 MCP 作用域强制层。关于 IDE 集成Claude Desktop、Cursor、Cline 及兼容 MCP 客户端的详细配置见 docs/guides/SETUP_GUIDE.md 的 “MCP Client Configuration” 小节OpenCode 场景另见 docs/frameworks/OPENCODE.md。压缩模型与 RTK 的运行时原理分别见 docs/compression/COMPRESSION_ENGINES.md 与 docs/compression/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），仅供参考