LangSmith 远程 MCP

通过 OAuth 将 MCP 兼容的客户端连接到 LangSmith，或用 LangSmith API 密钥为编程式客户端进行身份验证。

LangSmith 远程 MCP 是由 LangSmith 托管的一个 Model Context Protocol (MCP) 服务器。它暴露与独立 LangSmith MCP 服务器相同的工具（对话历史、提示、运行和追踪、数据集、实验、账单），而无需单独的部署。交互式 MCP 客户端通过 OAuth 连接，无需 API 密钥或标头配置；编程式客户端可通过 X-Api-Key 标头用 LangSmith API 密钥进行身份验证。

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

端点

LangSmith Cloud：

区域	主机 / URL
GCP US	{`$ / https://${prefix_0 || "api.smith"}.langchain.com${suffix_0 || ""}`}
GCP EU	{`$ / https://eu.${prefix_0 || "api.smith"}.langchain.com${suffix_0 || ""}`}
GCP APAC	{`$ / https://apac.${prefix_0 || "api.smith"}.langchain.com${suffix_0 || ""}`}
AWS US	{`$ / https://aws.${prefix_0 || "api.smith"}.langchain.com${suffix_0 || ""}`}

该服务器在同一主机上通过 RFC 8414 在 /.well-known/oauth-authorization-server 处发现其剩余的 OAuth 元数据，因此兼容的 MCP 客户端只需要上面的 URL。

自托管 LangSmith：

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

BYOC：

https://<data_plane_url>/api/mcp，其中 <data_plane_url> 是你的 BYOC 数据平面的 URL。

身份认证

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

OAuth

带动态客户端注册（RFC 7591）的 OAuth 2.1 是交互式客户端的默认方式。兼容的 MCP 客户端会在首次使用时自行注册——没有需要预配的客户端 ID，也没有需要管理的 API 密钥。

注册之后：

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

会话被限定到你的 LangSmith 用户和工作区权限——通过 MCP 服务器的调用只能查看你的账户被允许查看的内容。

API 密钥

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

请求以拥有该 API 密钥的用户身份被授权，限定到该密钥的工作区和权限——与该密钥在 LangSmith API 别处所拥有的授权相同。接受 workspace_id 参数的工具可以针对特定工作区；否则使用密钥自身的工作区。

WARNING

在 BYOC 上，该 API 密钥必须被指派给你的 LangSmith 工作区。

NOTE

X-Api-Key 标头是远程 MCP 特有的。独立 LangSmith MCP 服务器使用一个不同的标头 LANGSMITH-API-KEY。

快速开始

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> 的形式可用。

Deep Agents Code (dcode)

将该服务器添加到你的用户级 ~/.deepagents/.mcp.json 文件，以便在每个 Deep Agents Code 项目中可用；或把它添加到一个项目级的 .mcp.json 文件，仅供那个项目使用。有关发现位置和优先级规则，参阅 Deep Agents Code MCP 工具文档。

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

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

• 在 Deep Agents Code TUI 中，运行 /mcp，选择 langsmith，并按照登录提示操作。

• 从你的 shell，运行：

  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 中存储令牌。然后它就能针对与远程 MCP 服务器相同的项目、追踪、运行、数据集、实验和线程工作。

AI SDK

对于从 AI SDK 的编程式使用，通过 X-Api-Key 标头和一个内置的 http（Streamable HTTP）传输，用 API 密钥进行身份验证：

import { createMCPClient } from "@ai-sdk/mcp";

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 或 generateText。远程 MCP 是无状态的，并通过标准 Streamable HTTP 传输以 JSON 响应，因此内置传输即可直接使用——你不需要一个自定义传输。

其他客户端

任何支持 Streamable HTTP 传输的 MCP 客户端都能仅凭上面的 URL 连接——使用带动态客户端注册的 OAuth 2.1，或在 X-Api-Key 标头中放一个 LangSmith API 密钥。

已知客户端不兼容

NOTE

OpenAI Codex CLI 无法与 LangSmith 远程 MCP 配合工作。Codex 在 OAuth 流程中省略了 RFC 8707 resource 参数，而该参数是 MCP 授权规范所要求的，因此登录看似成功，但签发的令牌未绑定到 LangSmith MCP，且 initialize 会因一个需要身份验证的错误而失败。两个上游问题影响 Codex 中的令牌交换和授权请求（参阅 openai/codex#20729 和 openai/codex#13891）。在此期间，从 Codex 使用 LangSmith CLI。LangSmith CLI 支持与 MCP 服务器相同的项目、追踪、运行、数据集、实验和线程，并原生支持 OAuth 登录。

可用工具

远程 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
• 账单： get_billing_usage

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

重新身份验证

如果某个客户端失去了它的会话（例如在撤销了你 LangSmith 账户中的访问权限之后，或刷新令牌被作废），从客户端触发重新身份验证：

• Claude Code： 运行 /mcp，选择 langsmith，选择重新身份验证。
• Cursor： 在 MCP 设置中禁用并重新启用该服务器。
• 其他客户端： 查阅该客户端的 MCP 设置 UI。

自托管 LangSmith

自托管 LangSmith 部署在 v0.16 或更高版本上，会在 https://<your-langsmith-host>/api/mcp 暴露远程 MCP。一旦启用，身份验证和工具集与 LangSmith Cloud 完全相同。

启用远程 MCP

当设置了 config.hostname 时，远程 MCP 及其 OAuth 授权服务器会被自动接线，但在你提供一个签名 JWKS 之前它们保持无效（404）。这是 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

2. 将其提供给 chart，作为 config.signingJwks（存储在该 chart 的 secret 中），或作为 langsmith_signing_jwks 键放在你的现有 secret 中：

   config:
     hostname: "your-langsmith-host"
     signingJwks: |
       {"keys":[ ... ]}

WARNING

不要通过 commonEnv 或 extraEnv 直接设置 LANGSMITH_SIGNING_JWKS——该 chart 已经从 secret 把它接好线，而手动复制会因重复的环境变量错误而使安装失败。请改用 config.signingJwks 或 config.existingSecretName。

升级后，OAuth 发现端点和 /api/mcp 会上线。用以下命令验证：

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

对于较早版本上的部署，在你自己的环境中运行独立 LangSmith MCP 服务器，并把它的 LANGSMITH_ENDPOINT 指向你的自托管实例。

---