以编程方式使用文档

LangSmith 远程 MCP 是一个 模型上下文协议 （MCP）服务器，由 LangSmith 托管。它提供与 独立 LangSmith MCP 服务器 相同的工具（对话历史、提示、运行和追踪、数据集、实验、计费），无需单独部署。交互式 MCP 客户端通过 OAuth 连接，无需 API 密钥或标头配置；编程客户端可以通过以下方式使用 LangSmith API 密钥进行身份验证 X-Api-Key header.

远程 MCP 在所有 LangSmith Cloud 区域和 自托管 LangSmith 部署（运行 v0.16 或更高版本）上可用（自托管还需要配置签名 JWKS——请参阅 自托管 LangSmith）。早期版本的自托管部署应继续使用 独立 LangSmith MCP 服务器.

端点

LangSmith Cloud：

服务器通过以下方式发现其余的 OAuth 元数据 RFC 8414 at /.well-known/oauth-authorization-server 在同一主机上，因此符合标准的 MCP 客户端只需要上面的 URL。

自托管 LangSmith：

https://<your-langsmith-host>/api/mcp，其中 <your-langsmith-host> 是您的 LangSmith 实例的主机名。

身份验证

远程 MCP 支持两种身份验证方法。使用 **OAuth** 用于交互式 MCP 客户端（Claude Code、Cursor 等），以及 **API 密钥** 用于无法完成基于浏览器的登录的编程或无头客户端。

OAuth

OAuth 2.1 与 动态客户端注册 (RFC 7591) 是交互式客户端的默认设置。兼容的 MCP 客户端在首次使用时自动注册——无需配置客户端 ID，也无需管理 API 密钥。

注册后：

  1. 客户端在您的浏览器中打开授权 URL。
  2. 您登录 LangSmith（或使用现有会话）并同意。
  3. 客户端接收访问令牌和刷新令牌。
  4. 访问令牌过期时客户端会自动刷新。

会话范围限定为您的 LangSmith 用户和工作区权限——通过 MCP 服务器的调用只能查看您的账户有权查看的内容。

API 密钥

在每个请求的 LangSmith API 密钥 标头中发送一个 X-Api-Key 标头。这适用于后端服务、脚本和 SDK，例如 AI SDK，其中交互式 OAuth 流程不可行。

请求以拥有 API 密钥的用户身份授权，范围限定为该密钥的工作区和权限——与该密钥在 LangSmith API 其他地方的授权相同。接受 workspace_id 参数可以指向特定的工作区；否则使用密钥自己的工作区。

快速入门

Claude Code

将服务器添加到项目的 .mcp.json （或运行 claude mcp add --transport http -s user langsmith https://api.smith.langchain.com/mcp 进行用户级安装）：

{
  "mcpServers": {
    "langsmith": {
      "type": "http",
      "url": "https://api.smith.langchain.com/mcp"
    }
  }
}

然后运行 /mcp 并选择 **langsmith** 以完成 OAuth 流程。工具将作为 mcp__langsmith__<tool_name>.

深度代理代码（dcode)

将服务器添加到用户级 ~/.deepagents/.mcp.json 文件中，使其在每个深度代理代码项目中可用，或将其添加到项目级 .mcp.json 文件中，仅限该项目。请参阅 深度代理代码 MCP 工具文档 了解发现位置和优先级规则。

{
  "mcpServers": {
    "langsmith": {
      "url": "https://api.smith.langchain.com/mcp",
      "transport": "http",
      "auth": "oauth"
    }
  }
}

然后通过以下两种方式之一完成 OAuth 登录流程：

  • - 在深度代理代码 TUI 中，运行 /mcp，选择 **langsmith**，然后按提示登录。
  • - 从终端运行：
  dcode mcp login langsmith

启动 dcode，或重启现有会话以加载 LangSmith MCP 工具。在交互式会话中运行 /mcp 查看服务器状态和已加载的工具。

Cursor

添加到 Cursor mcp.json:

