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

通过添加 .mcp.json 配置文件到您的项目来实现项目级作用域，或在用户级应用以适用于所有项目。

快速入门

本快速入门添加 LangChain 文档 MCP 服务器 到您机器上的每个 Deep Agents Code 会话中。以相同格式替换任何其他 MCP 服务器的 URL 或 stdio 命令。

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

                touch .mcp.json
                

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

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

        dcode
        

        ✓ Loaded 3 MCP tools
        

Auto-discovery

Deep Agents Code 自动在标准位置搜索 .mcp.json 文件。无需任何标志，只需放置配置文件即可自动拾取。

发现位置

配置按此顺序检查（从最低优先级到最高优先级）：

项目根目录是包含 .git 文件夹的最近父目录，若无则回退到当前工作目录。

当存在多个配置文件时，它们的 mcpServers 条目会被合并。如果同一服务器名称出现在多个文件中，则优先使用优先级较高的配置。这样可以让项目级配置覆盖用户级条目（例如，固定同一服务器的不同版本）而不影响其他项目。

标志

Claude Code 兼容性

如果您已有 .mcp.json 在项目根目录用于 Claude Code，Deep Agents Code 会自动拾取它——无需额外设置。

配置格式

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

stdio 服务器（默认）

stdio servers are spawned as child processes. Deep Agents Code communicates with them over stdin/stdout.

{
  "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 to "sse" or "http" 并提供一个 url:

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

字段参考

标头环境变量

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

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

多个服务器

你可以根据需要配置任意数量的服务器。所有服务器的工具会合并并对 agent 可用：

{
  "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 ..." }
    }
  }
}

工具过滤

每个服务器可以使用两个可选字段之一来缩小向 agent 暴露的工具范围：

• - allowedTools：仅保留列出的工具；删除其他所有工具。
• - disabledTools：删除列出的工具；保留其他所有工具。

过滤适用于 stdio、HTTP 和 SSE 服务器。配置加载时会拒绝以下两种情况：

• - 设置 allowedTools 和 disabledTools 在同一服务器上。
• - 将任一字段设置为空列表（会静默删除所有工具，或变为无操作）。应改为省略该字段。

{
  "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（任何包含 *, ?, or [ 的条目都被视为模式）。条目会同时与裸 MCP 工具名称和带服务器前缀的形式（{server}_{tool}）进行匹配，因此任一形式都有效：

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

工具名称或 fnmatch glob 模式以保留。来自此服务器的其他所有工具都会被删除。与 disabledTools.

工具名称或 fnmatch glob 模式以删除。来自此服务器的其他所有工具都会被保留。与 allowedTools.

OAuth 登录

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

配置服务器

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

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

要将深度 Agent 代码连接到 LangSmith，请使用 LangSmith 远程 MCP:

{
    "mcpServers": {
        "langsmith": {
            "url": "https://api.smith.langchain.com/mcp",
            "transport": "http",
            "auth": "oauth"
        }
    }
}

运行登录流程

dcode mcp login linear

具体行为取决于服务器的主机：

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

默认情况下， dcode mcp login 读取与 Deep Agents Code 在运行时使用的相同自动发现配置（受项目级信任限制）。传递 --config <path> 以使用特定文件：

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

令牌存储

令牌写入到：

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

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

Re-authentication

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

服务器状态

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

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

项目级信任

项目级配置可以包含执行本地命令的 stdio 服务器和远程服务器，其 headers 可能会从你的环境进行插值 ${VAR} 为防止不受信任的仓库在 CLI 启动时运行任意代码或泄露本地密钥，Deep Agents Code 对项目级条目强制执行 **default-deny** 策略。

工作原理

• 交互模式： Deep Agents Code 在激活项目服务器之前提示批准，显示每个 stdio 命令和远程 URL。使用 SHA-256 内容指纹持久化批准——如果配置更改，你将再次收到提示。
• - **非交互模式（-n):** 项目服务器会被静默跳过，除非 --trust-project-mcp 已传递。
• 信任覆盖标准输入输出和远程条目 — 远程服务器可以在预检探测期间利用 SSRF 攻击访问本地主机或云元数据端点并泄露 ${VAR} 通过标头传递值，因此其受信任方式与标准输入输出相同。
• 用户级配置 (~/.deepagents/.mcp.json) 始终受信任——与以下内容采用相同的信任模型 config.toml 和 hooks.json.
• - **dcode mcp login** 还支持项目级信任：在登录发现期间会跳过不受信任的项目级配置，因此攻击者控制的远程条目无法将密钥泄露到 OAuth 握手过程中。

标志

# Skip the approval prompt
dcode --trust-project-mcp

# Non-interactive: explicitly trust project servers
dcode -n "run tests" --trust-project-mcp

信任存储

信任决策存储在 ~/.deepagents/.state/mcp_trust.json:

{
  "version": 1,
  "projects": {
    "/Users/you/myproject": "sha256:abc123..."
  }
}

每个密钥对应 projects 表示项目根目录的绝对路径。值为各项目级配置内容的 SHA-256 哈希摘要。如需撤销信任，请删除相关条目或修改项目的 .mcp.json （这会自动使指纹失效）。

系统提示感知

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

故障排除

        npx -y @modelcontextprotocol/server-filesystem /tmp
        

进一步阅读

• - LangSmith 远程 MCP：通过 OAuth 将 Deep Agents Code 连接到 LangSmith 工具
• - LangChain MCP 指南：协议详情、构建自定义服务器以及使用 langchain-mcp-adapters 以编程方式
• - MCP 规范：官方协议规范和服务器注册表