企业官网建设流程全解析

dcode 如何配置 MCP 服务器并通过 dcode mcp login 完成远程 OAuth 认证？

【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents

在 dcode（deepagents 仓库libs/code中的终端编码 agent）里接入一个需要 OAuth 认证的远程 MCP 服务器（例如 Notion 的https://mcp.notion.com/mcp）时，需要完成两件事：在 MCP 配置文件里正确声明该服务器，以及运行dcode mcp login <server>完成远程 OAuth 握手。本文给出这条从配置到登录成功、再到工具可用的完整路径，以及登录失败时的排查依据。前提是已安装 dcode；仓库提供的安装方式为：

curl -LsSf https://langch.in/dcode | bash dcode

编写 MCP 配置文件

MCP 文档是一个包含mcpServers对象的 JSON。每个服务器条目可声明type或transport：配置了url而省略 transport 时按http处理，否则按stdio处理。dcode 接受stdio、http、sse，并把streamable_http、streamable-http归一化为http。远程服务器必须有url，stdio 服务器必须有command；args、env和远程headers均受支持。

dcode CLI 帮助界面内置的远程 OAuth 服务器示例如下（来自 ui.py 中的dcode mcp login --help输出），可直接作为模板，把服务器名和 URL 换成你的目标：

{ "mcpServers": { "notion": { "transport": "http", "url": "https://mcp.notion.com/mcp", "auth": "oauth" } } }

字段规则要点（详见 MCP Integration 与 mcp_config.py）：

• auth: oauth是远程认证选项，不能与静态Authorizationheader 同时使用；且静态Authorizationheader 的优先级高于已存储的 OAuth 凭据，配置了静态 header 时不会走 OAuth。
• command、url、args、env、headers字段中支持${VAR}与${VAR:-default}环境变量引用。变量未设置且无默认值、或${...}写法不合法时是报错，而不是静默产生一个错误的端点或密钥。
• allowedTools与disabledTools是互斥的非空 glob 列表，用于过滤该服务器暴露的工具。

配置文件放在哪里：三个自动发现路径

dcode 按以下顺序（从低到高优先级）自动发现配置文件，dcode mcp config会打印这些路径并标记哪些在磁盘上存在（来自 mcp_tools.py 的MCP_CONFIG_DISCOVERY_PATHS与 client/commands/mcp.py 的run_mcp_config）：

1. 用户级：当前 profile 的~/.deepagents/.mcp.json；
2. 项目子目录：<project-root>/.deepagents/.mcp.json；
3. 项目根：<project-root>/.mcp.json。

其中<project-root>定义为最近的含.git的祖先目录，否则就是当前目录。任何子命令上都可用--mcp-config <path>显式指定一个文件，绕过发现机制；dcode mcp login <server>同样支持该参数：

dcode mcp config # 查看发现路径 dcode mcp login linear --mcp-config ./mcp-config.json

两个信任边界需要注意，它们决定你的服务器定义能否参与登录和加载：

• 用户级配置（profile 下那个.mcp.json）始终被视为可信来源；
• 项目级.mcp.json是不受信的：除非本次调用设置了--trust-project-mcp，或该服务器在用户级信任策略中有匹配项目根与服务器指纹的批准，否则会被跳过。这样做的目的是防止克隆下来的仓库里的headers等字段在 OAuth 握手时外带本地机密。

所以最稳妥的主路径是：把需要 OAuth 的远程服务器写在用户级~/.deepagents/.mcp.json，或者用--mcp-config指向自己维护的文件。

执行 dcode mcp login 完成 OAuth 认证

dcode mcp login不带参数时，列出所有已配置auth: oauth但尚无本地 token 的服务器；带服务器名时对该服务器执行登录流程（命令定义见 client/commands/mcp.py）：

dcode mcp login # 列出需要登录的 OAuth 服务器 dcode mcp login notion # 对 notion 这个服务器执行 OAuth 登录

登录流程的行为（依据 mcp_auth.py 的login()与 MCP Integration）：

