MCP 工具

为什么需要它

你的 Agent 能力有限——想接数据库、调用 API、操作文件系统怎么办？

快速入门

三步配置：创建文件、添加服务器、启动——就这么简单

# 创建用户级配置目录和文件
mkdir -p ~/.deepagents
touch ~/.deepagents/.mcp.json

# 在项目根目录创建配置文件
touch .mcp.json

# 或隐藏在 .deepagents 子目录中
mkdir -p .deepagents
touch .deepagents/.mcp.json

配置示例

一个 JSON 文件搞定——声明服务器名称、类型和连接参数

{
    "mcpServers": {
        "docs-langchain": {           // 服务器名称（需匹配 [A-Za-z0-9_-]+）
            "type": "http",          // 传输类型：http / sse / stdio（默认）
            "url": "https://docs.langchain.com/mcp"  // 远程 MCP 服务器端点
        }
    }
}

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

启动 Deep Agents Code 后，会看到确认信息：

✓ Loaded 3 MCP tools

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

自动发现机制

Deep Agents Code 自动搜索标准位置的配置文件，无需任何命令行标志

配置格式

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

stdio 服务器（默认）

作为子进程启动，通过 stdin/stdout 通信——最常用的本地服务器类型

{
  "mcpServers": {
    "filesystem": {               // 服务器名称
      "command": "npx",          // 启动子进程的可执行文件
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],  // 允许访问 /tmp 目录
      "env": {}                   // 无额外环境变量
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],  // GitHub MCP 官方服务器
      "env": { "GITHUB_TOKEN": "your-token" }  // 通过 env 安全传递 API 密钥
    }
  }
}

字段参考

远程服务器

SSE 和 HTTP 两种远程传输方式——连接云端 MCP 服务

{
  "mcpServers": {
    "remote-api": {
      "type": "sse",              // Server-Sent Events 传输方式
      "url": "https://api.example.com/mcp",  // 远程 MCP 端点
      "headers": { "Authorization": "Bearer your-token" }  // 每次请求携带认证头
    }
  }
}

字段参考

{
    "mcpServers": {
        "internal-api": {
            "type": "http",                     // 可流式传输的 HTTP 双向通信
            "url": "https://api.example.com/mcp",
            "headers": { "Authorization": "Bearer ${INTERNAL_API_TOKEN}" }  // ${} 在激活时从环境变量展开
        }
    }
}

多个服务器

配置任意数量的服务器，工具自动合并提供给 Agent

{
  "mcpServers": {
    "filesystem": {          // stdio 类型（默认，无需指定 type）
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    },
    "github": {              // stdio 类型——本地 GitHub MCP 服务器
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }  // 安全传递 GitHub Token
    },
    "database": {            // SSE 类型——远程数据库 MCP 服务器
      "type": "sse",
      "url": "https://db-mcp.internal:8080/mcp",
      "headers": { "Authorization": "Bearer ..." }
    }
  }
}

工具过滤

精细控制每个服务器暴露给 Agent 的工具范围

"allowedTools": ["read_file", "list_directory"]

"disabledTools": ["delete_repository", "delete_*_branch"]

{
  "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"]  // 黑名单：禁用危险操作（支持 glob）
    }
  }
}

OAuth 登录

需要 OAuth 的远程服务器（Slack、GitHub、Notion 等）一键认证

{
    "mcpServers": {
        "linear": {
            "type": "http",                      // HTTP 传输方式
            "url": "https://mcp.linear.app/mcp",  // Linear 官方 MCP 端点
            "auth": "oauth"                       // 使用 OAuth 认证（不能用 Authorization 头）
        }
    }
}

# 启动 OAuth 登录流程（打开浏览器授权）
dcode mcp login linear

令牌与重认证

令牌自动持久化和刷新——过期时无需重启会话

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

# 指定配置文件登录（不使用自动发现的配置）
dcode mcp login linear --config ./mcp-config.json

服务器状态

每个服务器启动后处于三种状态之一——单个失败不影响整体

项目信任机制

默认拒绝策略——防止不受信任的仓库执行任意代码或窃取密钥

# 交互模式下跳过批准提示（直接信任当前项目的 MCP 配置）
dcode --trust-project-mcp

# 非交互模式下必须显式信任，否则项目服务器会被跳过
dcode -n "run tests" --trust-project-mcp

信任存储

信任决定存储在 config.toml 中——指纹校验，配置变化自动失效

# ~/.deepagents/config.toml

[mcp]
# 每项是一条被批准的服务器定义（项目根目录 + 服务器名 + 指纹）
enabled_project_server_approvals = [
  { project_root = "/Users/you/myproject", name = "filesystem", fingerprint = "sha256:abc123..." }
]

故障排除

常见问题与解决方案——快速定位并修复 MCP 配置问题

# 手动测试 stdio 服务器是否能在 Deep Agents Code 外正常运行
npx -y @modelcontextprotocol/server-filesystem /tmp

本章回顾

MCP 工具让 Deep Agents Code 的能力边界变得无限可扩展

延伸阅读