MCP 工具 - Docs by LangChain

MCP（模型上下文协议）让你无需修改智能体本身，即可通过外部服务器（文件系统、API、数据库等）扩展深度智能体 CLI 的工具能力。CLI 在启动时连接到 MCP 服务器，发现其工具，并将它们与内置工具一起提供给智能体使用。通过编辑项目中的 .mcp.json 配置文件来添加 MCP 服务器，可设置项目级别的作用域，也可在用户级别设置以应用于所有项目。

快速开始

本快速开始将 LangChain 文档 MCP 服务器添加到你机器上的每个深度智能体 CLI 会话中。替换为任何其他 MCP 服务器的 URL 或 stdio 命令即可，格式相同。

创建配置文件

如果尚未存在，在用户级别创建 .mcp.json 文件以使服务器对机器上的每个项目可用，或在项目级别创建。

用户级
项目级
项目级（隐藏）

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

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

touch .mcp.json

此文件（<project>/.mcp.json）中的服务器可用于此项目。

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

此文件（<project>/.deepagents/.mcp.json）中的服务器可用于此项目，但不会出现在仓库根目录中。

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

添加 MCP 服务器

~/.deepagents/.mcp.json

{
    "mcpServers": {
        "docs-langchain": {
            "type": "http",
            "url": "https://docs.langchain.com/mcp"
        }
    }
}

要添加更多服务器，请在 mcpServers 中添加更多条目。有关 OAuth、stdio、SSE 和 HTTP 服务器字段、环境变量和请求头，请参阅配置格式。

启动 CLI

deepagents

启动时，CLI 会自动发现配置文件，连接到每个服务器，发现其工具，并打印确认信息：

✓ Loaded 3 MCP tools

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

自动发现

CLI 会自动在标准位置搜索 .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——不加载任何服务器

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

Claude Code 兼容性

如果你的项目根目录中已有用于 Claude Code 的 .mcp.json，深度智能体 CLI 会自动识别它——无需额外设置。

配置格式

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

stdio 服务器（默认）

stdio 服务器作为子进程启动。CLI 通过 stdin/stdout 与它们通信。

mcp-config.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：

mcp-config.json

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

字段参考

stdio（默认）

必需： command。可选： args、env，以及共享的工具过滤字段。

command

string

required

要运行的可执行文件。

args

string[]

传递给命令的参数。

env

object

为子进程设置的环境变量。使用此选项传递 API 密钥和其他凭据，而不会在 shell 历史记录中暴露它们。

sse

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

type

"sse"

required

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

url

string

required

服务器端点 URL。

headers

object

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

auth

"oauth"

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

http

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

type

"http"

required

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

url

string

required

服务器端点 URL。

headers

object

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

auth

"oauth"

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

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

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

请求头环境变量

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

.mcp.json

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

多服务器

你可以根据需要配置任意多个服务器。所有服务器的工具会被合并并提供给智能体使用：

mcp-config.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。
将任一字段设置为空列表（会静默删除所有工具，或无效操作）。请改为省略该字段。

.mcp.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}），因此两种形式都可以使用：

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

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

allowedTools

string[]

要保留的工具名称或 fnmatch glob 模式。此服务器的所有其他工具将被丢弃。与 disabledTools 互斥。

disabledTools

string[]

要丢弃的工具名称或 fnmatch glob 模式。此服务器的所有其他工具将被保留。与 allowedTools 互斥。

OAuth 登录

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

OAuth 登录需要 deepagents-cli>=0.0.46。

配置服务器

.mcp.json

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

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

运行登录流程

deepagents mcp login linear

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

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

默认情况下，deepagents mcp login 读取与 CLI 运行时使用的相同自动发现配置（受项目级信任机制约束）。传递 --config <path> 使用特定文件：

deepagents mcp login linear --config ./mcp-config.json

未受信任的项目级配置（参见项目级信任）在 mcp login 期间会被跳过，以防止攻击者控制的 headers 条目通过 ${VAR} 插值窃取本地密钥。先在项目中运行 deepagents 一次以批准配置，或显式传递 --config <path>。

Token 存储

Token 写入到：

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

