Smith API：MCP 供应商、代理缓存与 Tool 目录

这组接口包含三个不同层次：Workspace 原生 Tool 目录、任意 MCP Server 的发现/代理通道，以及平台维护的 MCP Vendor 集成。它们可能最终都表现为“可调用工具”，但资源所有权、缓存、身份与故障域不同，集成层不能把它们压成一个无来源的工具列表。

Workspace Tool 目录

/api/v1/platform/tools 是 Workspace 范围的工具元数据 CRUD：

操作	标识	关键语义
create	collection	handle/name/description/parameters 必填；enabled、returns、metadata 可选；handle 冲突为 409
list	collection	limit/offset 分页，query 按名称或描述搜索，返回 total 与 next_offset
get/delete	handle 或 `id/{uuid}`	两套等价定位入口
patch	handle 或 `id/{uuid}`	可改 name、description、enabled、parameters、returns、metadata

Tool 模型保存 ID、tenant_id、handle、JSON-like parameter/return schema、metadata 与时间戳。Update payload 不含 handle，因此 handle 是稳定引用，若需要变更应创建新 handle、迁移调用方、再删除旧项。ID 适合内部关系，handle 适合配置与可读调用；不要把可变 display name 当主键。

parameters 和 returns 在 OpenAPI 中是通用 object，服务端契约没有替客户端完成完整 JSON Schema 治理。生产目录应额外验证 schema 可解析、字段描述完整、返回结构与实际实现一致，并限制 schema 深度和大小。enabled=false 应在执行入口再次校验，不能只靠 UI 隐藏。

MCP Tool 发现与缓存

GET /api/v1/mcp/tools 以远端 server url 为必填参数，返回工具目录。其获取顺序是：命中新鲜缓存直接返回；缓存缺失时先尝试快速 manifest fetch，再回退到完整 MCP handshake；结果以 upsert 写回缓存。

身份相关参数：

oauth_provider_id 选择 OAuth provider；
ls_user_id 选择 LangSmith user subject，但 override 仅允许 service identity；
agent_id 让 deployment/service-key 调用方指定 agent OAuth subject；
force_refresh=true 绕过读缓存，但新结果仍会缓存。

缓存 key 不能只包含 URL：OAuth provider、用户/agent subject 可能影响可见 tools。跨身份复用错误缓存会造成权限泄露。调用 tool 遇到 stale-tools 错误后，使用 DELETE /api/v1/mcp/tools 按 URL/provider/user 失效缓存，再由下一次 GET 重新发现；不要在每个请求上强制 refresh，避免把远端握手变成主链路瓶颈。

MCP Proxy

POST /api/v1/mcp/proxy 接收：

必填 URL；
method，支持 GET/POST/PUT/DELETE/PATCH/HEAD/OPTIONS，默认 GET；
headers、body、OAuth provider、user/agent subject；
timeout，默认 120 秒。

GET 版本把 URL 放在 query，accept_stream 默认 true，timeout 默认 60 秒。两者响应都只是通用 object，页面未给更强的下游响应 schema，也未声明重试或幂等保证。

这是高风险出站代理边界。OpenAPI 只描述字段，并不证明平台会替业务完成所有 SSRF 防护；调用方仍应只允许已登记 MCP origins，拒绝 loopback/link-local/metadata/private network 等非预期地址，限制重定向、协议、端口、body/response 大小，并清理 hop-by-hop 与用户不可控认证 headers。Proxy POST 的 method 可能有副作用，网络超时后不能默认重放。

MCP Vendor 模型

Vendor 入口以 vendor_slug 定位，目前 schema 用 Arcade 的 organization/project settings 举例：

GET /mcp-vendors 返回 vendor catalog，包括 vendor_id、名称、描述、icon 与 enabled/disabled 状态。
GET /{vendor} 同时返回 provider_id、status 与当前 settings。
GET /{vendor}/account 解析 OAuth token，返回账户下 organizations/projects 及默认项；上游失败可能 502。
Settings 的 POST 是初始化，PUT 是整体替换，DELETE 移除配置；organization_id 和 project_id 是核心字段，重复创建可 409。
GET /{vendor}/mcp-servers 返回配置 org/project 下的 MCP gateways，含 binding、auth_type、status、instructions 与 allowed_tools filter；limit/offset 默认语义分别约 100/0。
GET /{vendor}/tools 返回 vendor 工具目录，limit/offset 默认语义约 50/0，响应含 total。

Vendor enabled 只表示平台目录状态；settings configured、OAuth account 可解析、gateway status 可用、tool 在 allow list、最终用户具备下游权限，全部成立后才应允许调用。任何一层失败都应保留明确错误来源，不要统一伪装成“tool not found”。

一条可审计的工具解析链

用户/Agent 身份
  → Workspace integration policy
  → Tool enabled + schema
  → Vendor/MCP server configured
  → OAuth subject 与下游授权
  → MCP discovery cache
  → 实际 invoke/proxy
  → 结果校验与 trace

调用 trace 至少记录 tool ID/handle、vendor/server 标识、schema 版本或摘要、OAuth subject 的非敏感 ID、耗时、状态与错误分类；不得记录 access token、代理认证 header、完整敏感输入输出。Tool schema 或远端 manifest 变化时要做兼容性检查，避免旧 agent 按缓存 schema 发送已失效参数。

失败与重试

400/422：本地参数或 schema 错误，修正后再请求。
401/403：认证或 workspace/downstream 权限，不自动刷新重试风暴。
404：未知 tool/vendor/settings，也可能是作用域不可见。
409：handle/settings 创建冲突，先读取现有资源再决定更新。
502：vendor 上游故障，可对 GET 做有界退避；写请求先核对是否已生效。
stale tool：精确失效对应缓存后重发现，不清空全 workspace 缓存。