Skip to main content
MCP（模型上下文协议） 允许您通过外部服务器的文件系统、API、数据库等扩展 Deep Agents CLI，而无需修改代理本身。CLI 在启动时连接到 MCP 服务器，发现其工具，并将这些工具与内置工具一起提供给代理。

​
快速入门

创建配置文件

在项目根目录下创建一个 .mcp.json 文件。格式遵循 Claude Desktop 的约定：
.mcp.json
{
    "mcpServers": {
        "docs-langchain": {
            "type": "http",
            "url": "https://docs.langchain.com/mcp"
        }
    }
}

启动 CLI

deepagents
启动时，CLI 自动发现您的 .mcp.json 文件，启动每个配置的服务器，发现其工具，并打印确认信息：
✓ 加载了 3 个 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 兼容性

如果您已经在项目根目录下有一个 .mcp.json 文件用于 Claude Code，Deep Agents 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" }
    }
  }
}
​
command
string
required
要运行的可执行文件。
​
args
string[]
传递给命令的参数。
​
env
object
为子进程设置的环境变量。使用此字段来传递 API 密钥和其他凭据，而不将其暴露在 shell 历史记录中。

​
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" }
    }
  }
}
​
type
string
required
运输类型："sse" 表示 Server-Sent Events 或 "http" 表示可流式传输的 HTTP。
​
url
string
required
服务器端点 URL。
​
headers
object
每个请求发送的 HTTP 头。通常用于身份验证。

​
服务器类型总结

类型必需字段可选字段
stdio (默认)commandargs, env
ssetype: "sse", urlheaders
httptype: "http", urlheaders
type 字段也可以写为 transport 以与其他 MCP 客户端兼容。

​
多个服务器

您可以配置所需的任意多个服务器。来自所有服务器的工具会被合并并提供给代理：
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 ..." }
    }
  }
}

​
项目级别信任

项目级别的配置可以包含执行本地命令的 stdio 服务器。为了防止不可信的仓库在 CLI 启动时运行任意代码，CLI 对项目级别的 stdio 服务器实施 默认拒绝 策略。

​
工作原理

  • 交互模式： CLI 在启动项目 stdio 服务器之前会提示您确认，显示确切的命令。如果配置更改，则会再次提示。
  • 非交互模式 (-n)： 如果未传递 --trust-project-mcp 标志，则静默跳过项目 stdio 服务器。
  • 来自项目配置的远程服务器 (SSE/HTTP) 始终允许，因为它们不会执行本地代码。
  • 用户级别配置 (~/.deepagents/.mcp.json) 总是可信—与 config.toml 和 hooks.json 的信任模型相同。

​
标志

标志行为
--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 服务器及其工具会自动列在代理的系统提示中，并按服务器名称和传输类型分组。这有助于模型推理工具来源和故障域，而无需手动上下文。

​
故障排除

确认 CLI 之外命令是否正常工作：
npx -y @modelcontextprotocol/server-filesystem /tmp
常见原因：包未安装、npx 不在 PATH 中，或缺少必需的环境变量。
确认远程服务器是否运行且 URL 是否正确。如果服务器需要身份验证，请确保 headers 包含正确的凭据。
CLI 在启动时打印加载的工具数量（例如，✓ 加载了 3 个 MCP 工具）。如果您看到 0，则服务器已成功启动但没有广告任何工具—检查服务器自己的日志或文档。

​
进一步阅读

  • LangChain MCP 指南：协议细节、构建自定义服务器和使用 langchain-mcp-adapters 程序化地
  • MCP 规范：官方协议规范和服务注册表
在 GitHub 上编辑此页面：编辑此页 或 提交问题。
通过 MCP 将这些文档连接到 Claude、VSCode 等，以实现实时答案。