<sha256-16(url)> 部分是服务器 URL 的 SHA-256 的前 16 个十六进制字符。目录锁定为模式 0700，每个 Token 文件为模式 0600。文件包含 OAuth 访问 Token、刷新 Token 和动态注册的客户端信息，所有内容都在一个带模式版本的有效负载中，以原子方式写入（写入临时文件 + rename）。

将 URL 哈希到文件名中意味着指向不同 URL 的同名服务器（例如 dev 与 prod）获得独立的 Token 文件，不会互相覆盖。

重新身份验证

当运行时刷新失败（刷新 Token 过期或被撤销）时，CLI 将服务器标记为 unauthenticated 而不是导致智能体崩溃。欢迎横幅显示未认证服务器的数量，/mcp 报告每个服务器的原因。重新运行 deepagents mcp login <server> 以刷新凭据——你的对话继续进行而无需重启。

服务器状态

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

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

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

项目级信任

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

工作原理

交互模式： CLI 在激活项目服务器之前提示批准，显示每个 stdio 命令和远程 URL。批准使用 SHA-256 内容指纹持久化——如果配置更改，你将再次被提示。
非交互模式（-n）： 除非传递 --trust-project-mcp，否则项目服务器会被静默跳过。
信任涵盖 stdio 和远程条目——远程服务器可以在预检探测期间 SSRF 到 localhost 或云元数据端点，并通过请求头窃取 ${VAR} 值，因此它们的门控方式与 stdio 相同。
用户级配置（~/.deepagents/.mcp.json）始终受信任——与 config.toml 和 hooks.json 的信任模型相同。
deepagents mcp login 也遵守项目信任：未受信任的项目级配置在登录发现期间被跳过，因此攻击者控制的远程条目无法将密钥拉入 OAuth 握手。

标志

标志	行为
`--trust-project-mcp`	信任所有项目级 stdio 服务器而不提示（用于 CI 和自动化）

# 跳过批准提示
deepagents --trust-project-mcp

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

信任存储

信任决策存储在 ~/.deepagents/config.toml 中：

[mcp_trust.projects]
"/Users/you/myproject" = "sha256:abc123..."

每个键是一个绝对项目根路径。值是连接的项目级配置内容的 SHA-256 摘要。要撤销信任，删除该条目或修改项目的 .mcp.json（这会自动使指纹失效）。

受信任的 stdio MCP 服务器与你的用户账户具有相同权限。仅批准来自你信任的仓库的服务器。在接受之前，请查看批准提示中显示的命令。

系统提示词感知

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

故障排除

服务器启动失败（stdio）

验证该命令在 CLI 外部是否正常工作：

npx -y @modelcontextprotocol/server-filesystem /tmp

常见原因：包未安装、npx 不在 PATH 中，或缺少必需的环境变量。

连接被拒绝（SSE/HTTP）

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

工具未出现

CLI 在启动时打印已加载的工具数量（例如 ✓ Loaded 3 MCP tools）。如果你看到 0，表示服务器启动成功但没有公布任何工具——请检查服务器自身的日志或文档。

服务器在 /mcp 中显示 `unauthenticated`

要么你还没有运行 deepagents mcp login <server>，要么持久化的刷新 Token 已过期或在服务器端被撤销。再次运行登录命令——你的会话将继续运行，服务器将在 Token 刷新后重新连接。

`Invalid MCP config at ...`

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

`${VAR}` 请求头引用失败

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

Documentation Index

​快速开始

​自动发现

​发现位置

​标志

​Claude Code 兼容性

​配置格式

​stdio 服务器（默认）

​SSE 和 HTTP 服务器

​字段参考

​请求头环境变量

​多服务器

​工具过滤

​匹配规则

​OAuth 登录

​配置服务器

​运行登录流程

​Token 存储

​重新身份验证

​服务器状态

​项目级信任

​工作原理

​标志

​信任存储

​系统提示词感知

​故障排除

​延伸阅读

快速开始

自动发现

发现位置

标志

Claude Code 兼容性

配置格式

stdio 服务器（默认）

SSE 和 HTTP 服务器

字段参考

请求头环境变量

多服务器

工具过滤

匹配规则

OAuth 登录

配置服务器

运行登录流程

Token 存储

重新身份验证

服务器状态

项目级信任

工作原理

标志

信任存储

系统提示词感知

故障排除

延伸阅读