{
  "mcpServers": {
    "LangSmith": {
      "url": "https://api.smith.langchain.com/mcp"
    }
  }
}

Cursor 会在首次使用时会引导你完成 OAuth 流程。

LangSmith CLI

此 LangSmith CLI 使用相同的 OAuth 服务器进行身份验证，因此 langsmith auth login 通过 OAuth 设备流程登录——无需 API 密钥：

# LangSmith Cloud
langsmith auth login

# Self-hosted (point at your instance's /api base)
langsmith auth login --api-url https://<your-langsmith-host>/api

CLI 会输出激活 URL；打开它并批准后，CLI 完成登录并按配置文件将令牌存储在 ~/.langsmith/config.json。然后它可以像 Remote MCP 服务器一样访问相同的项目、追踪、运行、数据集、实验和线程。

AI SDK

对于通过 AI SDK进行编程使用，请通过 X-Api-Key 标头和内置的 http （Streamable HTTP）传输方式：

const client = await createMCPClient({
  transport: {
    type: "http",
    url: "https://api.smith.langchain.com/mcp",
    headers: { "X-Api-Key": process.env.LANGSMITH_API_KEY! },
  },
});

const tools = await client.tools();

将 tools 直接传递给 streamText or generateText。Remote MCP 是无状态的，通过标准 Streamable HTTP 传输返回 JSON，因此内置传输方式可以直接使用——无需自定义传输。

其他客户端

任何支持 Streamable HTTP 传输方式 只需使用上述 URL 即可连接——使用 OAuth 2.1 和动态客户端注册，或使用 LangSmith API 密钥 X-Api-Key header.

已知客户端不兼容问题

可用工具

Remote MCP 公开与 独立服务器:

  • 对话和线程： get_thread_history
  • 提示管理： list_prompts, get_prompt_by_name, push_prompt
  • 跟踪和运行： fetch_runs, list_projects
  • 数据集和示例： list_datasets, list_examples, read_dataset, read_example, create_dataset, update_examples
  • 实验和评估： list_experiments, run_experiment
  • Billing: get_billing_usage

参阅 独立服务器参考 了解参数和分页详情——两个服务器共享相同的工具实现。

Re-authenticating

如果客户端丢失会话（例如，在 LangSmith 账户中撤销访问权限后，或刷新令牌失效），则从客户端触发重新认证：

  • Claude Code： 运行 /mcp，选择 **langsmith**，选择重新认证。
  • Cursor: 在 MCP 设置中禁用并重新启用服务器。
  • 其他客户端： 请查阅客户端的 MCP 设置界面。

自托管 LangSmith

自托管 LangSmith v0.16 或更高版本的部署在以下位置暴露 Remote MCP https://<your-langsmith-host>/api/mcp。启用后，身份验证和工具界面与 LangSmith Cloud 相同。

启用 Remote MCP

当设置 config.hostname 时，Remote MCP 及其 OAuth 授权服务器会自动连接，但它们保持 **静止状态（404）** ，直到您提供签名 JWKS。这是 LangSmith Cloud 为您处理的唯一配置项。要启用它：

  1. **生成 Ed25519 (OKP) JWKS。** RSA 密钥会被拒绝。例如，使用 step:
   step crypto jwk create /dev/null /tmp/jwk.json --kty OKP --crv Ed25519 --no-password --insecure -f
   jq -c '{keys:[.]}' /tmp/jwk.json   # wrap the single key in a JWKS
  1. **将其提供给 chart** as config.signingJwks （存储在 chart secret 中），或作为密钥 langsmith_signing_jwks 在您的 现有 secret 中:
   config:
     hostname: "your-langsmith-host"
     signingJwks: |
       {"keys":[ ... ]}

升级后，OAuth发现端点和 /api/mcp 变为可用。使用以下方式验证：

curl https://<your-langsmith-host>/api/.well-known/oauth-protected-resource/mcp

对于早期版本的部署，请运行 独立的LangSmith MCP服务器 在您自己的环境中，并将其 LANGSMITH_ENDPOINT 指向您的自托管实例。