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 仓库的官方文档docs/frameworks/MCP-SERVER.md及其多语言版本系统讲解内建 MCPModel Context Protocol服务器的启动方式、三种传输协议、110 个工具的作用域划分、描述压缩与工具基数削减、心跳与审计日志等运行时机制。读完后你将能够把 OmniRoute 接入 Claude Desktop、Cursor 等 MCP 客户端通过 scope 化的 API Key 安全授权工具调用并用MCP_TOOL_DENY/MCP_TOOL_ALLOW等手段控制工具目录的 token 开销。安装与启动方式OmniRoute 的 MCP Server 是内建功能无需额外安装依赖。文档给出了两种启动路径omniroute --mcp或者通过 open-sse 传输在开发模式下自动挂载# HTTP streamable transport omniroute --dev # MCP 会在 /mcp 端点自动启动从源码结构看两种启动方式背后是同一个工厂函数createMcpServer()定义在 server.ts 中。stdio 入口直接调用该工厂并连接进程标准输入输出而 HTTP 形态则由 httpTransport.ts 在 Next.js 进程内运行因此可以从 dashboard 动态开关不必依赖omniroute --mcp独立进程。文件头注释明确说明了这一设计意图Runs the MCP server inside the Next.js process so it can be toggled from the dashboard。工具总数并非硬编码server.ts 在模块加载时调用countUniqueMcpTools()将MCP_TOOLS、memory、skills、agentSkills、githubSkills、pool、gamification、plugins、Notion、Obsidian、localCorpus、compression 等各工具集合的name并入Set去重计数得到文档所述的 110 个唯一工具。去重逻辑位于 toolCount.ts——因为部分工具如 agent-skills 三件套会同时出现在数组集合与 record 集合中简单求和会重复计数。三种传输协议MCP Server 暴露三种传输全部由同一个createMcpServer()工厂支撑传输方式位置适用场景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 传输sse或streamable-http由mcpTransport设置项决定切换传输会关闭另一传输上的既有会话。httpTransport.ts 中的实现印证了这一点Streamable HTTP 会话以Mapstring, StreamableSession管理每个会话持有独立的McpServer与WebStandardStreamableHTTPServerTransport实例空闲超过MCP_SESSION_IDLE_MS5 分钟的会话由每 60 秒运行一次的清扫定时器回收。对应的 Next.js 路由实际存在于 src/app/api/mcp/ 目录下包含sse/、stream/、status/、tools/、audit/、audit/stats/六组route.ts。两种 HTTP 传输都受mcpEnabled设置门控——未启用或未选择对应传输时路由返回 400 并附带切换设置的提示。远程访问LOCAL_ONLY 与 manage scope 旁路/api/mcp/*被划入 LOCAL_ONLY 安全层级。在 routeGuard.ts 中/api/mcp/是LOCAL_ONLY_API_PREFIXES的第一个条目——默认仅回环地址localhost、127.0.0.1、::1可以访问非回环请求返回403 LOCAL_ONLY。自 v3.8.2 起routeGuard.ts 将/api/mcp/列入LOCAL_ONLY_MANAGE_SCOPE_BYPASS_PREFIXES携带manage作用域 Bearer API Key 的非回环客户端可以接入。这是通过隧道、反向代理或公网域名访问远程 MCP Server 的唯一路径。操作方式为在 dashboard 的 API Keys 页面为某个 key 打开 Management Access或创建时传入scopes: [manage]。文档给出了完整的远程初始化请求示例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/*被刻意设计为不可旁路。此外mcp:connect是一个更窄的远程接入作用域#7895。managementScopes.ts 导出MCP_CONNECT_SCOPE mcp:connect它只授权management.ts策略中的/api/mcp/旁路不授予任何其他管理路由权限且被刻意排除在MANAGEMENT_API_KEY_SCOPES之外。持有manage/admin的 key 依旧通过旁路检查mcp:connect则是仅远程 MCP 调用这类低权限场景的替代方案经由hasMcpConnectOrManageScope()校验。在作用域解析层面HTTP/SSE 传输下 httpTransport.ts 通过resolveMcpCallerAuthInfo()定义于 httpAuthContext.ts解析调用方真实的api_keys.scopes并注入 MCP SDK 的transport.handleRequest(req, { authInfo })使每次工具调用中的extra.authInfo.scopes反映 Bearer key 自身的作用域。scopeEnforcement.ts 的resolveCallerScopeContext()按authInfo_metaOMNIROUTE_MCP_SCOPES环境变量三级优先级取用——HTTP 路径现在补上了此前缺失的第一优先级来源。stdio 无逐调用方身份见mcpCallerIdentity.ts继续沿用_meta/env 回退链不受影响。核心工具清单Phase 114 个工具作用域说明omniroute_get_healthread:health运行时长、内存、熔断器、限流、缓存统计omniroute_list_combosread:combos全部已配置 combo 及其策略可选带指标omniroute_get_combo_metricsread:combos指定 combo 的性能指标omniroute_switch_combowrite:combos激活或停用 comboomniroute_create_combowrite:combos经既有 combo API 创建经过校验的 comboomniroute_check_quotaread:quota配额已用/总量、剩余百分比、重置时间、token 健康度omniroute_route_requestexecute:completions经 OmniRoute 路由发送聊天补全omniroute_cost_reportread:usage按周期session/day/week/month的成本报告omniroute_list_models_catalogread:models完整模型目录能力、状态、定价omniroute_radar_catalogread:radar本地签名 Radar 目录支持 provider/family 过滤omniroute_tool_searchread:tools从已注册 MCP 目录中发现工具omniroute_web_searchexecute:search经已配置搜索 provider 做网络搜索非 X/Twitteromniroute_x_searchexecute:search经 xAI/SuperGrok 搜索 X或选xquik-search走 Xquik API需所选后端的凭据omniroute_web_fetchexecute:search经已配置 fetch provider 抓取网页内容高级工具Phase 211 个工具作用域说明omniroute_simulate_routeread:health,read:combos带回退树的 dry-run 路由模拟omniroute_set_budget_guardwrite:budget会话预算degrade/block/alert 动作omniroute_set_routing_strategywrite:combos运行时更新 combo 策略priority/weighted/auto 等omniroute_set_resilience_profilewrite:resilience应用aggressive/balanced/conservative弹性预设omniroute_test_comboexecute:completions,read:combos用真实上游请求实测 combo 内每个 provideromniroute_get_provider_metricsread:health单 provider 指标含 p50/p95/p99 延迟与熔断器状态omniroute_best_combo_for_taskread:combos,read:health按任务类型给出带预算/延迟约束的 combo 推荐omniroute_explain_routeread:health,read:usage解释请求为何被路由到某 provider评分因子 回退omniroute_get_session_snapshotread:usage完整会话快照成本、token、top 模型/Provider、错误、预算守卫omniroute_db_health_checkread:health,write:resilience诊断可选自动修复数据库漂移如损坏的 combo 引用、孤儿行omniroute_sync_pricingpricing:write从外部源LiteLLM同步定价数据支持dryRun缓存、压缩与其他领域工具缓存工具2 个omniroute_cache_statsread:cache语义缓存/prompt-cache/幂等统计与omniroute_cache_flushwrite:cache全局或按签名/模型刷新。压缩工具13 个处理函数位于 compressionTools.ts工具作用域说明omniroute_compression_statusread:compression压缩设置、分析摘要、缓存感知统计含analytics.mcpDescriptionCompression元数据omniroute_compression_configurewrite:compression配置压缩模式、阈值、目标比例、system-prompt 保留、MCP 描述压缩开关omniroute_set_compression_enginewrite:compression选择活动引擎off/caveman/rtk/stacked与 Caveman/RTK 强度omniroute_list_compression_combosread:compression列出命名压缩组合及其引擎管线omniroute_compression_combo_statsread:compression按压缩组合与引擎分组的分析数据omniroute_ccr_storewrite:compression存储调用方隔离的内容到内存 CCR 存储返回 marker 与ccr://引用omniroute_ccr_retrieveread:compression全量或以 head/tail/lines/grep/stats 模式取回 CCR 内容omniroute_ccr_inspectread:compression查看调用方 CCR 元数据不返回内容omniroute_ccr_listread:compression分页列出调用方 CCR 块元数据omniroute_ccr_deletewrite:compression删除调用方 CCR 块omniroute_ccr_statsread:compression报告调用方维度的内存占用、生命周期计数与存储上限omniroute_rtk_discoverread:compression在自选 RTK 输出样本中发现重复噪声omniroute_rtk_learnread:compression从自选样本生成可审查的 RTK 过滤草案CCRContent Cache/Reference条目仅存在于内存重启即消失且限额明确单块 2 MiB、每 principal 16 MiB、全局 64 MiB默认 TTL 24 小时上限 7 天。MCP 全量取回限制为 256 KiB更大块需走 ranged/grep 模式。存储、取回、列举、检查、删除、统计均按已认证的 API-key principal 隔离审计记录只含哈希与大小元数据绝不包含内容本身。omniroute_compression_status会在analytics.mcpDescriptionCompression下单独报告 MCP 描述压缩——这些是针对 MCP 可列举描述tools、prompts、resources、resourceTemplates的元数据尺寸估算而非 provider 用量凭证因此标记source: mcp_metadata_estimate以示区分。MCP 无障碍树过滤器v3.8.0与上述压缩工具不同这是一个执行后的透明过滤器用于压缩 MCP 浏览器/无障碍工具返回给 Agent 的工具结果本身不是工具——对任何包含冗长无障碍树或浏览器快照文本≥2000 字符的工具结果自动生效。关键行为将 ≥30 行连续重复的兄弟节点折叠为 head tail 摘要保留 Playwright/computer-use 所依赖的[refeXX]锚点超过 50,000 字符的文本硬性截断并附导航提示浏览器快照负载预期节省 60–80%配置位于全局设置compression.mcpAccessibilitymigration 056server.ts 中readMcpAccessibilityConfig()从key_value表读取并用clampMcpAccessibilityConfig约束每个字段保证持久化的越界maxTextChars不会导致过滤逻辑截断整段文本。实现位于open-sse/services/compression/engines/mcpAccessibility/完整文档见 COMPRESSION_ENGINES.md。其余领域工具1Proxy 工具3 个omniroute_oneproxy_fetch/oneproxy_rotate/oneproxy_stats作用域read:proxies从 1proxy 市场拉取免费代理、按策略random/quality/sequential轮换、查看池统计与协议/国家分布。记忆工具3 个定义在 memoryTools.tsomniroute_memory_searchread:memory按查询/类型/API key 检索并施加 token 预算、omniroute_memory_addwrite:memoryfactual/episodic/procedural/semantic四类、omniroute_memory_clearwrite:memory可按类型或olderThan时间戳过滤清除。Skill 工具4 个定义在 skillTools.ts由src/lib/skills/registrysrc/lib/skills/executor支撑omniroute_skills_list、omniroute_skills_enable、omniroute_skills_executeexecute:skills、omniroute_skills_executions。Notion 上下文源6 个定义在 notionTools.ts。Token 存于key_value表src/lib/db/notion.tsREST 客户端在 src/lib/notion/api.ts设置 API 在 src/app/api/settings/notion/route.ts。可从 Endpoint dashboard 的Context Sources选项卡配置或经 REST# 设置 token 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工具为notion_search、notion_get_page、notion_list_block_children、notion_query_database、notion_get_database均read:notion与notion_append_blockswrite:notion每请求最多 100 个块。Agent Skill 目录工具3 个定义在 agentSkillTools.ts由src/lib/agentSkills/catalog支撑作用域read:catalogomniroute_agent_skills_list列出 45 个 agent skills支持category(api|cli) 与area过滤、omniroute_agent_skills_get按规范id获取完整元数据 SKILL.md 内容、omniroute_agent_skills_coverage23 个 API、21 个 CLI 及 1 个 config skill 中已有 SKILL.md 文件数的覆盖率统计。目录全貌见 AGENT-SKILLS.md。此外文档还明确了两条框架边界Cloud Agentscodex-cloud、cursor-cloud、devin、jules经/api/v1/agents/*REST 面暴露实现于src/lib/cloudAgent/不属于 MCP 工具目录调用不消耗 MCP scopeGuardrailsvision-bridge、pii-masker、prompt-injection 等前置/后置过滤器实现在src/lib/guardrails/在触及 MCP 工具/路由层之前运行。因此调试看似被拦截的 MCP 调用时应同时查看 MCP 审计日志中的scope_denied:*条目与 guardrails 审计轨迹——请求可能在到达 MCP scope 强制层之前就被 guardrail 拒绝了。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查询mcp_tool_audit审计日志过滤limit、offset、tool、success、apiKeyIdManagement/api/mcp/audit/statsGET聚合审计统计totalCalls、successRate、avgDurationMs、top 工具Management环境变量一览变量默认值用途OMNIROUTE_BASE_URLhttp://localhost:20128MCP Server 调用 OmniRoute 内部 API 的 Base URLOMNIROUTE_API_KEY空作为Authorization: Bearer转发给内部 API 调用OMNIROUTE_MCP_ENFORCE_SCOPESfalse仅true启用启用后缺失 scope 的工具调用被拒绝并记录scope_denied:reasonOMNIROUTE_MCP_SCOPES空逗号分隔的默认可用 scope 允许列表调用方未自带 scopes 时生效OMNIROUTE_MCP_COMPRESS_DESCRIPTIONS未设置 开设为0/false/off/no时禁用注册时描述压缩OMNIROUTE_MCP_DESCRIPTION_COMPRESSION未设置 开上一项的别名开关OMNIROUTE_MCP_FETCH_TIMEOUT_MS10000内部管理类读取health、resilience、combos、quota、usage的 Abort 预算OMNIROUTE_MCP_UPSTREAM_TIMEOUT_MS60000等待 provider 的跳数route_request、web_search、web_fetchAbort 预算MCP_TOOL_DENY未设置 不过滤逗号分隔、从tools/list中剔除的工具名MCP_TOOL_ALLOW未设置 不过滤逗号分隔的允许列表仅保留列出的工具DATA_DIR~/.omniroute心跳文件写入${DATA_DIR}/runtime/mcp-heartbeat.json前几项在 server.ts 中直接读取OMNIROUTE_BASE_URL经resolveOmniRouteBaseUrl()解析OMNIROUTE_MCP_ENFORCE_SCOPES true才置位MCP_ENFORCE_SCOPESOMNIROUTE_MCP_SCOPES拆分为Set。两个超时值通过mcpFetchTimeoutSignal()fetchTimeout.ts分别约束管理读取默认 10s与上游等待跳数默认 60s。描述压缩与工具基数削减描述压缩降低单个工具的元数据尺寸实现位于 descriptionCompressor.ts通过createMcpServer()内的compressMcpRegistryMetadata挂入注册流程。压缩对描述文本应用 Caveman 规则集getRulesForContext(all, full)并做保留块抽取代码片段、围栏块等结构内容不被改写。三个开关层次部署级key_value设置表中的compression.mcpDescriptionCompressionEnabled默认开启server.ts 的readMcpDescriptionCompressionEnabled()读取该键UI 暴露为Analytics → MCP description compression进程级OMNIROUTE_MCP_COMPRESS_DESCRIPTIONSfalse或OMNIROUTE_MCP_DESCRIPTION_COMPRESSIONfalse实时统计omniroute_compression_status的analytics.mcpDescriptionCompression字段标记source: mcp_metadata_estimate。工具基数削减F4.3更进一步减少tools/list清单中通告的工具数量本身直接削减客户端模型为整个工具目录支付的每请求 token 成本。实现是无状态纯函数reduceToolManifesttoolCardinality.ts挂接在createMcpServer()的注册循环中。该过滤默认关闭、显式选用两个环境变量都不设时110 个工具原样全部通告。deny优先于allow名称逗号分隔、去空格、忽略空项# 从目录中剔除两个工具 MCP_TOOL_DENYomniroute_get_health,omniroute_list_combos omniroute --mcp # 仅通告路由 配额工具allow-list 模式 MCP_TOOL_ALLOWomniroute_route_request,omniroute_check_quota omniroute --mcp被过滤工具移除的方式是注册始终成功随后在 MCP SDK handle 上调用.disable()——工具不出现在tools/list中但接线保持完整干净的启用/禁用无需重新注册。环境解析器readMcpToolProfileFromEnv(process.env)toolCardinality.ts在两变量均为空时返回null不过滤。底层的ToolProfile形状还支持 scope 交集过滤allowScopes支持read:*通配与确定性maxTools上限但这两项需要注册时的完整 manifest目前未通过环境变量暴露tools/list级钩子是已记录的后续工作estimateManifestTokens()可用于对比削减前后的 manifest token 成本。运行时心跳与审计日志stdio 传输每 5 秒把存活状态持久化到${DATA_DIR}/runtime/mcp-heartbeat.json——runtimeHeartbeat.ts 中DEFAULT_INTERVAL_MS 5000且存在约为 3 倍间隔的离线判定阈值。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 }审计方面每次工具调用都由 audit.ts 写入 SQLitemcp_tool_audit表工具名、参数按各工具auditLevel做哈希/截断、结果、耗时ms、成功/失败标志与错误信息如适用、API key 哈希、时间戳scope 拒绝以scope_denied:reason加缺失 scope 列表记录。可用 dashboard 或/api/mcp/audit、/api/mcp/audit/stats两个 REST 端点查看近期调用。关键源码文件索引文件职责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.tstool/prompt/resource 注册表的描述压缩open-sse/mcp-server/toolCardinality.ts工具基数削减reduceToolManifest、env 解析open-sse/mcp-server/toolCount.ts跨集合去重工具计数open-sse/mcp-server/schemas/tools.tsZod schema 与工具注册表MCP_TOOLS45 条open-sse/mcp-server/tools/各领域工具处理函数advanced、compression、memory、skill、notion、gamification、plugin、obsidian 等src/server/authz/routeGuard.tsLOCAL_ONLY 层级与 manage-scope 旁路src/app/api/mcp/status/route.ts/api/mcp/status端点src/app/api/mcp/audit/stats/route.ts/api/mcp/audit/stats聚合审计指标src/lib/notion/api.tsNotion REST 客户端重试、超时、错误分类配套测试包括 Notion API 客户端测试、Notion 工具 scope 强制测试与 Notion DB 模块测试位于tests/unit/下。IDE 客户端配置Claude Desktop、Cursor、Cline 等的完整步骤见 SETUP_GUIDE.md 的 MCP Client Configuration 章节远程访问的安全模型细节见 ROUTE_GUARD_TIERS.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），仅供参考