跳到主要内容

文档索引

在以下地址获取完整的文档索引：https://docs.langchain.org.cn/llms.txt

在进一步探索之前，请使用此文件发现所有可用页面。

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

​
快速入门

创建配置文件

在项目根目录创建 .mcp.json 文件。其格式遵循 Claude Desktop 约定
.mcp.json
{
    "mcpServers": {
        "docs-langchain": {
        "type": "http",
        "url": "https://docs.langchain.org.cn/mcp"
        }
    }
}

启动 CLI

deepagents
启动时，CLI 会自动发现您的 .mcp.json 文件，启动每个配置的服务器，发现其工具，并打印确认信息。
✓ Loaded 3 MCP tools
代理现在可以在会话期间使用这些工具。会话将保持活动状态——stdio 服务器在工具调用之间不会重新启动。

​
自动发现

CLI 会自动在标准位置搜索 .mcp.json 文件。无需任何标志——只需放置一个配置文件即可被识别。

​
发现位置

配置文件按此顺序检查（优先级从低到高）
优先级位置范围
1（最低）~/.deepagents/.mcp.json用户级别——适用于所有项目
2<项目>/.deepagents/.mcp.json项目级别——.deepagents 子目录
3（最高）<项目>/.mcp.json项目级别——根目录（Claude Code 兼容）
项目根目录是包含 .git 文件夹的最近父目录，如果不存在则回退到当前工作目录。 当存在多个配置文件时，它们的 mcpServers 条目会被合并。如果同一个服务器名称出现在多个文件中，则优先级更高的配置获胜。

​
标志

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

​
Claude Code 兼容性

如果您在项目根目录中已经为 Claude Code 配置了 .mcp.json 文件，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" }
    }
  }
}

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

​
字段参考

必填： command。可选： args、env、以及共享的 工具过滤字段。
​
命令
字符串
必填
要运行的可执行文件。
​
参数
字符串[]
传递给命令的参数。
​
env
对象
为子进程设置的环境变量。使用此项传递 API 密钥和其他凭据，而不会在 shell 历史记录中暴露它们。
必填： type: "sse"、url。可选： headers、auth、以及共享的 工具过滤字段。
​
type
"sse"
必填
传输类型。使用 "sse" 表示 Server-Sent Events。
​
URL
字符串
必填
服务器端点 URL。
​
headers
对象
随每个请求发送的 HTTP 头。常用于身份验证。值支持对父 shell 环境变量的 ${VAR} 引用（在服务器激活时解析）。
​
auth
"oauth"
设置为 "oauth" 以使用 deepagents mcp login 驱动 OAuth 登录流程，而不是提供 Authorization 头。不能与 Authorization 头结合使用。请参阅 OAuth 登录。
必填： type: "http"、url。可选： headers、auth、以及共享的 工具过滤字段。
​
type
"http"
必填
传输类型。使用 "http" 表示可流式 HTTP。streamable_http 和 streamable-http 也被接受为别名。
​
URL
字符串
必填
服务器端点 URL。
​
headers
对象
随每个请求发送的 HTTP 头。常用于身份验证。值支持对父 shell 环境变量的 ${VAR} 引用（在服务器激活时解析）。
​
auth
"oauth"
设置为 "oauth" 以使用 deepagents mcp login 驱动 OAuth 登录流程，而不是提供 Authorization 头。不能与 Authorization 头结合使用。请参阅 OAuth 登录。
type 字段也可以写成 transport 以兼容其他 MCP 客户端。
服务器名称必须匹配 [A-Za-z0-9_-]+。这些名称用作 OAuth 令牌文件的磁盘基名，因此在加载配置时会拒绝路径分隔符和其他 shell 元字符。

​
Header 环境变量

