MCP tools - Docs by LangChain中文

MCP (Model Context Protocol) 允许你用来自 external servers 的 tools 扩展 Deep Agents Code，例如 file systems、APIs、databases 等，而无需修改 agent 本身。Deep Agents Code 会在 startup 时连接到 MCP servers、发现它们的 tools，并将这些 tools 与 built-in tools 一起提供给 agent。通过向 project 添加 .mcp.json config file 可按 project-level scope 添加 MCP servers，或者在 user-level 添加以应用到所有 projects。

快速开始

此 quickstart 会将 LangChain documentation MCP server 添加到此机器上的每个 Deep Agents Code session。你可以用相同结构替换成任何其他 MCP server 的 URL 或 stdio command。

创建 config file

如果尚不存在，请在 user-level 创建 .mcp.json file，让 server 可用于机器上的每个 project，或在 project-level 创建。

User
Project
Project (hidden)

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

此 file（~/.deepagents/.mcp.json）中的 servers 可用于此机器上的每个 project。

touch .mcp.json

此 file（<project>/.mcp.json）中的 servers 可用于此 project。

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

此 file（<project>/.deepagents/.mcp.json）中的 servers 可用于此 project，但会保留在 repo root 之外。

完整 precedence rules 请参阅 Discovery locations。

添加 MCP server

~/.deepagents/.mcp.json

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

若要添加更多 servers，请向 mcpServers 添加更多 entries。有关 OAuth、stdio、SSE 和 HTTP server fields、environment variables，以及 headers，请参阅 Configuration format。

启动 Deep Agents Code

dcode

启动时，Deep Agents Code 会 auto-discover config，连接到每个 server，发现其 tools，并打印确认信息：

✓ Loaded 3 MCP tools

在 interactive session 中运行 /mcp，可查看 per-server status、transport 和 loaded tool list。Agent 现在可以在 session 期间使用这些 tools，stdio servers 会在 tool calls 之间保持运行。

Auto-discovery

Deep Agents Code 会自动在标准位置搜索 .mcp.json files。无需 flags，只需放置 config file，它就会被拾取。

Discovery locations

Configs 按以下顺序检查（从最低到最高 precedence）：

Priority	Location	Scope
1（最低）	`~/.deepagents/.mcp.json`	User-level，适用于所有 projects
2	`<project>/.deepagents/.mcp.json`	Project-level，`.deepagents` subdirectory
3（最高）	`<project>/.mcp.json`	Project-level，root（Claude Code compatible）

Project root 是包含 .git folder 的最近父 directory，如果找不到则回退到 current working directory。当存在多个 config files 时，它们的 mcpServers entries 会合并。如果同一 server name 出现在多个 file 中，higher-precedence config 胜出。这允许 project-level config 覆盖 user-level entry（例如 pin 同一 server 的不同版本），且不会影响其他 projects。

Flags

Flag	Behavior
`--mcp-config PATH`	添加 explicit config 作为 highest-precedence source（merge 到 auto-discovered configs 之上）
`--no-mcp`	完全禁用 MCP，不加载任何 servers

--mcp-config 和 --no-mcp 互斥。

Claude Code compatibility

如果 project root 已有用于 Claude Code 的 .mcp.json，Deep Agents Code 会自动拾取它，无需额外 setup。

Configuration format

mcpServers 下的每个 key 都是 server name。Server fields 决定 Deep Agents Code 如何连接到它。

stdio servers（default）

stdio servers 会作为 child processes 启动。Deep Agents Code 通过 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 servers

对于 remote MCP servers，将 type 设置为 "sse" 或 "http"，并提供 url：

mcp-config.json

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

Field reference

stdio (default)

Required: command。Optional: args、env，以及共享的 tool-filter fields。

command

string

required

要运行的 executable。

args

string[]

传给 command 的 arguments。

env

object

为 subprocess 设置的 environment variables。使用它传递 API keys 和其他 credentials，可避免将其暴露在 shell history 中。

