LangChain 中文文档

外观

MCP（模型上下文协议）让你可以用外部服务器上的工具来扩展 Deep Agents Code——文件系统、API、数据库等——而无需修改智能体本身。Deep Agents Code 在启动时连接 MCP 服务器，发现它们的工具，并将这些工具与内置工具一起提供给智能体使用。

要添加 MCP 服务器，可以在你的项目中添加一个 .mcp.json 配置文件以实现项目级作用域，也可以在用户级添加以应用于所有项目。

快速入门 ​

本快速入门将 LangChain MCP 服务器添加到本机上每次 Deep Agents Code 会话中。我们建议添加用于概念指南和操作指南的 docs-langchain，以及用于 API 参考的 reference-langchain。

服务器URL涵盖内容
docs-langchainhttps://docs.langchain.com/mcp概念指南、操作指南和教程
reference-langchainhttps://reference.langchain.com/mcp权威 API 参考：类、方法和参数

创建配置文件 ​

    如果尚不存在，请在用户级创建 `.mcp.json` 文件，使该服务器对本机上的每个项目都可用，或在项目级创建。

用户 ​

bash
mkdir -p ~/.deepagents
touch ~/.deepagents/.mcp.json
            此文件（`~/.deepagents/.mcp.json`）中的服务器在本机上的每个项目中都可用。

项目 ​

bash
touch .mcp.json
            此文件（`<project>/.mcp.json`）中的服务器仅对该项目可用。

项目（隐藏） ​

bash
mkdir -p .deepagents
touch .deepagents/.mcp.json
            此文件（`<project>/.deepagents/.mcp.json`）中的服务器对该项目可用，但会保留在仓库根目录之外。

    完整的优先级规则请参阅[发现位置](#discovery-locations)。

添加 MCP 服务器 ​

json
{
    "mcpServers": {
        "docs-langchain": {
            "type": "http",
            "url": "https://docs.langchain.com/mcp"
        },
        "reference-langchain": {
            "type": "http",
            "url": "https://reference.langchain.com/mcp"
        }
    }
}
    要添加更多服务器，请向 `mcpServers` 添加更多条目。OAuth、stdio、SSE 和 HTTP 服务器字段、环境变量及标头请参阅[配置格式](#configuration-format)。

启动 Deep Agents Code ​

bash
dcode
    启动时，Deep Agents Code 会自动发现配置，连接到每个服务器，发现其工具，并打印一条确认信息：

✓ Loaded 3 MCP tools
    在交互式会话中运行 `/mcp` 可查看每个服务器的状态、传输方式以及已加载的工具列表。智能体现在可以在整个会话期间使用这些工具——stdio 服务器在工具调用之间保持存活。

自动发现 ​

Deep Agents Code 会自动在标准位置搜索 .mcp.json 文件。无需任何标志——只需放置配置文件，它就会被拾取。

发现位置 ​

配置按以下顺序检查（优先级从低到高）：

优先级位置作用域
1（最低）~/.deepagents/.mcp.json用户级——适用于所有项目
2<project>/.deepagents/.mcp.json项目级——.deepagents 子目录
3（最高）<project>/.mcp.json项目级——根目录（与 Claude Code 兼容）

项目根目录是包含 .git 文件夹的最近父目录，找不到时回退到当前工作目录。

当存在多个配置文件时，它们的 mcpServers 条目会按服务器名称合并。名称不同的服务器会保留。如果同一个服务器名称出现在多个文件中，则优先级更高的定义会整体替换较早的服务器对象；嵌套字段不会深度合并。这允许项目级配置覆盖用户级条目（例如，固定同一服务器的不同版本），而不会影响你的其他项目。

标志 ​

标志行为
--mcp-config PATH将显式配置添加为最高优先级来源（在自动发现的配置之上合并）
--no-mcp完全禁用 MCP——不加载任何服务器

INFO

--mcp-config 和 --no-mcp 互斥。

Claude Code 兼容性 ​

如果你在项目根目录已经有用于 Claude Code 的 .mcp.json，Deep Agents Code 会自动拾取它——无需额外设置。

配置格式 ​

mcpServers 下的每个键都是一个服务器名称。该服务器的字段决定了 Deep Agents Code 如何连接到它。

stdio 服务器（默认） ​

stdio 服务器以子进程形式启动。Deep Agents Code 通过 stdin/stdout 与它们通信。

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "your-token" }
    }
  }
}

