MCP 工具

从 MCP（Model Context Protocol）服务器加载额外的工具

MCP（Model Context Protocol）使你能够用来自外部服务器（文件系统、API、数据库等）的工具扩展 Deep Agents Code，而无需修改智能体本身。Deep Agents Code 会在启动时连接 MCP 服务器、发现它们的工具，并将这些工具与内置工具一并提供给智能体。

通过在项目中添加 .mcp.json 配置文件（项目级作用域）来添加 MCP 服务器，或在用户级添加以应用于所有项目。

将下面这段提示词粘贴到你的编码智能体中即可连接这些服务器，或者按照下面专门针对 Deep Agents Code 的步骤操作。对于其他编辑器，参见以编程方式使用文档。

把两个 LangChain 文档 MCP 服务器都连接到我的编码智能体，使其能够查阅最新的 LangChain、LangGraph 和 LangSmith 文档与 API 参考。

要添加的服务器：

docs-langchain: https://docs.langchain.com/mcp
reference-langchain: https://reference.langchain.com/mcp

判断我正在使用的智能体或编辑器（Claude Code、Cursor、Codex CLI、Claude Desktop、Deep Agents Code、VS Code、Antigravity 或其他兼容 MCP 的客户端）。使用 https://docs.langchain.com/use-these-docs.md 中与之对应的设置：

Claude Code：为每个服务器执行 claude mcp add --transport http（默认为项目作用域；只有当我要求全局访问时才使用 --scope user）。
Codex CLI：使用 codex mcp add 并分别指定每个服务器的 URL。
Cursor、Deep Agents Code、VS Code 或 Antigravity：按照该页面上针对我的客户端给出的字段名，把这两条条目合并进 MCP 设置 JSON。
Claude Desktop：在 Settings > Connectors 下添加这两个 URL。

不要臆造其他 MCP URL。配置完成后，请确认两个服务器都已列出且可访问。

快速开始

本快速开始会把 LangChain MCP 服务器添加到你机器上的每一个 Deep Agents Code 会话中。我们建议添加 docs-langchain 以获取概念指南和操作教程，添加 reference-langchain 以获取 API 参考。

服务器	URL	覆盖范围
`docs-langchain`	`https://docs.langchain.com/mcp`	概念指南、操作教程和入门教程
`reference-langchain`	`https://reference.langchain.com/mcp`	权威 API 参考：类、方法和参数

Create the config file

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

bash

mkdir -p ~/.deepagents
touch ~/.deepagents/.mcp.json

此文件（~/.deepagents/.mcp.json）中的服务器在本机的每个项目中都可用。

有关完整的优先级规则，参见发现位置。

Add the MCP servers

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 服务器的字段、环境变量与请求头，参见配置格式。

Launch 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——不加载任何服务器

NOTE

--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，以及共享的工具过滤字段。

string必填

要运行的可执行文件。

string[]

传递给该命令的参数。

object

为子进程设置的环境变量。使用它传递 API 密钥和其他凭证，可避免在 shell 历史记录中暴露它们。

sse

必填： type: "sse"、url。可选： headers、auth，以及共享的工具过滤字段。

"sse"必填

传输类型。使用 "sse" 表示 Server-Sent Events。

string必填

服务器端点的 URL。

object

随每个请求发送的 HTTP 请求头。通常用于身份认证。取值支持以 ${VAR} 引用父 shell 的环境变量（在服务器激活时解析）。

"oauth"

设为 "oauth"，以通过 dcode mcp login 驱动 OAuth 登录流程，而无需提供 Authorization 请求头。不能与 Authorization 请求头同时使用。参见 OAuth 登录。

http

必填： type: "http"、url。可选： headers、auth，以及共享的工具过滤字段。

"http"必填

传输类型。使用 "http" 表示可流式传输的 HTTP。streamable_http 和 streamable-http 作为别名也被接受。

string必填

服务器端点的 URL。

object

随每个请求发送的 HTTP 请求头。通常用于身份认证。取值支持以 ${VAR} 引用父 shell 的环境变量（在服务器激活时解析）。

"oauth"

设为 "oauth"，以通过 dcode mcp login 驱动 OAuth 登录流程，而无需提供 Authorization 请求头。不能与 Authorization 请求头同时使用。参见 OAuth 登录。

NOTE

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

NOTE

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

环境变量插值