sse

Required: type: "sse"、url。Optional: headers、auth，以及共享的 tool-filter fields。

type

"sse"

required

Transport type。对 Server-Sent Events 使用 "sse"。

url

string

required

Server endpoint URL。

headers

object

随每个 request 发送的 HTTP headers。通常用于 authentication。Values 支持对 parent-shell environment variables 的 ${VAR} references（在 server 激活时解析）。

auth

"oauth"

设置为 "oauth"，即可通过 dcode mcp login 驱动 OAuth login flow，而不是提供 Authorization header。不能与 Authorization header 组合使用。请参阅 OAuth login。

http

Required: type: "http"、url。Optional: headers、auth，以及共享的 tool-filter fields。

type

"http"

required

Transport type。对 streamable HTTP 使用 "http"。streamable_http 和 streamable-http 可作为 aliases。

url

string

required

Server endpoint URL。

headers

object

随每个 request 发送的 HTTP headers。通常用于 authentication。Values 支持对 parent-shell environment variables 的 ${VAR} references（在 server 激活时解析）。

auth

"oauth"

设置为 "oauth"，即可通过 dcode mcp login 驱动 OAuth login flow，而不是提供 Authorization header。不能与 Authorization header 组合使用。请参阅 OAuth login。

为了兼容其他 MCP clients，type field 也可以写作 transport。

Server names 必须匹配 [A-Za-z0-9_-]+。Names 会作为 OAuth token files 的 on-disk basenames，因此 path separators 和其他 shell metacharacters 会在 config load 时被拒绝。

Header environment variables

Header values 支持来自 parent shell 的 ${VAR} substitution，并在 server activation 时解析，而不是在 config load 时解析。某个 unset variable 只会导致需要它的 server 失败，其他 servers 仍会启动。

.mcp.json

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

Multiple servers

你可以按需配置任意数量的 servers。来自所有 servers 的 tools 会合并，并提供给 agent：

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

Tool filtering

每个 server 都可以使用两个 optional fields 之一，缩小它暴露给 agent 的 tools 范围：

allowedTools：仅保留列出的 tools，丢弃其他所有 tools。
disabledTools：丢弃列出的 tools，保留其他所有 tools。

Filtering 同样适用于 stdio、HTTP 和 SSE servers。以下两种情况都会在 config load 时被拒绝：

在同一 server 上同时设置 allowedTools 和 disabledTools。
将任一 field 设置为空 list（会静默移除所有 tools，或成为 no-op）。请改为省略该 field。

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

Match rules

