---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - mcp
  - tools
topic: LangSmith Smith API MCP 发现代理、供应商集成与 Workspace Tool 目录
sources:
  - https://docs.langchain.com/langsmith/smith-api/mcp/get-tools
  - https://docs.langchain.com/langsmith/smith-api/mcp/invalidate-tools-cache
  - https://docs.langchain.com/langsmith/smith-api/mcp/proxy
  - https://docs.langchain.com/langsmith/smith-api/mcp/proxy-get
  - https://docs.langchain.com/langsmith/smith-api/mcp_vendors/create-vendor-settings
  - https://docs.langchain.com/langsmith/smith-api/mcp_vendors/delete-vendor-settings
  - https://docs.langchain.com/langsmith/smith-api/mcp_vendors/get-mcp-vendor
  - https://docs.langchain.com/langsmith/smith-api/mcp_vendors/get-vendor-account
  - https://docs.langchain.com/langsmith/smith-api/mcp_vendors/get-vendor-settings
  - https://docs.langchain.com/langsmith/smith-api/mcp_vendors/list-mcp-servers-for-a-vendor
  - https://docs.langchain.com/langsmith/smith-api/mcp_vendors/list-mcp-vendors
  - https://docs.langchain.com/langsmith/smith-api/mcp_vendors/list-tools-for-a-vendor
  - https://docs.langchain.com/langsmith/smith-api/mcp_vendors/replace-vendor-settings
  - https://docs.langchain.com/langsmith/smith-api/tools/create-a-tool
  - https://docs.langchain.com/langsmith/smith-api/tools/delete-a-tool-by-handle
  - https://docs.langchain.com/langsmith/smith-api/tools/delete-a-tool-by-id
  - https://docs.langchain.com/langsmith/smith-api/tools/get-a-tool-by-handle
  - https://docs.langchain.com/langsmith/smith-api/tools/get-a-tool-by-id
  - https://docs.langchain.com/langsmith/smith-api/tools/list-tools
  - https://docs.langchain.com/langsmith/smith-api/tools/update-a-tool-by-handle
  - https://docs.langchain.com/langsmith/smith-api/tools/update-a-tool-by-id
last_verified: 2026-08-11
---

# 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 举例：

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

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

## 一条可审计的工具解析链

```text
用户/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 缓存。