OpenConnector Runtime API 设计原理/v1 接口与 MCP 工具如何实现【免费下载链接】open-connectorOpen-source auth gateway connecting 1000 SaaS providers to AI agents through SDK, CLI, MCP, HTTP, and OpenAPI.项目地址: https://gitcode.com/gh_mirrors/op/open-connectorOpenConnector 是一个开源的认证网关通过Runtime API/v1HTTP 接口与MCP 工具两种访问面把 1000 SaaS 服务商连接到 AI Agent。它让开发者只需配置一次凭据就能用统一的方式发现、执行各类 Action操作无需为每个 SaaS 单独写认证逻辑。本文用最通俗的方式拆解这两套接口背后的设计原理与实现细节。1. 为什么需要两套接口OpenConnector 的核心思路是把连接 SaaS这件事抽象成 Action动作目录 执行运行时。/v1/*HTTP 运行时 API面向 SDK 风格客户端、脚本和自动化系统是程序化调用 Action 的入口。/MCPModel Context Protocol端点面向 Claude 等支持 MCP 协议的 AI Agent 宿主暴露一小组发现 执行工具。两者共享同一套底层运行时凭据存储、策略引擎、执行器区别只在说话方式一个说 REST一个说 JSON-RPC。这样同一套安全策略Action 白名单、连接授权能同时约束两类调用方。2./v1接口统一的 JSON 信封设计2.1 端点一览运行时路由集中在 connect-server.ts/v1下共十余个公开端点端点用途GET /v1/health健康检查GET /v1/providers、GET /v1/apps发现服务商与已连接应用GET /v1/actions、GET /v1/actions/search发现 ActionPOST /v1/actions/:actionId执行 Action核心POST /v1/proxy/:service代理调用服务商原始 API2.2 统一响应信封一切皆success所有/v1响应都采用统一的 JSON 信封定义见 runtime-api.ts{ success: true, message: OK, data: {}, meta: {} }失败时额外携带errorCode如unknown_action、connection_not_allowed。这种成功/失败 业务码的设计让客户端只需一套解析逻辑而meta.executionId则把每次执行关联到审计记录实现可追溯的运行日志。错误码到 HTTP 状态的映射同样集中在 runtime-api.ts未知 Action 返回 404、权限不足返回 403、OAuth 令牌过期返回 409、服务商限流返回 429让 AI Agent 能根据状态码做合理的重试或降级决策。2.3 幂等重试Idempotency-Key的巧妙之处执行类 Action如发一封邮件最怕网络抖动导致的重复执行。/v1支持可选的Idempotency-Key请求头实现见 action-idempotency.ts每次新的逻辑操作生成唯一 Key重试同一操作时复用该 Key运行时回放原始响应含原始executionId保留窗口 24 小时Key 与不同 Action、输入或连接搭配时返回409 idempotency_key_conflict。这为脚本和 Agent 提供了至少一次请求、至多一次副作用的近似保证是/v1相比裸调服务商 API 的显著增值。3. MCP 工具给 AI Agent 的发现式五件套 MCP 端点由 mcp.ts 中的createMcpServer构建只暴露5 个精简工具工具作用list_apps列出服务商应用及连接/Action 数量list_connections列出已配置连接及安全的账户信息search_actions按关键词检索 Action 目录get_action_guide返回某个 Action 的 Markdown 指南参数、示例execute_action按 actionId JSON 输入执行 Action3.1 设计哲学先发现后执行MCP 服务器在注册时注入了instructions提示词mcp.ts明确指导 Agent 的工作流先用search_actions发现、再用get_action_guide确认输入结构、最后才execute_action对创建、发送、删除等有外部副作用的 Action必须先确认用户意图。这与/v1的直接执行形成互补——MCP 面把发现能力内建进了工具协议。3.2 无状态 POST 传输/mcp只支持无状态POSTJSON-RPC 请求并返回 JSON 响应路由见 connect-server.ts不维持 SSE 长连接GET /mcp/tools还提供工具元数据预览。这让端点可以部署在 Cloudflare Workers 等无长连接环境里/mcp传输与/v1/proxy直通流量均不被缓冲或重编码connect-server.ts。4. 共享底座策略、连接与多账户两套接口背后是同一套安全与执行底座理解这三点就能看懂全部行为命名连接alias同一个服务商可配置多个账户如default和work。/v1用请求头x-oo-connector-alias或alias查询参数选择MCP 用connectionName字段。缺省总是走default连接绝不静默回退到其他账户。令牌级授权持久运行时令牌可携带allowedActions、blockedActions、allowedProxies和allowedConnections白名单。未授权连接会在凭据查找之前被拦截403 connection_not_allowed发现类接口的返回也会被过滤防止信息泄漏。审计留痕每次执行生成executionId作为稳定运行 ID写入运行日志Web 控制台的 Runs 页面可回溯caller字段还会区分调用来自http、mcp还是webconnect-server.ts。5. 快速上手路径 本地起服务后打开 Web 控制台浏览服务商、配置凭据Overview 页的 Runtime ready 表示就绪脚本与 SDK 走/v1GET /v1/actions发现 →POST /v1/actions/:actionId执行需要防重放时加Idempotency-KeyAI Agent 宿主指向POST /mcp让 Agent 用 5 个工具自主发现并执行需要完整端点列表与 curl 示例时查阅权威文档 runtime-api.md。6. 小结OpenConnector 的 Runtime API 设计可以浓缩为三句话统一信封 稳定错误码让任何语言、任何 Agent 都能低成本集成幂等 Key 与 24 小时回放把重试安全做进协议层/v1管执行MCP 管发现共享同一套策略引擎与审计链路一套安全模型覆盖所有访问面。对于想深入源码的读者建议从 src/server/api/runtime-api.ts信封与错误码、src/mcp.ts工具注册和 docs/runtime-api.md端点参考三个文件读起即可完整还原这套网关的设计脉络。【免费下载链接】open-connectorOpen-source auth gateway connecting 1000 SaaS providers to AI agents through SDK, CLI, MCP, HTTP, and OpenAPI.项目地址: https://gitcode.com/gh_mirrors/op/open-connector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考