每个 entry 都是 literal tool name 或 fnmatch-style glob（任何包含 *、? 或 [ 的 entry 都视为 pattern）。Entries 会同时匹配 bare MCP tool name 和 server-prefixed form（{server}_{tool}），因此两种形式都可用：

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

没有匹配任何 loaded tool 的 entries 会记录为 warning，而不是 error。这样底层 MCP server 可以跨版本演进 tool list，而不会破坏你的 config。

allowedTools

string[]

要保留的 tool names 或 fnmatch glob patterns。此 server 的其他所有 tools 都会被丢弃。与 disabledTools 互斥。

disabledTools

string[]

要丢弃的 tool names 或 fnmatch glob patterns。此 server 的其他所有 tools 都会保留。与 allowedTools 互斥。

对于需要 OAuth 的 remote MCP servers（Slack、GitHub、Notion、Linear 和其他 hosted MCP endpoints），请在 server entry 上设置 "auth": "oauth"，并运行一次 login subcommand。Tokens 会持久化到 disk，并自动 refresh。

配置 server

.mcp.json

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

auth: "oauth" 与同一 entry 上的 Authorization header 互斥，并且不能设置在 stdio server 上。若要将 Deep Agents Code 连接到 LangSmith，请使用 LangSmith Remote MCP：

.mcp.json

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

dcode mcp login linear

具体行为取决于 server host：

Spec-compliant servers（默认）：Deep Agents Code 执行 Dynamic Client Registration，在 browser 中打开 Authorization Code + PKCE flow，并要求你将 redirected URL 粘贴回 terminal。
Slack（slack.com、*.slack.com）：使用相同的 paste-back flow，但预置 Slack public client。系统会提示你输入可选 team ID（例如 T01234567），以便 app 安装到正确 workspace。
GitHub（api.githubcopilot.com）：RFC 8628 Device Authorization Grant。Deep Agents Code 会打印 verification URL 和 user code；你在 browser 中输入 code，Deep Agents Code 会轮询完成状态。

默认情况下，dcode mcp login 会读取 Deep Agents Code 在 runtime 使用的同一组 auto-discovered configs（受 project-level trust gating 约束）。传入 --config <path> 可使用特定 file：

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

尚未 trust 的 project-level configs（请参阅 Project-level trust）会在 mcp login 期间被跳过，以防 attacker-controlled headers entries 通过 ${VAR} interpolation 外泄 local secrets。请在 project 中运行一次 dcode 来 approve config，或显式传入 --config <path>。

Token storage

Tokens 会写入：

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

<sha256-16(url)> segment 是 server URL 的 SHA-256 前 16 个 hex characters。该 directory 被锁定为 mode 0700，每个 token file 为 mode 0600。Files 包含 OAuth access token、refresh token 和 dynamically registered client info，全部位于带 schema version 的 payload 中，并以原子方式写入（write-to-temp + rename）。

将 URL hash 到 filename 意味着指向不同 URLs（例如 dev vs. prod）的同一 server name 会获得独立 token files，彼此不会覆盖。

Re-authentication

当 runtime refresh 失败（refresh token 过期或被 revoke）时，Deep Agents Code 会将 server 标记为 unauthenticated，而不是让 agent 崩溃。Welcome banner 会显示 unauthenticated servers 数量，/mcp 会按 server 报告原因。重新运行 dcode mcp login <server> 可刷新 credentials，你的 conversation 会继续，无需 restart。

Server status

每个已配置 server 在 startup 后都会处于以下三种 states 之一：

Status	Meaning
`ok`	已连接；tools 已加载并可供 agent 使用
`unauthenticated`	需要 OAuth login 或 refresh 失败，请运行 `dcode mcp login <server>`
`error`	Pre-flight、discovery 或 transport setup 失败；附带 error message

单个 server 失败不会再中止 startup。Agent 会使用成功启动的 servers 运行，welcome banner 会在 tool count 旁显示 unauthenticated 和 errored servers 的数量。在 interactive session 中打开 /mcp，可查看 per-server status、transport、tool list，以及非 ok entries 的 failure reason。Viewer 会随 servers 连接实时更新，并支持 tab/shift+tab navigation。

Project-level trust

Project-level configs 可以包含执行 local commands 的 stdio servers，以及其 headers 可能从你的 environment interpolates ${VAR} 的 remote servers。为防止 untrusted repositories 在 CLI startup 时运行任意 code 或外泄 local secrets，Deep Agents Code 对 project-level entries 强制执行 default-deny policy。

工作方式

Interactive mode： Deep Agents Code 会在激活 project servers 前提示 approval，显示每个 stdio command 和 remote URL。Approval 使用 SHA-256 content fingerprint 持久化；如果 config 改变，会再次提示你。
Non-interactive mode（-n）： 除非传入 --trust-project-mcp，否则会静默跳过 project servers。
Trust 同时覆盖 stdio 和 remote entries：remote servers 可在 pre-flight probe 期间 SSRF 到 localhost 或 cloud-metadata endpoints，并通过 headers 外泄 ${VAR} values，因此它们与 stdio 使用相同 gating。
User-level configs（~/.deepagents/.mcp.json）始终 trusted，与 config.toml 和 hooks.json 采用相同 trust model。
dcode mcp login 也遵守 project trust：login discovery 期间会跳过 untrusted project-level config，因此 attacker-controlled remote entry 无法将 secrets 拉入 OAuth handshake。

Flags

Flag	Behavior
`--trust-project-mcp`	不提示即 trust 所有 project-level stdio servers（用于 CI 和 automation）

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

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

Trust store

Trust decisions 存储在 ~/.deepagents/.state/mcp_trust.json 中：

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

projects 下的每个 key 都是 absolute project root path。Value 是拼接后的 project-level config contents 的 SHA-256 digest。若要 revoke trust，请删除该 entry，或修改 project 的 .mcp.json（这会自动使 fingerprint 失效）。

Trusted stdio MCP server 拥有与你的 user account 相同的权限。仅 approve 来自可信 repositories 的 servers。接受前，请审查 approval prompt 中显示的 commands。

System prompt awareness

Connected MCP servers 及其 tools 会自动列入 agent system prompt，并按 server name 和 transport type 分组。这有助于 model 推理 tool provenance 和 failure domains，而无需 manual context。

Troubleshooting

Server fails to start (stdio)

验证 command 在 Deep Agents Code 外部也能工作：

npx -y @modelcontextprotocol/server-filesystem /tmp

常见原因：package 未安装、npx 不在 PATH 中，或缺少 required environment variables。

Connection refused (SSE/HTTP)

检查 remote server 是否正在运行，以及 URL 是否正确。如果 server 需要 authentication，请确保 headers 包含正确 credentials。

Tools not appearing

Deep Agents Code 会在 startup 时打印 loaded tools 数量（例如 ✓ Loaded 3 MCP tools）。如果看到 0，说明 server 成功启动，但未 advertise 任何 tools，请检查 server 自身 logs 或 documentation。

Server shows `unauthenticated` in /mcp

要么你尚未运行 dcode mcp login <server>，要么 persisted refresh token 已过期或在 server-side 被 revoke。再次运行 login command，你的 session 会继续运行，tokens 刷新后 server 会重新 attach。

`Invalid MCP config at ...`

Pre-flight validation 拒绝了 --mcp-config（或 auto-discovered .mcp.json）。常见原因包括 unsupported server name（必须匹配 [A-Za-z0-9_-]+）、在 stdio server 上设置 auth: oauth、同一 entry 同时设置 command 和 url，或 header value 不是 string。修复高亮原因并重新启动，Deep Agents Code 不再针对 config errors 输出多页 subprocess trace。

`${VAR}` header references fail

Header interpolation 在 activation time 运行，因此 unset variable 只会导致需要它的 server 失败。请在 parent shell 中 export 该 variable，或将其添加到 ~/.deepagents/.env。若要 debug，请设置 DEEPAGENTS_CODE_DEBUG=1，并检查 shutdown 时打印到 stderr 的 per-session log path。

进一步阅读

LangSmith Remote MCP：通过 OAuth 将 Deep Agents Code 连接到 LangSmith tools
LangChain MCP guide：protocol details、构建 custom servers，以及以编程方式使用 langchain-mcp-adapters
MCP specification：official protocol spec 和 server registry

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

​快速开始

​Auto-discovery

​Discovery locations

​Flags

​Claude Code compatibility

​Configuration format

​stdio servers（default）

​SSE 和 HTTP servers

​Field reference

​Header environment variables

​Multiple servers

​Tool filtering

​Match rules

​OAuth login

​配置 server

​运行 login flow

​Token storage

​Re-authentication

​Server status

​Project-level trust

​工作方式

​Flags

​Trust store

​System prompt awareness

​Troubleshooting

​进一步阅读

快速开始

Auto-discovery

Discovery locations

Flags

Claude Code compatibility

Configuration format

stdio servers（default）

SSE 和 HTTP servers

Field reference

Header environment variables

Multiple servers

Tool filtering

Match rules

OAuth login

配置 server

运行 login flow

Token storage

Re-authentication

Server status

Project-level trust

工作方式

Flags

Trust store

System prompt awareness

Troubleshooting

进一步阅读