Header 值支持从父 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 风格的全局模式（任何包含 *、? 或 [ 的条目都被视为模式）。条目会与裸 MCP 工具名称和带服务器前缀的形式 ({server}_{tool}) 进行匹配，因此两种形式都有效。 
{
  "allowedTools": ["read_file", "fs_list_*"]
}
未匹配到任何已加载工具的条目将作为警告而不是错误记录——底层 MCP 服务器可以在不同版本之间演变其工具列表，而不会破坏您的配置。
​
allowedTools
字符串[]
要保留的工具名称或 fnmatch 全局模式。此服务器的所有其他工具都将被删除。与 disabledTools 互斥。
​
disabledTools
字符串[]
要删除的工具名称或 fnmatch 全局模式。此服务器的所有其他工具都将被保留。与 allowedTools 互斥。

​
OAuth 登录

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

​
令牌存储

令牌写入到 
~/.deepagents/mcp-tokens/<server>-<sha256-16(url)>.json
<sha256-16(url)> 段是服务器 URL 的 SHA-256 的前 16 个十六进制字符。目录被锁定为 0700 模式，每个令牌文件为 0600 模式。文件包含 OAuth 访问令牌、刷新令牌和动态注册的客户端信息，所有这些都以原子方式写入的模式版本化有效负载（写入临时文件 + rename）。
将 URL 哈希到文件名中意味着指向不同 URL（例如，开发环境与生产环境）的同一服务器名称会获得独立的令牌文件，并且不会相互覆盖。

​
重新认证

当运行时刷新失败（刷新令牌过期或被撤销）时，CLI 会将服务器标记为 unauthenticated，而不是使代理崩溃。欢迎横幅会显示未认证服务器的数量，并且 /mcp 会报告每个服务器的原因。重新运行 deepagents mcp login <server> 以刷新凭据——您的对话将继续而无需重新启动。

​
服务器状态

每个配置的服务器在启动后会处于三种状态之一：
状态含义
ok已连接；工具已加载并可供代理使用
unauthenticated需要 OAuth 登录或刷新失败 — 运行 deepagents mcp login <server>
错误预检、发现或传输设置失败；附带一条错误消息
单个服务器故障不再中止启动。代理会使用所有正常启动的服务器运行，欢迎横幅会显示未认证和出错服务器的数量，以及工具数量。在交互式会话中打开 /mcp 可查看每个服务器的状态、传输、工具列表以及非 ok 条目的失败原因。查看器会在服务器连接时实时更新，并支持 tab/shift+tab 导航。

​
项目级别信任

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

​
工作原理

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

​
标志

标志行为
--trust-project-mcp信任所有项目级别 stdio 服务器，无需提示（用于 CI 和自动化）
# Skip the approval prompt
deepagents --trust-project-mcp

# Non-interactive: explicitly trust project servers
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 在启动时会打印加载的工具数量（例如，✓ Loaded 3 MCP tools）。如果您看到 0，则表示服务器已成功启动但未公布任何工具——请检查服务器自身的日志或文档。
您要么尚未运行 deepagents mcp login <server>，要么持久化的刷新令牌已过期或在服务器端被撤销。请再次运行登录命令——您的会话将继续运行，并且一旦令牌刷新，服务器将重新连接。
预检验证拒绝了 --mcp-config（或自动发现的 .mcp.json）。常见原因：不支持的服务器名称（必须匹配 [A-Za-z0-9_-]+），stdio 服务器上的 auth: oauth，同一条目上同时设置了 command 和 url，或者不是字符串的头部值。修复突出显示的原因并重新启动——CLI 不再为配置错误转储多页子进程跟踪。
头部插值在激活时运行，因此未设置的变量只会导致需要它的服务器失败。在父 shell 中导出该变量或将其添加到 ~/.deepagents/.env。要进行调试，请设置 DEEPAGENTS_CLI_DEBUG=1 并在关闭时检查打印到 stderr 的每个会话日志路径。

​
延伸阅读

  • LangChain MCP 指南：协议详情、构建自定义服务器以及以编程方式使用 langchain-mcp-adapters
  • MCP 规范：官方协议规范和服务器注册表
将这些文档连接到 Claude、VSCode 等，以获得实时答案。
在 GitHub 上编辑此页面 或 提交问题。
© . This site is unofficial and not affiliated with LangChain, Inc.