• 只支持远程http/sse传输；对 stdio 服务器会直接报错（错误信息形如 “OAuth login is only valid for http/sse”）。
• 认证采用 RFC 9728 的发现式登录，因此即使配置里没写auth: oauth，只要远端以 401 Bearer protected-resource challenge 应答，dcode 也会把该服务器标记为unauthenticated并提示dcode mcp login <server>，登录流程同样适用。
• 有浏览器可用时通过webbrowser打开授权页完成 loopback 回调；无浏览器的环境（headless/SSH）会退化为打印授权 URL 由你手动完成，无法打开浏览器时流程会以“No browser is available to complete the OAuth flow.”失败。
• 成功后 token 独立于配置存放：位于所选 profile 状态目录下的mcp-tokens子目录，文件名由校验过的服务器名加上解析后 URL 的哈希组成，同名的不同端点因此不会互相覆盖。
• 重新授权失败时不会丢弃之前存储的有效凭据。

退出码与失败信息

dcode mcp login的退出码约定（来自 client/commands/mcp.py 的 docstring）：

• 0：成功，或列出登录状态时所有已配置服务器状态都确定（“部分服务器需要登录”只是提示，不算失败）；
• 1：配置或登录失败，包括未知服务器、无效服务器定义、token 存储目录不可写、环境变量插值失败等；
• 2：没有找到任何 MCP 配置文件。

几条文档中明确给出的失败处理路径：

• 提示cannot write to the MCP tokens store时，按提示检查 token 存储目录权限后重跑dcode mcp login <server>；
• 存储的 token 文件损坏时，mcp_auth的报错会指向删除该文件并重新登录（TUI 内为/mcp login <server>，终端内为dcode mcp login <server>）；
• 涉及环境变量插值的配置，失败详情会被打码，避免把解析后的密钥打印到终端。

验证登录结果并让工具生效

验证分三层，都有文档依据：

1. 登录命令本身：login()成功后输出Logged in to MCP server '<server>'（设置DEBUG时还会追加 token 保存路径）。这是 CLI 层面的成功条件。
2. 列表命令：再跑一次dcode mcp login，刚登录的服务器不再出现在 “MCP servers needing login” 列表中；全部正常时输出No MCP servers need login.，退出码为 0。
3. dcode 会话内：登录只写 token，不会自动重载当前会话的工具。启动 dcode 后，未认证的服务器状态为unauthenticated（含义是“需要先完成 OAuth 登录才能加载工具”，见 mcp_tools.py 的状态定义）；在 TUI 中用/mcp打开查看器可以看到服务器状态，/mcp login <server>可发起登录，登录后运行/mcp reconnect加载工具（app.py 中的提示语为 “Authenticated — run/mcp reconnectto load tools.” / “Run/mcp reconnectwhen ready to load the new tools.”）。

工具加载后，MCP 工具在 dcode 中以{server_name}_{tool_name}的形式命名。另外注意 operations/security.md 与 MCP Integration 的边界：信任决定“定义能否连接”，OAuth 决定“允许的远程连接如何认证”——token 不会替你批准项目级配置，信任批准也不会替端点完成认证，两者不能互相替代。

不适用与限制

• stdio 服务器不能用dcode mcp login走 OAuth，它只适用于远程http/sse目标；
• 项目级.mcp.json中的服务器未通过信任检查时，既不会出现在dcode mcp login的扫描里，也不会被登录；
• dcode 与 Talon（libs/talon）是两套独立的 MCP 集成：配置审批、凭据文件和运行时会话互不共享，Talon 的deepagents-talon mcp login与本文的dcode mcp login不通用；
• --no-mcp会整体禁用 MCP 加载，--mcp-config优先级最高并在普通会话中做预校验，这两项开关见 Run a dcode Session。

完成登录后，下一步就是在 dcode 会话里用/mcp reconnect确认目标服务器从unauthenticated变为已加载，随后直接调用其工具验证功能是否可用。

【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents