将 MCP 工具连接到托管深度代理 - 以编程方式使用文档

托管深度代理可以调用你通过以下方式公开的外部工具模型上下文协议 (MCP)：例如 GitHub、内部服务或第三方 API。LangSmith 管理到每个 MCP 服务器的连接，包括每用户 OAuth，因此代理无需自定义客户端代码即可进行身份验证。

MCP 服务器是 workspace-level 资源。在部署引用它的代理之前，请先注册或连接服务器。在以下位置查看你所有的 MCP 服务器 LangSmith > 设置 > MCP 服务器.

前提条件

- 托管深度代理私人测试版访问权限.
- A LangSmith API 密钥用于具有私人测试版访问权限的工作区。
- MCP 服务器 URL，加上服务器所需的任何静态请求头或 OAuth 凭据。
- 界面的客户端： deepagents-cli 对于 CLI，使用 managed-deepagents (Python) 或 @langchain/managed-deepagents (TypeScript) SDK 用于 SDK 工作流，或使用 HTTP 客户端（如 curl）用于 REST API。有关安装命令和版本要求，请参阅安装客户端快速入门中的内容。

快速入门

从由 deepagents init创建的项目目录中，连接静态请求头工具并部署：

# 1. Register the MCP server.
deepagents mcp-servers add --url https://example.com/mcp --name my-tools

# 2. List its tools and copy the printed tools.json snippet.
deepagents mcp-servers tools my-tools

# 3. Paste the tool entries into tools.json (manual step).

# 4. Deploy the agent.
deepagents deploy

对于 OAuth 服务器，请在注册步骤（第 1 步）之后、列出工具（第 2 步）之前运行 deepagents mcp-servers connect <id|name|url> 。以下各节将详细说明每个步骤。

对于大多数设置，请使用 CLI 。对于 Python 或 TypeScript 自动化，请使用 SDK ，或当你需要直接控制请求负载时，使用 REST API 。

使用 CLI 连接工具

在 CLI 中， add 注册一个服务器， connect 完成已注册服务器的 OAuth 验证。有关所有 MCP 服务器命令和标志，请参阅 CLI 参考文档.

添加静态请求头 MCP 服务器

注册服务器：

deepagents mcp-servers add \
  --url https://example.com/mcp \
  --name my-tools

如果服务器需要静态凭据，请传递请求头：

deepagents mcp-servers add \
  --url https://example.com/mcp \
  --name my-tools \
  --header Authorization="Bearer <token>"

重复 --header 以添加多个请求头：

deepagents mcp-servers add \
  --url https://example.com/mcp \
  --name my-tools \
  --header Authorization="Bearer <token>" \
  --header X-Workspace-ID="<workspace-id>"

如果 CLI 可以访问服务器，它会在注册后列出服务器的 tools 并打印一条 tools.json 代码片段。要跳过该步骤，请传递 --no-tools.

添加 OAuth MCP 服务器

注册并连接 OAuth MCP 服务器：

deepagents mcp-servers add \
  --url https://example.com/mcp \
  --name github-tools \
  --auth-type oauth \
  --connect

该命令执行完整的每用户 OAuth 流程：

为每用户 OAuth 注册 MCP 服务器。
打印并打开验证 URL。
等待您在浏览器中批准访问。
批准完成后确认连接。

要连接已存在的 OAuth MCP 服务器，请运行：

deepagents mcp-servers connect <id|name|url>

使用 --scope 来请求 OAuth 范围：

deepagents mcp-servers connect <id|name|url> \
  --scope repo \
  --scope read:user

使用 --timeout 0 来启动无轮询的 OAuth 流程：

deepagents mcp-servers connect <id|name|url> --timeout 0

当命令启动授权会话时，它会打印验证 URL。重新运行 deepagents mcp-servers connect <id|name|url> 以完成或重用连接。

列出可用工具

列出已注册 MCP 服务器暴露的工具：

deepagents mcp-servers tools <id|name|url>

该命令打印每个工具名称及其第一行描述，然后 tools.json 代码片段。复制您需要的条目，然后引用它们。当服务器的工具有变化时重新运行它以刷新条目。如果没有列出工具，请确认服务器 URL 可访问，并且对于 OAuth 服务器，请确认您已完成 connect.

使用 SDK 或 API 连接工具

设置请求默认值

对于 SDK 使用，请安装并配置托管深度代理 SDK。对于直接 REST 调用，请设置基础 URL 和 API 密钥：

REST 请求需要 X-Api-Key header:

X-Api-Key:

如果请求失败，SDK 会引发 SDK 特定的错误。REST API 返回非 2xx 状态，响应正文中包含错误详情。对于身份验证错误（401 和 403），请参阅 API 参考.

注册静态头部 MCP 服务器

使用 POST /v1/deepagents/mcp-servers:

Python SDK

from managed_deepagents import Client

with Client() as client:
    mcp_server = client.mcp_servers.create(
        name="my-tools",
        url="https://example.com/mcp",
        headers=[
            {"key": "Authorization", "value": "Bearer <token>"},
        ],
    )

print(mcp_server)

TypeScript SDK

const client = new Client();

const mcpServer = await client.mcpServers.create({
  name: "my-tools",
  url: "https://example.com/mcp",
  headers: [{ key: "Authorization", value: "Bearer <token>" }],
});

console.log(mcpServer);

cURL

curl --request POST \
  --url "$DEEPAGENTS_BASE_URL/mcp-servers" \
  --header "X-Api-Key: $LANGSMITH_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "my-tools",
    "url": "https://example.com/mcp",
    "headers": [
      {"key": "Authorization", "value": "Bearer <token>"}
    ]
  }'

注册 OAuth MCP 服务器

使用 SDK 或 API 注册并连接 OAuth 服务器等同于 CLI deepagents mcp-servers add --auth-type oauth --connect 命令。该流程有三个步骤：注册服务器、为其注册 OAuth 提供程序，然后为当前用户启动授权会话。

Python SDK

from managed_deepagents import Client

with Client() as client:
    mcp_server = client.mcp_servers.create(
        name="github-tools",
        url="https://example.com/mcp",
        auth_type="oauth",
        oauth_mode="per_user_dynamic_client",
    )

    provider = client.mcp_servers.register_oauth_provider(mcp_server["id"])
    oauth_provider_id = provider["oauth_provider_id"]

    auth_session = client.auth_sessions.create(
        provider_id=oauth_provider_id,
        scopes=["repo", "read:user"],
        strategy="REUSE",
        is_default=True,
    )

    if auth_session.get("verification_url"):
        print(f"Open: {auth_session['verification_url']}")

    session_id = auth_session.get("id")
    while session_id:
        session = client.auth_sessions.get(session_id)
        if session.get("status") != "PENDING":
            print(session)
            break
        time.sleep(2)

TypeScript SDK

const client = new Client();

const mcpServer = await client.mcpServers.create({
  name: "github-tools",
  url: "https://example.com/mcp",
  auth_type: "oauth",
  oauth_mode: "per_user_dynamic_client",
});

const provider = await client.mcpServers.registerOAuthProvider(mcpServer.id);
const oauthProviderId = provider.oauth_provider_id;

const authSession = await client.authSessions.create({
  provider_id: oauthProviderId,
  scopes: ["repo", "read:user"],
  strategy: "REUSE",
  is_default: true,
});

if (authSession.verification_url) {
  console.log(`Open: ${authSession.verification_url}`);
}

let sessionId = authSession.id;
while (sessionId) {
  const session = await client.authSessions.get(sessionId);
  if (session.status !== "PENDING") {
    console.log(session);
    break;
  }
  await new Promise((resolve) => setTimeout(resolve, 2000));
}

cURL

MCP_SERVER_ID="$(
  curl --silent --request POST \
    --url "$DEEPAGENTS_BASE_URL/mcp-servers" \
    --header "X-Api-Key: $LANGSMITH_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{
      "name": "github-tools",
      "url": "https://example.com/mcp",
      "auth_type": "oauth",
      "oauth_mode": "per_user_dynamic_client"
    }' | jq -r '.id'
)"

OAUTH_PROVIDER_ID="$(
  curl --silent --request POST \
    --url "$DEEPAGENTS_BASE_URL/mcp-servers/$MCP_SERVER_ID/oauth-provider" \
    --header "X-Api-Key: $LANGSMITH_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{}' | jq -r '.oauth_provider_id'
)"

AUTH_SESSION="$(
  curl --silent --request POST \
    --url "$DEEPAGENTS_BASE_URL/auth-sessions" \
    --header "X-Api-Key: $LANGSMITH_API_KEY" \
    --header 'Content-Type: application/json' \
    --data "{
      \"provider_id\": \"$OAUTH_PROVIDER_ID\",
      \"scopes\": [\"repo\", \"read:user\"],
      \"strategy\": \"REUSE\",
      \"is_default\": true
    }"
)"

echo "$AUTH_SESSION" | jq .

使用 strategy="CREATE" 强制启动新的 OAuth 会话。使用 strategy="REUSE" 在有可用令牌时重用现有有效令牌。如果启动-认证-会话响应包含 verification_url，请打开它并轮询认证会话直到其状态为 COMPLETED.

列出服务器的工具

在引用代理中的工具之前，列出已注册MCP服务器公开的工具：

Python SDK

from managed_deepagents import Client

with Client() as client:
    tools = client.mcp_servers.list_tools(
        url="https://example.com/mcp",
    )

print(tools)

TypeScript SDK

const client = new Client();

const tools = await client.mcpServers.listTools({
  url: "https://example.com/mcp",
});

console.log(tools);

cURL

curl --get \
  --url "$DEEPAGENTS_BASE_URL/mcp/tools" \
  --header "X-Api-Key: $LANGSMITH_API_KEY" \
  --data-urlencode "url=https://example.com/mcp"

对于OAuth服务器，还要传递 oauth_provider_id 由OAuth提供商注册返回的：

Python SDK

from managed_deepagents import Client

with Client() as client:
    tools = client.mcp_servers.list_tools(
        url="https://example.com/mcp",
        oauth_provider_id=oauth_provider_id,
    )

TypeScript SDK

const tools = await client.mcpServers.listTools({
  url: "https://example.com/mcp",
  oauthProviderId,
});

cURL

curl --get \
  --url "$DEEPAGENTS_BASE_URL/mcp/tools" \
  --header "X-Api-Key: $LANGSMITH_API_KEY" \
  --data-urlencode "url=https://example.com/mcp" \
  --data-urlencode "oauth_provider_id=$OAUTH_PROVIDER_ID"

要绕过缓存的工具定义并从MCP服务器获取最新定义，请设置 force_refresh=True 在Python中， forceRefresh: true 在TypeScript中，或 force_refresh=true 在REST中。从响应中选择工具名称后，引用它们.

引用工具

工具条目需要 name，一个由已注册MCP服务器公开的工具，以及 mcp_server_url，指向该服务器。 mcp_server_name 和 display_name 字段是可选的。

{
  "tools": [
    {
      "name": "example_tool",
      "mcp_server_url": "https://example.com/mcp",
      "mcp_server_name": "my-tools",
      "display_name": "example_tool"
    }
  ],
  "interrupt_config": {
    "https://example.com/mcp::example_tool": true
  }
}

使用CLI，将这些条目添加到 tools.json 项目根目录中的文件，该文件 deepagents init 包含一个空的 tools 数组。使用SDK或API时，传递相同的对象作为 tools 代理创建或更新请求的字段：

Python SDK

from managed_deepagents import Client

tools_config = {
    "tools": [
        {
            "name": "example_tool",
            "mcp_server_url": "https://example.com/mcp",
            "mcp_server_name": "my-tools",
            "display_name": "example_tool",
        }
    ],
    "interrupt_config": {
        "https://example.com/mcp::example_tool": True,
    },
}

with Client() as client:
    agent = client.agents.update(
        "<agent_id>",
        tools=tools_config,
        include_files=True,
    )

TypeScript SDK

const client = new Client();

const toolsConfig = {
  tools: [
    {
      name: "example_tool",
      mcp_server_url: "https://example.com/mcp",
      mcp_server_name: "my-tools",
      display_name: "example_tool",
    },
  ],
  interrupt_config: {
    "https://example.com/mcp::example_tool": true,
  },
};

const agent = await client.agents.update(
  "<agent_id>",
  { tools: toolsConfig },
  { includeFiles: true },
);

cURL

curl --request PATCH \
  --url "$DEEPAGENTS_BASE_URL/agents/<agent_id>?include_files=true" \
  --header "X-Api-Key: $LANGSMITH_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "tools": {
      "tools": [
        {
          "name": "example_tool",
          "mcp_server_url": "https://example.com/mcp",
          "mcp_server_name": "my-tools",
          "display_name": "example_tool"
        }
      ],
      "interrupt_config": {
        "https://example.com/mcp::example_tool": true
      }
    }
  }'

使用 interrupt_config 需要在工具运行前进行人工批准。按以下方式对每个条目进行键控 "{mcp_server_url}::{tool_name}" 并将其设置为 true。您还可以在键中包含服务器名称： "{mcp_server_url}::{mcp_server_name}::{tool_name}"。当代理调用标记为需要批准的工具时，运行会暂停并产生一个中断，操作员通过 resolve-interrupt路由.

要部署不包含MCP工具的代理，请将 tools.json 留空或省略 tools field.

在部署时验证工具

在部署时，托管深度代理会验证引用的MCP服务器URL：

- 如果服务器URL未注册，请先注册。
- CLI: deepagents mcp-servers add.
- SDK: client.mcp_servers.create(...) 在Python中或 client.mcpServers.create(...) 在TypeScript中。
- API: POST /v1/deepagents/mcp-servers.
- 如果OAuth服务器已注册但调用者无法调用它，请先完成OAuth。
- CLI: deepagents mcp-servers connect <id|name|url>.
- SDK: client.auth_sessions.create(...) 在Python中或 client.authSessions.create(...) 在TypeScript中。
- API：运行 OAuth auth-session流程.

CLI在发送部署请求前会在本地运行此检查。

管理服务器凭证

静态头部与MCP服务器记录一起存储，并在您检查时进行脱敏处理。

任务	CLI	Python SDK	TypeScript SDK	API
列出服务器	`deepagents mcp-servers list`	`client.mcp_servers.list()`	`client.mcpServers.list()`	`GET /v1/deepagents/mcp-servers`
检查服务器（头部已脱敏）	`deepagents mcp-servers get <server>`	`client.mcp_servers.get(mcp_server_id)`	`client.mcpServers.get(mcpServerId)`	`GET /v1/deepagents/mcp-servers/{mcp_server_id}`
更改头部	`deepagents mcp-servers update <server>`	`client.mcp_servers.update(mcp_server_id, headers=[...])`	`client.mcpServers.update(mcpServerId, { headers: [...] })`	`PATCH /v1/deepagents/mcp-servers/{mcp_server_id}`
移除服务器及其存储的头部	`deepagents mcp-servers delete <server>`	`client.mcp_servers.delete(mcp_server_id)`	`client.mcpServers.delete(mcpServerId)`	`DELETE /v1/deepagents/mcp-servers/{mcp_server_id}`

对于OAuth服务器，凭证按用户划分作用域，因此每个调用者完成自己的连接。有关完整的命令列表，请参阅 CLI参考。有关所有MCP服务器路由，请参阅 API参考.

后续步骤

连接工具后，部署代理使用 tools.json 引用已注册MCP服务器URL的文件。