> ## Documentation Index
> Fetch the complete documentation index at: https://nvd-54.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 工具

> 从 MCP（模型上下文协议）服务器加载额外工具

[MCP（模型上下文协议）](https://modelcontextprotocol.io/)让你可以使用来自外部服务器的工具扩展深度智能体 CLI — 文件系统、API、数据库等 — 无需修改智能体本身。CLI 在启动时连接到 MCP 服务器，发现其工具，并使它们与内置工具一起可供智能体使用。

通过编辑 `.mcp.json` 配置文件添加 MCP 服务器：在你的项目中添加用于项目级范围，或在用户级添加以应用于所有项目。

## 快速开始

本快速开始将 [LangChain 文档 MCP 服务器](https://docs.langchain.com/mcp)添加到你机器上的每个深度智能体 CLI 会话。你可以用任何其他 MCP 服务器的 URL 或 stdio 命令替换。

<Steps>
  <Step title="创建配置文件" icon="file">
    如果尚未存在，在用户级创建 `.mcp.json` 文件以使服务器对机器上的每个项目可用，或在项目级创建。

    <Tabs>
      <Tab title="用户">
        ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        mkdir -p ~/.deepagents
        touch ~/.deepagents/.mcp.json
        ```

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

      <Tab title="项目">
        ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        touch .mcp.json
        ```

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

      <Tab title="项目（隐藏）">
        ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
        mkdir -p .deepagents
        touch .deepagents/.mcp.json
        ```

        此文件（`<project>/.deepagents/.mcp.json`）中的服务器对此项目可用，但保持在仓库根目录之外。
      </Tab>
    </Tabs>

    参见[发现位置](#discovery-locations)了解完整优先级规则。
  </Step>

  <Step title="添加 MCP 服务器" icon="plug">
    ```json title="~/.deepagents/.mcp.json" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
        "mcpServers": {
            "docs-langchain": {
                "type": "http",
                "url": "https://docs.langchain.com/mcp"
            }
        }
    }
    ```

    要添加更多服务器，在 `mcpServers` 中添加更多条目。参见[配置格式](#configuration-format)了解 OAuth、stdio、SSE 和 HTTP 服务器字段、环境变量和头部。
  </Step>

  <Step title="启动 CLI" icon="terminal">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    deepagents
    ```

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

    ```
    ✓ Loaded 3 MCP tools
    ```

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

## 自动发现

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

<Note>
  `--mcp-config` 和 `--no-mcp` 互斥。
</Note>

### Claude Code 兼容性

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

## 配置格式

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

### stdio 服务器（默认）

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

```json title="mcp-config.json" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "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 title="mcp-config.json" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "mcpServers": {
    "remote-api": {
      "type": "sse",
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}
```

### 字段参考

<AccordionGroup>
  <Accordion title="stdio（默认）">
    **必需：** `command`。**可选：** `args`、`env`，加上共享的[工具过滤字段](#tool-filtering)。

    <ResponseField name="command" type="string" required>
      要运行的可执行文件。
    </ResponseField>

    <ResponseField name="args" type="string[]">
      传递给命令的参数。
    </ResponseField>

    <ResponseField name="env" type="object">
      为子进程设置的环境变量。使用此项传递 API 密钥和其他凭证，而不在 shell 历史中暴露它们。
    </ResponseField>
  </Accordion>

  <Accordion title="sse">
    **必需：** `type: "sse"`、`url`。**可选：** `headers`、`auth`，加上共享的[工具过滤字段](#tool-filtering)。

    <ResponseField name="type" type="&#x22;sse&#x22;" required>
      传输类型。对于 Server-Sent Events 使用 `"sse"`。
    </ResponseField>

    <ResponseField name="url" type="string" required>
      服务器端点 URL。
    </ResponseField>

    <ResponseField name="headers" type="object">
      随每个请求发送的 HTTP 头。通常用于认证。值支持 `${VAR}` 引用父 shell 环境变量（在服务器激活时解析）。
    </ResponseField>

    <ResponseField name="auth" type="&#x22;oauth&#x22;">
      设为 `"oauth"` 以使用 `deepagents mcp login` 驱动 OAuth 登录流程，而不提供 `Authorization` 头。不能与 `Authorization` 头组合。参见 [OAuth 登录](#oauth-login)。
    </ResponseField>
  </Accordion>

  <Accordion title="http">
    **必需：** `type: "http"`、`url`。**可选：** `headers`、`auth`，加上共享的[工具过滤字段](#tool-filtering)。

    <ResponseField name="type" type="&#x22;http&#x22;" required>
      传输类型。对于可流式 HTTP 使用 `"http"`。`streamable_http` 和 `streamable-http` 作为别名接受。
    </ResponseField>

    <ResponseField name="url" type="string" required>
      服务器端点 URL。
    </ResponseField>

    <ResponseField name="headers" type="object">
      随每个请求发送的 HTTP 头。通常用于认证。值支持 `${VAR}` 引用父 shell 环境变量（在服务器激活时解析）。
    </ResponseField>

    <ResponseField name="auth" type="&#x22;oauth&#x22;">
      设为 `"oauth"` 以使用 `deepagents mcp login` 驱动 OAuth 登录流程，而不提供 `Authorization` 头。不能与 `Authorization` 头组合。参见 [OAuth 登录](#oauth-login)。
    </ResponseField>
  </Accordion>
</AccordionGroup>

<Note>
  `type` 字段也可以写为 `transport` 以兼容其他 MCP 客户端。
</Note>

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

### 头部环境变量

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

```json title=".mcp.json" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
    "mcpServers": {
        "internal-api": {
            "type": "http",
            "url": "https://api.example.com/mcp",
            "headers": { "Authorization": "Bearer ${INTERNAL_API_TOKEN}" }
        }
    }
}
```

## 多个服务器

你可以配置任意数量的服务器。所有服务器的工具合并后可供智能体使用：

```json title="mcp-config.json" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "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 title=".mcp.json" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "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`](https://docs.python.org/3/library/fnmatch.html) 风格的通配符（任何包含 `*`、`?` 或 `[` 的条目被视为模式）。条目与裸 MCP 工具名称和服务器前缀形式（`{server}_{tool}`）都进行匹配，因此两种形式都有效：

```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "allowedTools": ["read_file", "fs_list_*"]
}
```

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

<ResponseField name="allowedTools" type="string[]">
  要保留的工具名称或 `fnmatch` 通配符模式。此服务器的所有其他工具被删除。与 `disabledTools` 互斥。
</ResponseField>

<ResponseField name="disabledTools" type="string[]">
  要删除的工具名称或 `fnmatch` 通配符模式。此服务器的所有其他工具被保留。与 `allowedTools` 互斥。
</ResponseField>

## OAuth 登录

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

<Note>
  OAuth 登录需要 `deepagents-cli>=0.0.46`。
</Note>

### 配置服务器

```json title=".mcp.json" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
    "mcpServers": {
        "linear": {
            "type": "http",
            "url": "https://mcp.linear.app/mcp",
            "auth": "oauth"
        }
    }
}
```

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

### 运行登录流程

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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>` 使用特定文件：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
deepagents mcp login linear --config ./mcp-config.json
```

<Warning>
  未被信任的项目级配置（参见[项目级信任](#project-level-trust)）在 `mcp login` 期间被跳过，以防止攻击者控制的 `headers` 条目通过 `${VAR}` 插值泄露本地密钥。在项目中运行一次 `deepagents` 以批准配置，或显式传递 `--config <path>`。
</Warning>

### 令牌存储

令牌写入到：

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
~/.deepagents/.state/mcp-tokens/<server>-<sha256-16(url)>.json
```

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

<Note>
  将 URL 哈希到文件名中意味着指向不同 URL 的同名服务器（例如开发环境 vs 生产环境）获得独立的令牌文件，不会互相覆盖。
</Note>

### 重新认证

当刷新在运行时失败（刷新令牌过期或被撤销）时，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 和自动化） |

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 跳过批准提示
deepagents --trust-project-mcp

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

### 信任存储

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

```toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[mcp_trust.projects]
"/Users/you/myproject" = "sha256:abc123..."
```

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

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

## 系统提示感知

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

## 故障排除

<AccordionGroup>
  <Accordion title="服务器启动失败（stdio）">
    验证命令在 CLI 外工作：

    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    npx -y @modelcontextprotocol/server-filesystem /tmp
    ```

    常见原因：包未安装、`npx` 不在 `PATH` 中，或缺少所需的环境变量。
  </Accordion>

  <Accordion title="连接被拒绝（SSE/HTTP）">
    检查远程服务器是否正在运行且 URL 是否正确。如果服务器需要认证，确保 `headers` 包含正确的凭证。
  </Accordion>

  <Accordion title="工具未出现">
    CLI 在启动时打印加载的工具数量（例如 `✓ Loaded 3 MCP tools`）。如果你看到 `0`，说明服务器成功启动但未通告任何工具 — 检查服务器自己的日志或文档。
  </Accordion>

  <Accordion title="服务器在 /mcp 中显示 `unauthenticated`">
    你尚未运行 `deepagents mcp login <server>`，或持久化的刷新令牌已过期或在服务器端被撤销。再次运行登录命令 — 你的会话继续运行，令牌刷新后服务器将重新附加。
  </Accordion>

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

  <Accordion title="`${VAR}` 头部引用失败">
    头部插值在激活时运行，因此未设置的变量仅使需要它的服务器失败。在父 shell 中导出变量或将其添加到 `~/.deepagents/.env`。要调试，设置 `DEEPAGENTS_CLI_DEBUG=1` 并检查关闭时打印到 stderr 的每会话日志路径。
  </Accordion>
</AccordionGroup>

## 延伸阅读

* [LangChain MCP 指南](/oss/python/langchain/mcp)：协议详情、构建自定义服务器和以编程方式使用 `langchain-mcp-adapters`
* [MCP 规范](https://modelcontextprotocol.io/)：官方协议规范和服务器注册表

***

<div className="source-links">
  <Callout icon="terminal-2">
    [连接这些文档](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/cli/mcp-tools.mdx)或[提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>