# 远程 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`。