command、args、env、url 和 headers 中的字符串值支持以 ${VAR} 引用父 shell 的环境变量。当变量未设置或为空时，可使用 ${VAR:-default} 提供取值。

json

{
    "mcpServers": {
        "work-docs": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "${WORK_DOCS_DIR:-/tmp/work-docs}"],
            "env": { "LOG_LEVEL": "${MCP_LOG_LEVEL:-info}" }
        }
    }
}

多个服务器

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

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 风格的通配符（任何包含 *、? 或 [ 的条目都会被视为模式）。条目会同时与未加前缀的 MCP 工具名称和带服务器前缀的形式（{server}_{tool}）进行匹配，因此两种形式都可用：

json

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

NOTE

没有匹配到任何已加载工具的条目会记录为警告而非错误——底层 MCP 服务器可以在不同版本间演进其工具列表，而不会破坏你的配置。

string[]

要保留的工具名称或 fnmatch 通配符模式。该服务器的其他所有工具都会被丢弃。与 disabledTools 互斥。

string[]

要丢弃的工具名称或 fnmatch 通配符模式。该服务器的其他所有工具都会被保留。与 allowedTools 互斥。

Auto 模式下的只读工具注解

MCP 服务器在通告工具时可以附加标准的 ToolAnnotations。只有在以下全部条件都成立时，Deep Agents Code 才允许某个工具绕过自动批准模式下的分类器审查：

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"，并运行一次登录子命令。令牌会持久化到磁盘并自动刷新。

配置服务器

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"
        }
    }
}

运行登录流程

列出已配置但没有已存储凭证的 OAuth 服务器：

bash

dcode mcp login

然后为某个服务器运行登录流程：

bash

dcode mcp login linear

该列表使用与登录流程相同的、受信任门控的配置。它会报告那些设置了 auth: "oauth" 但没有已存储令牌的服务器。它不会检查令牌是否过期。

具体发生什么取决于服务器的主机：

符合规范的服务器（默认）：Deep Agents Code 会执行动态客户端注册，在浏览器中打开授权码 + 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>。

令牌存储

令牌会写入：

text

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

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

NOTE

把 URL 哈希进文件名意味着，同一个服务器名称指向不同 URL（例如 dev 与 prod）时会获得彼此独立的令牌文件，不会相互覆盖。

重新认证

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

若要在不离开会话的情况下重新认证某个 OAuth 服务器，请打开 /mcp，选中该服务器，然后按 Enter。

服务器状态

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

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

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

项目级信任

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

NOTE

已保存的项目 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

# Skip the approval prompt
dcode --trust-project-mcp

# Non-interactive: explicitly trust project servers
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 中的服务器定义；此时已保存的指纹将不再匹配。

旧式的扁平列表 [mcp].enabled_project_servers 在 config.toml 中会被忽略。请改用 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>，要么是持久化的刷新令牌已过期或在服务端被撤销。重新运行登录命令即可——你的会话会继续运行，令牌刷新后服务器会重新挂接。

Invalid MCP config at ...

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

${VAR} 引用失败

在父 shell 中导出该变量、将其添加到 ~/.deepagents/.env，或为该引用提供 ${VAR:-default} 回退值。要调试，请设置 DEEPAGENTS_CODE_DEBUG=1，并查看关闭时输出到 stderr 的每会话日志路径。

数据集

创建数据集

运行评估

评估技术

定义评估目标

打分方法

实验配置

多模态评估

分析实验结果

微调

教程

常见数据类型

评估器类型

UI

SDK

框架与集成

改进评估器

反馈

追踪设置

集成

手动埋点

配置与故障排除

项目与环境设置

高级追踪技术

数据与隐私

故障排除指南

查看与管理追踪

批量导出追踪数据

轨迹视图

数据类型参考

监控与告警

在线评估器

自动化

开发你的应用

设置依赖

持久化

能力

助手

运行

并发消息处理

如何构建

鉴权与访问控制

自定义鉴权教程

服务器定制

静态加密

替换内置后端

扩展 HTTP 服务器

请求头与日志

部署指南

参考

配置

参考

提示词

创建与管理提示词

连接模型

上下文中枢

教程

全栈 Web 应用

Agent Server API

控制平面 API

计费与用量

参考

按云服务商起步

用 Terraform 部署

AWS

GCP

Azure

安装实例

配置实例

连接外部服务

平台鉴权与访问控制

管理实例

自托管可观测性

混合部署

脚本

参考

组织