SSE 和 HTTP 服务器 ​

对于远程 MCP 服务器，请将 type 设置为 "sse" 或 "http" 并提供 url：

json
{
  "mcpServers": {
    "remote-api": {
      "type": "sse",
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

字段参考 ​

stdio（默认） ​

    **必填：** `command`。**可选：** `args`、`env`，以及共享的[工具过滤字段](#tool-filtering)。

  • command (string)（必填）：要运行的可执行文件。

  • args (string[])：传递给命令的参数。

  • env (object)：为子进程设置的环境变量。用它来传递 API 密钥和其他凭据，而不会暴露在 shell 历史中。

sse ​

    **必填：** `type: "sse"`、`url`。**可选：** `headers`、`auth`，以及共享的[工具过滤字段](#tool-filtering)。

  • type（必填）：传输类型。对于 Server-Sent Events 使用 "sse"。

  • url (string)（必填）：服务器端点 URL。

  • headers (object)：随每个请求发送的 HTTP 标头。通常用于身份验证。值支持引用父 shell 环境变量的 ${VAR}（在服务器激活时解析）。

  • auth：设置为 "oauth" 以通过 dcode mcp login 驱动 OAuth 登录流程，而不是提供 Authorization 标头。不能与 Authorization 标头结合使用。请参阅OAuth 登录。

http ​

    **必填：** `type: "http"`、`url`。**可选：** `headers`、`auth`，以及共享的[工具过滤字段](#tool-filtering)。

  • type（必填）：传输类型。对于流式 HTTP 使用 "http"。streamable_http 和 streamable-http 作为别名接受。

  • url (string)（必填）：服务器端点 URL。

  • headers (object)：随每个请求发送的 HTTP 标头。通常用于身份验证。值支持引用父 shell 环境变量的 ${VAR}（在服务器激活时解析）。

  • auth：设置为 "oauth" 以通过 dcode mcp login 驱动 OAuth 登录流程，而不是提供 Authorization 标头。不能与 Authorization 标头结合使用。请参阅OAuth 登录。

INFO

type 字段也可以写作 transport，以便与其他 MCP 客户端兼容。

INFO

服务器名称必须匹配 [A-Za-z0-9_-]+。名称用作 OAuth token 文件的磁盘基准名，因此路径分隔符和其他 shell 元字符会在配置加载时被拒绝。

标头环境变量 ​

标头值支持从父 shell 进行 ${VAR} 替换，在服务器激活时（而非配置加载时）解析。只有一个变量未设置只会导致需要它的那个服务器失败；其余服务器仍会正常启动。

json
{
    "mcpServers": {
        "internal-api": {
            "type": "http",
            "url": "https://api.example.com/mcp",
            "headers": { "Authorization": "Bearer ${INTERNAL_API_TOKEN}" }
        }
    }
}

多服务器 ​

你可以根据需要配置任意数量的服务器。来自所有服务器的工具会合并，并可供智能体使用：

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    },
    "database": {
      "type": "sse",
      "url": "https://db-mcp.internal:8080/mcp",
      "headers": { "Authorization": "Bearer ..." }
    }
  }
}

工具过滤 ​

每个服务器都可以通过两个可选字段之一来收窄它向智能体暴露的工具：

  • allowedTools：仅保留列出的工具；丢弃其余所有工具。
  • disabledTools：丢弃列出的工具；保留其余所有工具。

过滤适用于 stdio、HTTP 和 SSE 服务器。以下两种情况都会在配置加载时被拒绝：

  • 在同一服务器上同时设置 allowedTools 和 disabledTools。
  • 将任一字段设置为空列表（会静默剥离所有工具，或成为无操作）。应改为省略该字段。
json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "allowedTools": ["read_file", "list_directory"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "disabledTools": ["delete_repository", "delete_*_branch"]
    }
  }
}

匹配规则 ​

每个条目都是一个字面量工具名或一个 fnmatch 风格的 glob（任何包含 *、? 或 [ 的条目都会被视为模式）。条目会同时与裸 MCP 工具名和服务器前缀形式（{server}_{tool}）进行匹配，因此两种形式都可用：

json
{
  "allowedTools": ["read_file", "fs_list_*"]
}

INFO

与任何已加载工具都不匹配的条目会被记录为警告而非错误——底层 MCP 服务器可以跨版本演化其工具列表，而不会破坏你的配置。

  • allowedTools (string[])：要保留的工具名或 fnmatch glob 模式。来自此服务器的所有其他工具都会被丢弃。与 disabledTools 互斥。

  • disabledTools (string[])：要丢弃的工具名或 fnmatch glob 模式。来自此服务器的所有其他工具都会被保留。与 allowedTools 互斥。

Auto 模式下的只读工具注解 ​

MCP 服务器在宣传工具时可以附加标准的 ToolAnnotations。只有在以下所有条件都为真时，Deep Agents Code 才允许工具绕过Auto 审批模式中的分类器审查：

  • readOnlyHint 为字面量布尔值 true。
  • destructiveHint 缺失、为 null 或 false。
  • 每个提供的标准提示（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）都是布尔值或 null，而不是字符串或其他类型。

未通过此检查的工具在 Auto 模式下会进入分类器批次，在 Manual 模式下使用正常的审批界面，并在无头运行时中被拒绝，因为没有可用的审批界面。该注解是服务器提供的断言，Deep Agents Code 不会独立验证。

OAuth 登录 ​

对于需要 OAuth 的远程 MCP 服务器（Slack、GitHub、Notion、Linear 以及其他托管式 MCP 端点），请在服务器条目上设置 "auth": "oauth" 并运行一次登录子命令。Token 会持久化到磁盘并自动刷新。

配置服务器 ​

json
{
    "mcpServers": {
        "linear": {
            "type": "http",
            "url": "https://mcp.linear.app/mcp",
            "auth": "oauth"
        }
    }
}

auth: "oauth" 与同一条目上的 Authorization 标头互斥，并且不能设置在 stdio 服务器上。

要将 Deep Agents Code 连接到 LangSmith，请使用 LangSmith Remote MCP：

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

运行登录流程 ​

bash
dcode mcp login linear

具体行为取决于服务器的主机：

  • 符合规范的服务器（默认）：Deep Agents Code 执行动态客户端注册（Dynamic Client Registration），在浏览器中打开授权码 + PKCE 流程，并要求你把重定向回来的 URL 粘贴回终端。
  • Slack（slack.com、*.slack.com）：相同的粘贴回填流程，但预先填充了 Slack 的公共客户端。系统会提示你输入可选的团队 ID（例如 T01234567），以便应用安装到正确的工作区。
  • GitHub（api.githubcopilot.com）：RFC 8628 设备授权许可。Deep Agents Code 会打印一个验证 URL 和一个用户代码；你在浏览器中输入该代码，Deep Agents Code 会轮询直至完成。

默认情况下，dcode mcp login 读取与 Deep Agents Code 运行时相同的自动发现配置（受项目级信任门控约束）。传入 --mcp-config <path> 以使用特定文件：

bash
dcode mcp login linear --mcp-config ./mcp-config.json

WARNING

未受信任的项目级配置（参见项目级信任）会在 mcp login 期间被跳过，以防止攻击者控制的 headers 条目通过 ${VAR} 插值窃取本地机密。请在项目中运行 dcode，并选择 Allow for this project — until changed 以保存一次审批，或显式传入 --mcp-config <path>。

Token 存储 ​

Token 写入以下位置：

txt
~/.deepagents/.state/mcp-tokens/<server>-<sha256-16(url)>.json

<sha256-16(url)> 段是服务器 URL 的 SHA-256 的前 16 个十六进制字符。目录被锁定为模式 0700，每个 token 文件为模式 0600。文件包含 OAuth 访问 token、刷新 token 以及动态注册的客户端信息，全部放在一个带模式版本号的负载中，并以原子方式写入（先写入临时文件再 rename）。

INFO

将 URL 哈希到文件名中，意味着指向不同 URL 的同一服务器名称（例如，开发环境与生产环境）会获得独立的 token 文件，不会互相覆盖。

重新身份验证 ​

当运行时刷新失败（刷新 token 过期或被吊销）时，Deep Agents Code 会将服务器标记为 unauthenticated，而不是让智能体崩溃。欢迎横幅会显示未身份验证服务器的数量，/mcp 会报告每个服务器的原因。重新运行 dcode mcp login <server> 以刷新凭据——你的对话会继续，无需重启。

服务器状态 ​

启动后，每个配置的服务器都会处于以下三种状态之一：

状态含义
ok已连接；工具已加载并可供智能体使用
unauthenticated需要 OAuth 登录或刷新失败——运行 dcode mcp login <server>
error预检、发现或传输设置失败；附带一条错误消息

单个服务器失败不再中止启动。智能体会使用任何正常启动的服务器运行，欢迎横幅会在工具计数旁显示未身份验证和出错服务器的数量。在交互式会话中打开 /mcp 可查看每个服务器的状态、传输方式、工具列表，以及非 ok 条目的失败原因。该查看器会随服务器连接而实时更新，并支持 tab/shift+tab 导航。

项目级信任 ​

项目级配置可能包含执行本地命令的 stdio 服务器，以及 headers 可能从你的环境中插值 ${VAR} 的远程服务器。为了防止不受信任的仓库在 CLI 启动时运行任意代码或窃取本地机密，Deep Agents Code 对项目级条目强制执行默认拒绝（default-deny）策略。

INFO

已保存的项目 MCP 审批以及每服务器允许和拒绝策略需要 deepagents-code>=0.1.40。

工作原理 ​

  • 交互式模式： Deep Agents Code 在激活项目服务器前会提示审批，并显示每个 stdio 命令和远程 URL。选择 Allow once 为当前会话激活所有提示的服务器。选择 Allow for this project — until changed 为本会话激活所有提示的服务器，并选择要为未来会话保存哪些审批。
  • 已保存的审批： Deep Agents Code 将选定的服务器审批写入用户级的 ~/.deepagents/config.toml。每项审批都限定于解析后的项目根目录、服务器名称以及该服务器定义的 SHA-256 指纹。如果服务器的命令、URL、标头或其他配置字段发生变化，Deep Agents Code 会再次提示。
  • 非交互式模式（-n）： 没有匹配的已保存或环境审批的项目服务器会被静默跳过，除非传入 --trust-project-mcp。显式拒绝仍然有效。
  • 信任同时涵盖 stdio 和远程条目： 远程服务器可以在预检探测期间对 localhost 或云元数据端点发起 SSRF，并通过标头窃取 ${VAR} 值，因此 Deep Agents Code 以与 stdio 服务器相同的方式对其进行门控。
  • 用户级配置（~/.deepagents/.mcp.json）始终受信任，遵循与 config.toml 和 hooks.json 相同的信任模型。
  • dcode mcp login 也遵循项目信任：不受信任的项目级配置在登录发现期间会被跳过，因此攻击者控制的远程条目无法将机密拉入 OAuth 握手。

标志 ​

标志行为
--trust-project-mcp为当前运行信任项目级服务器，无需提示。被用户策略拒绝的服务器仍保持禁用。
bash
# 跳过审批提示
dcode --trust-project-mcp

# 非交互式：显式信任项目服务器
dcode -n "run tests" --trust-project-mcp

已保存的审批 ​

已保存的审批存储在 ~/.deepagents/config.toml 中：

toml
[mcp]
enabled_project_server_approvals = [
  { project_root = "/Users/you/myproject", name = "docs-langchain", fingerprint = "sha256:abc123..." }
]

要撤销一项审批，请从 enabled_project_server_approvals 中移除对应条目。要在不编辑 config.toml 的情况下强制重新审批，请更改项目 .mcp.json 中的服务器定义；已保存的指纹将不再匹配。

config.toml 中旧的扁平 [mcp].enabled_project_servers 列表会被忽略。已保存的审批请使用 enabled_project_server_approvals。

高级允许和拒绝策略 ​

使用 ~/.deepagents/config.toml 中的 [mcp].disabled_project_servers，或 shell 或全局 ~/.deepagents/.env 中的 DEEPAGENTS_CODE_DISABLED_PROJECT_MCP_SERVERS，可以始终按名称拒绝项目 MCP 服务器。拒绝优先于已保存的审批和 --trust-project-mcp 标志。

对于必须按名称预先批准项目 MCP 服务器的自动化场景，请在 shell 或全局 ~/.deepagents/.env 中将 DEEPAGENTS_CODE_DANGEROUSLY_ENABLE_PROJECT_MCP_SERVERS 设置为以逗号分隔的服务器名称列表。这是一个进程级的逃生舱口：同一服务器名称下的不同项目、命令更改或 URL 更改仍然会匹配。设置此变量后，Deep Agents Code 会忽略该进程的已保存审批。除非你需要跨项目和服务器定义变更进行基于名称的审批，否则请优先使用已保存的审批或 --trust-project-mcp。

deepagents-code>=0.1.40 会忽略旧变量 DEEPAGENTS_CODE_ENABLED_PROJECT_MCP_SERVERS。如果你需要同样的基于名称的行为，请用 DEEPAGENTS_CODE_DANGEROUSLY_ENABLE_PROJECT_MCP_SERVERS 替换它。

WARNING

受信任的 stdio MCP 服务器以你的用户账户权限运行。批准远程服务器允许 Deep Agents Code 在预检期间联系其 URL，并发送其配置的标头。只批准来自你信任的仓库的服务器，并检查审批提示中显示的命令和 URL。

系统提示词感知 ​

已连接的 MCP 服务器及其工具会自动列在智能体的系统提示词中，并按服务器名称和传输类型分组。这有助于模型理解工具来源和故障域，而无需手动上下文。

故障排查 ​

服务器无法启动（stdio） ​

    验证命令在 Deep Agents Code 之外是否能正常工作：
bash
npx -y @modelcontextprotocol/server-filesystem /tmp
    常见原因：包未安装、`npx` 不在 `PATH` 中，或所需的环境变量缺失。

连接被拒绝（SSE/HTTP） ​

    检查远程服务器是否正在运行，以及 URL 是否正确。如果服务器需要身份验证，请确保 `headers` 包含正确的凭据。

工具未出现 ​

    Deep Agents Code 会在启动时打印加载的工具数量（例如，`✓ Loaded 3 MCP tools`）。如果你看到 `0`，说明服务器启动成功但没有宣传任何工具——请检查服务器自身的日志或文档。

服务器在 /mcp 中显示 unauthenticated ​

    要么是你尚未运行 `dcode mcp login <server>`，要么是持久化的刷新 token 已过期或在服务器端被吊销。再次运行登录命令——你的会话会继续运行，token 刷新后服务器会重新连接。

Invalid MCP config at ... ​

    预检验证拒绝了 `--mcp-config`（或自动发现的 `.mcp.json`）。常见原因：不支持的服务器名称（必须匹配 `[A-Za-z0-9_-]+`）、stdio 服务器上的 `auth: oauth`、同一条目上同时设置了 `command` 和 `url`，或标头值不是字符串。修复提示的原因并重新启动——Deep Agents Code 不再为配置错误转储多页的子进程跟踪信息。

${VAR} 标头引用失败 ​

    标头插值在激活时运行，因此未设置的变量只会导致需要它的那个服务器失败。在父 shell 中导出该变量，或将其添加到 `~/.deepagents/.env`。要调试，请设置 `DEEPAGENTS_CODE_DEBUG=1`，并检查关闭时打印到 stderr 的每会话日志路径。

延伸阅读 ​

  • LangSmith Remote MCP：通过 OAuth 将 Deep Agents Code 连接到 LangSmith 工具
  • LangChain MCP 指南：协议细节、构建自定义服务器，以及以编程方式使用 langchain-mcp-adapters
  • MCP 规范：官方协议规范与服务器注册表