# 远程 Connector MCP 基建方案 状态:用于 Tutti 与 `tsh-server` 协同切换的确定方案。 ## 当前落地范围 Tutti 侧已经采用独立的 MCP `2026-07-28` 无状态 HTTP Client,不复用旧 Stdio / Legacy Streamable HTTP Client。公共 `ImplementationHost` 通过 `RemoteMCPClientFactory` 请求一个产品实现的远端 Client,不再持有 Gateway Base URL、 HTTP Client 或账号授权回调。Tuttid 的 Direct Factory 使用默认 `https://tutti.sh/api/desktop`(可通过 `TUTTI_CONNECTOR_MCP_BASE_URL` 覆盖),并把 实际地址固定派生为 `POST {baseUrl}/v1/connectors/{connectorId}/mcp`;Connector 无法覆盖 该地址。VM-backed 产品可以提供指向 typed desktop relay 的 Factory。 Remote Connector 在建立 Route 时仍会解析本地安装发布物,并把其中合法的 `skills/` 目录投影为 Agent Skill Root;它只是不创建本地执行快照、不启动 Connector 进程。Agent 继续只感知本地聚合 MCP Server `connector`,其 Tool 列表由已激活的本地和远程 Connector Route 共同组成。 同步 Token 授权和异步 OAuth 授权都会读取服务端返回的 `resultConnectionId`,写入账号级 Authorization Projection,并调度 Runtime Reconcile。Remote MCP Route 只携带 Tutti Account Session 访问 Gateway,不请求、缓存或转发 Provider Credential Grant。登录后的 Bootstrap、 安装、授权和断开操作使用同一个 Account Scope。 Tutti 通过本地 MCP Client 将每个已安装的远程 Connector 暴露给 Agent。远程执行统一经过已认证的 `tsh-server` Connector MCP Gateway;Connector 发布物不得包含业务 MCP endpoint 或 Provider 凭据注入策略。 本方案面向 MCP `2026-07-28`,不保留早期远程 MCP 使用的 `initialize`、`Mcp-Session-Id` 或 HTTP `DELETE` 生命周期。本地托管的 stdio MCP Server 继续使用现有 Legacy Client 和生命周期。 ## 职责边界 ```mermaid flowchart LR R["Connector Release
产品契约"] -->|"bindingRef + contractVersion"| B["tsh-server MCP Binding
基础设施契约"] B --> D["已发布的 Binding 快照"] D --> G["Connector MCP Gateway"] T["Tutti 远程 MCP Client"] -->|"POST /v1/connectors/{connectorId}/mcp"| G G --> U["业务 MCP Server"] T --> A["Agent 本地 connector MCP"] ``` Connector Release 与服务端 Binding 必须相互独立: | 关注点 | 归属方 | | ---------------------------------------- | --------------------------- | | Connector 标识、版本和产品元数据 | Connector Release | | 远程 Runtime 类型和公开协议版本 | Connector Release | | 稳定的 Binding 引用和所需能力 | Connector Release | | 向用户展示的授权 Profile | Connector Release | | 不同环境的 Gateway Base URL | Tutti 账号/控制面配置 | | 业务 MCP endpoint 和上游协议模式 | `tsh-server` Binding 控制面 | | Host 白名单和凭据注入方式 | `tsh-server` Binding 控制面 | | 路由、限制、健康、容灾和灰度策略 | `tsh-server` Binding 控制面 | | 用户 Connection 和加密后的 Provider 凭据 | `tsh-server` 授权控制面 | Connector 作者不能决定服务端的出网地址,也不能决定用户 Provider 凭据的发送目标。 ## Connector Release 契约 远程 Connector 只声明客户端和产品语义。具体 Schema 可以位于 `tutti.connector.json`,也可以投影到安装后的 Runtime Descriptor,但逻辑结构如下: ```yaml connectorId: tencent-docs version: 1.0.0 runtime: kind: remote_mcp protocolVersion: 2026-07-28 bindingRef: tencent-docs.primary contractVersion: 1 bindingContractHash: sha256:... authorizationProfile: tencent-docs.personal-token requiredCapabilities: - tools minimumHostVersion: 0.0.0 ``` Connector Release 不得包含: - 业务 MCP endpoint; - 上游 Host 白名单; - Provider Token 的 Header 或 Query 注入配置; - 上游 MCP 版本或兼容模式; - 超时、重试、限流、熔断、区域路由、健康或容灾配置。 Connector 发布方必须在激活 Release 前,根据其引用的已发布 Binding 完成校验。出现以下任一情况时,发布失败:Binding 不存在、授权契约不一致、所需能力未满足、Connector 版本不在 Binding 约束范围内,或契约版本/Hash 不兼容。 ## 公开 Gateway Endpoint Tutti 根据当前环境和 Connector 标识生成 endpoint: ```text POST {tshServerBaseUrl}/v1/connectors/{connectorId}/mcp ``` 每个请求还必须通过 `Tutti-Connector-Version` 固定当前已安装的 Connector Release。客户端不会接收或发送 Binding Revision、业务 endpoint、Connection ID 或 Provider 凭据。 第一阶段只支持: - `server/discover`; - `tools/list`; - `tools/call`。 第一阶段不支持 subscriptions、长期 SSE、MRTR、Tasks、prompts、resources、sampling、elicitation、roots 或 server-to-client requests。客户端发送空的 `clientCapabilities`,Gateway 只声明 `tools` 能力。 ### MCP 请求元数据 每次调用都是独立的 HTTP `POST`,并携带: ```http Content-Type: application/json Accept: application/json, text/event-stream MCP-Protocol-Version: 2026-07-28 Mcp-Method: tools/call Mcp-Name: document.search Tutti-Connector-Version: 1.0.0 Cookie: ``` 每个请求的 `params` 都包含: ```json { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientInfo": { "name": "tutti-connector-host", "version": "" }, "io.modelcontextprotocol/clientCapabilities": {}, "sh.tutti/connectorVersion": "1.0.0" } } ``` `MCP-Protocol-Version`、`Mcp-Method`、`Mcp-Name` 和 Connector Version 必须与 Body 中对应字段一致。当 `Mcp-Name` 或 `Mcp-Param-*` 不是安全的纯 ASCII Header 值时,必须使用 MCP Base64 Sentinel 编码。HTTP Client 从 `tools/list` 校验 `x-mcp-header` 声明,排除不合法的 Tool,并在 `tools/call` 时将合法的基本类型参数映射到 `Mcp-Param-*` Header。 ## 客户端架构 公共 Host 与产品连接策略通过以下 Port 隔离: ```text ImplementationHost -> RemoteMCPClientFactory -> Tuttid Direct Factory -> Tutti Gateway -> VM Product Factory -> typed desktop relay -> Tutti Gateway ``` Factory request 只携带 operation、connection、Connector、account、release、generation 和 signed binding contract 等非凭证身份。公共 Host 继续负责 `server/discover`、 `tools/list`、Tool Schema 注册、Route publication、generation fence 和 Close;Factory 只负责创建实现这些协议方法的 Client。产品不得通过通用 `RoundTripper` 静默改变业务 目标,也不得把账号 Cookie、Provider Credential 或任意上游 URL 放入 Factory request。 Tuttid Direct Factory 在每次请求时通过 daemon-owned authorizer 注入当前账号 Cookie。 VM-backed Factory 使用其产品本地 capability 到达 desktop relay,由 desktop host 校验 生命周期身份并注入账号 Cookie;Relay 失败时不得回退为 VM 持有账号 Session 直连。 远程 HTTP MCP 和本地托管 MCP 使用两个独立的协议 Client: ```text ModernStreamableHTTPClient MCP 2026-07-28 只用于 Tutti Gateway 每个请求均无状态 LegacyMCPClient 保留现有 initialize/session 生命周期 只用于 managed stdio 和明确标记为 legacy 的本地 Runtime ``` `ModernStreamableHTTPClient` 必须: - 每个 JSON-RPC Request 都发送一个新的 HTTP `POST`; - 发送标准请求元数据 Header 和 `_meta`; - 同时支持 JSON 和 Request-scoped SSE Response; - 增量解析 SSE,在收到匹配的最终响应后返回,并在取消时关闭 Response; - 在非 2xx 响应中保留 JSON-RPC Error Body; - 忽略服务端返回的 `Mcp-Session-Id`,且不发送 `DELETE`; - 将 Cursor 视为不透明的可空值,区分字段不存在和空字符串; - 不持久化或按 TTL 缓存 Tool 列表;每次 `tools/list` 和 `tools/call` 都以当前下游列表为准; - 原子替换生成 `Mcp-Param-*` Header 所需的 Tool Schema,已删除 Tool 不得残留。 远程 Route Builder 每次激活都调用 `server/discover`。同一进程内、同一授权身份 (account、connector、release digest、本地 connection id、`connectionVersion`、 `serverRevision`)的成功 `tools/list` 可以由 `ImplementationHost` 复用,避免 Bootstrap 重建 Route 时重复探测;身份变化必须重新列出。该内存表没有 TTL,不写入 SQLite,`Host.Close` 时丢弃,且不得缓存空列表、非法契约或 428/`-33001`/`-33002`。 它只服务 Route 激活校验,不是 Agent 可见列表。调用 Gateway 时不得发送 `initialize` 或 `notifications/initialized`。 ## 授权与 Runtime Reconcile 授权状态和 Agent Route 状态属于同一个持久化工作流: ```mermaid sequenceDiagram participant U as 用户 participant T as Tutti participant G as tsh-server participant R as Runtime Reconciler participant A as Agent U->>T: 提交 Token 或完成 OAuth T->>G: 以冻结的 account scope 完成授权 G-->>T: 授权完成 T->>G: GET authorization snapshot G-->>T: revision + connected + connectionVersion T->>T: 原子保存账号级授权投影 T->>R: 调度持久化 Reconcile R->>G: server/discover; tools/list unless same-boot identity hits Host memory R->>A: 发布或移除 Connector Route ``` 同步 Secret 提交和异步 OAuth 完成必须汇聚到同一个权威快照流程。授权 mutation 成功后,Tutti 立即按冻结的 account scope 重新拉取服务端快照,原子保存 Projection,再调度 Runtime Reconcile;本地 provisional 状态不得覆盖已同步快照。 `tsh-server` 是授权状态唯一真相。Tutti 在登录、Bootstrap、账号切换后通过 `GET /v1/connector-authorizations/snapshot` hydrate 本地 Projection,并以账号级单调 `revision` 与 Connector 级 `connectionVersion` 拒绝旧状态。服务端 `connector.authorization.changed` WebSocket 事件和 MCP `-33001/-33002` 只作为同步提示;5 分钟轮询负责低频校准。变化进入可重试 dirty-set,只有 Route 收敛成功才清除,避免丢失一次性事件。 远端授权 Route 使用稳定的 `account + connector` 本地身份;服务端 `connectionId` 只作为诊断字段,Default Connection 切换不会留下旧 Route。Bootstrap 获取快照失败时只关闭账号授权型远端 Route,不影响无需授权的本地 Connector。所有授权控制面请求和远端 MCP 请求都绑定操作开始时的 account scope,账号切换必须 fail closed。 以下变更都必须触发 Runtime Reconcile: - 授权成功; - Token 或授权 Scope 发生变化; - 授权过期或进入 `reauth_required`; - Connection 被撤销; - Active Default Connection 发生变化; - 已安装的 Connector Release 发生变化。 生产环境 Composition Root 必须提供 `AuthorizationProjections` 和 `AccountRuntimeBindingResolver`。没有 Active Authorized Account Binding 的远程 Connector 必须处于 Disabled 状态,不得向 Agent 发布 Route。安装阶段的 enabled Reconcile 若收到 HTTP 428 或 JSON-RPC `-33001`/`-33002`,必须写成过期投影并重规划 Disabled Desired,而不是把 428 当作可重试的安装失败。安装是设备事实;未授权的远程 Connector 可以已安装,但不向 Agent 发布 Route。 ## Tool 生命周期 1. 安装阶段保存 Connector Release 及其 Binding 契约引用。 2. 授权阶段在 `tsh-server` 建立或更新账号级 Connection。 3. Runtime Reconcile 判断远程 Route 是否启用。 4. `server/discover` 在不访问上游 MCP 的情况下确认 Gateway 协议和公开能力。 5. `tools/list` 返回当前 Connection 可用的 Tool;同一授权身份在本进程内可复用上次成功的激活结果。Tutti 使用 Connector Namespace 注册这些 Tool。 6. `tools/call` 携带已安装的 Connector Version 和当前 Tutti Session 转发给 Gateway。 7. 授权失效时,通过同一个 Reconcile 流程移除或禁用 Route。 Agent 可见的 Tool 不做本地业务缓存:Agent 的 `tools/list` 逐页直取下游;`tools/call` 只定位可能拥有该 Namespace 的 Connector,重新读取其当前 Tool 契约后调用,避免无关 Connector 超时阻塞。Route 激活时的内存复用只跳过启动探测,不作为 Agent 可见列表的真相,也不得用 TTL 或 SQLite 代替下游当前列表。 ## 端到端工作流程 ```mermaid sequenceDiagram participant Agent as Codex / Claude / ACP participant Local as Tutti Connector MCP participant Daemon as Tutti daemon participant Server as tsh-server participant DB as Encrypted Connection DB participant Upstream as Tencent Docs MCP Daemon->>Server: GET authorization snapshot (account cookie) Server->>DB: read revision + default connections DB-->>Server: account authorization state (no secret) Server-->>Daemon: revision + projections Daemon->>Daemon: atomic apply + readiness=true Daemon->>Local: reconcile stable account+connector route Daemon->>Agent: inject standard local HTTP MCP binding Agent->>Local: tools/list Local->>Server: tools/list (account-bound Tutti session) Server->>DB: resolve current Binding + Connection Server->>Upstream: one-shot MCP tools/list with decrypted token Upstream-->>Agent: current tools via Server + Local Agent->>Local: namespaced tools/call Local->>Server: tools/list + tools/call for target Connector Server->>Upstream: one-shot MCP request Upstream-->>Agent: Tool result via Server + Local Server-->>Daemon: connector.authorization.changed (hint) Daemon->>Server: refresh authoritative snapshot Daemon->>Local: dirty-set reconcile; publish or withdraw route ``` ## 错误处理 传输、身份认证和协议错误继续使用 HTTP Error;协议要求时同时返回 MCP JSON-RPC Error Body。Gateway 和协议前置条件均成功后,Tool 或上游业务错误通常返回成功的 JSON-RPC Response,并将 `result.isError` 设置为 `true`。 客户端识别标准 MCP 错误,包括: - `-32601`:不支持的方法; - `-32020`:缺少 Header 或 Header 与 Body 不一致; - `-32022`:不支持的协议版本。 Tutti Gateway 的前置条件错误使用 MCP 保留区间 `-32000..-32099` 以外的错误码: | 错误码 | 含义 | 客户端行为 | | -------- | ------------------------- | ------------------------------------- | | `-33001` | `authorization_required` | 启动或恢复授权;不发布 Route | | `-33002` | `reauth_required` | 将授权投影标记为过期并调度 Reconcile | | `-33003` | `connector_unavailable` | 保留安装状态;展示临时不可用 | | `-33004` | `upstream_timeout` | 展示失败;只允许用户或 Agent 显式重试 | | `-33005` | `upstream_rate_limited` | 存在 Retry 元数据时遵循该元数据 | | `-33006` | `upstream_protocol_error` | 展示集成故障;不得解释为授权故障 | ## 协同切换 本方案不要求兼容旧版远程协议,但仍需控制发布顺序,避免旧 Host 激活不兼容的 Connector: 1. 发布 `tsh-server` Binding 控制面和无状态数据面。 2. 发布包含 `ModernStreamableHTTPClient` 和完整授权/Reconcile 链路的 Tutti。 3. 将 Connector 的 `minimumHostVersion` 设置为对应 Tutti 版本。 4. 发布包含稳定 Binding 契约引用的 Connector Release。 5. 切换完成后,删除旧版远程 Transport Session 和 HTTP `DELETE` 实现。 保留本地 Legacy stdio 支持不是远程 Gateway 的兼容方案,而是独立的 Runtime 能力。 ## 验收标准 - Connector Package 不包含业务 endpoint 或凭据注入策略。 - 授权前不存在远程 Route,授权成功后无需重启即可出现。 - 撤销授权或切换 Default Connection 后,无需重启即可更新 Agent Route。 - 客户端发送 MCP `2026-07-28` 元数据,且不创建 Transport Session。 - `server/discover`、分页 `tools/list` 和 `tools/call` 可通过 Gateway 工作。 - JSON 和 Request-scoped SSE Response 都能正确处理,且不会无限缓冲 Stream。 - 非 2xx JSON-RPC Error Body 能到达授权/Reconcile 逻辑。 - Managed stdio Connector 继续使用 Legacy MCP Client。 服务端 Binding、安全、缓存和上游 Adapter 契约定义在 `tsh-server/docs/connector-mcp.md`。