Bitget Agentic 账户 连接指南

本文是什么：Bitget Agentic 账户首次接入指南（在线文档，以前叫 Agent 子账户）。交给 AI Agent 读完后，会引导你完成「连接云端 MCP → 旧版快检 → 浏览器 OAuth 授权」的首次连接，全程不需要你手动创建或粘贴 API Key。

Agent 要做什么：读完本文后按 Step 1–5 执行：把云端 MCP https://agent.bitget.com/mcp 直接写进当前客户端的 MCP 配置，多数情况下工具会立刻在本对话可用，不必新开对话 → 做旧版快检，检测到旧版就提醒用户先处理持仓和未完成委托、升级后在授权页新建账户 → 触发客户端侧鉴权（Cursor 等客户端的 mcp_auth/Connect 动作，不是服务端 tool），打开授权窗口触发 OAuth，等用户在浏览器完成登录确认 → 用一次具体的账户类接口（如 getAccountAssets）确认云端 MCP 已记住登录态 → 给出完成提示。不要让用户手动创建或粘贴 API Key，也不要自己拼授权链接或监听回调。

之后：首次授权完成后本文使命结束。本版本不依赖安装本地 bitget-agentic skill——后续 Key 失效、重新授权、交易与风控规则，仍按本文 Step 1–5 的结论处理；本地 skill 暂缓更新，如已安装且内容与本文不一致，以本文最新结论为准。

只有用户明确说不要授权时，才不发起 OAuth。只说「先看行情」不算拒绝授权。

先看这几条

• 行情可以不登录就查。交易、账户、Reality / rToken 要 OAuth。调用前用 guide 核对，没有的接口就说明没有。标准调用链：行情 guide(surface="market_data") → 拿到入参 → do_query；交易/账户 guide(surface="open_api") → 拿到 operation_id → do_request_open_api。

• 不做：提现、主账户划到子账户、改主账户邮箱 / 手机 / 双重验证。美股直连、CFD、税务、质押借贷、机构借贷不接入。

• 新版登录态是 OAuth token，不是 API Key。一个 Agentic 账户只能授权给一个 Agent，一个 Agent 也只能接入一个 Agentic 账户——换绑（同一个 Agent 换绑新账户，或另一个 Agent 接已授权过的账户）都会替换掉原有授权（原有的监控挂单可能会失效，务必要提示给用户）

• 可以同时用多个 Agent，每个各绑一个子账户，来实现管理多个 Agent 子账户目的；想让一个 Agent 管理多个子账户，提示用户进群反馈给产品团队

• 授权窗口由云端 MCP 打开。不要自己编授权链接。

• 用户在使用过程中如果表现出明显的产品层面困惑或疑问（不是这篇文档能讲清楚的操作细节），可以提示用户进群向产品团队反馈。

Step 1 · 连接云端 MCP

不要配置 BITGET_API_*。只注册这一个 HTTP 地址：https://agent.bitget.com/mcp。

• Claude Code：claude mcp add bitget-mcp-server -s user --transport http https://agent.bitget.com/mcp（-s user 让这条注册在用户级生效，不是只在当前项目里；Claude Code 侧不需要、也没有 Cursor 那套 auth.CLIENT_ID 机制）

• Cursor：Agent 直接把下面这段配置写进 ~/.cursor/mcp.json（已有其他 server 配置时合并进去，不要整份覆盖）。不用等用户自己去设置界面手填，写完后这个工具通常会立刻出现在当前对话里（状态为待授权）

• 其他客户端：按该客户端的 HTTP MCP 方式填同一地址

{ "mcpServers": { "bitget-mcp-server": { "url": "https://agent.bitget.com/mcp", "auth": { "CLIENT_ID": "cursor" } } } }

写完配置后，先在本对话里看这条连接是否已经可用：服务端只有 guide / do_query / do_request_open_api 三个 tool，mcp_auth 不是其中之一，不要当成 tool 去 tools/call，看不到它不代表 MCP 没连上——真正的连接信号是看得到 guide 等三个 tool。多数情况下，刚写入的这条连接会立刻在本对话可用，不需要新开对话，也不用重启客户端——不要默认假设看不到。

只有确认写入配置、并在本对话里实际看过仍然看不到 guide / do_query / do_request_open_api 这三个 tool 时，才需要继续排查，不要把新开对话当成默认步骤。最常见的原因：当前客户端的 MCP 配置里还同时留着旧版本地 stdio MCP 包 @bitget-ai/bitget-agent-mcp，或手填了 API Key 的本地 MCP——旧版和新版配置技术上可能同时写在文件里、不会互相报错（软冲突），但产品设计上只认一套，旧版留在那里会挡住新连接生效，这是硬冲突，要跟用户讲清楚、引导清理，不能只说"再检查一下"。确认没有这类旧版残留、仍然看不到工具时，才新开对话。Claude Code：退出后重开 claude。Cursor：新开一个 Agent 对话。其他客户端：按其重连方式处理。新对话里发：

我已经把 https://agent.bitget.com/mcp 写进本地 MCP 配置，但这个对话里还是看不到 guide / do_query / do_request_open_api 这三个工具。请检查一下我的 MCP 配置里是不是还留着旧版本地 stdio MCP 包 @bitget-ai/bitget-agent-mcp，或手填了 API Key 的本地 MCP——如果有，这可能是挡住新连接的原因，请先告诉我要怎么清理，再帮我确认新连接能不能用。

Step 2 · 授权前快检旧版

即将 OAuth 时顺手看一眼即可——不用建状态文件，也不用跨对话记住这个结论，每次看当前客户端存放 MCP 配置的位置就行。用户明确不要授权则跳过这一步。命中下面两样之一就是旧版：

• 配置用本地 stdio 启动 @bitget-ai/bitget-agent-mcp

• 这条 MCP 配置里手填了 BITGET_API_KEY / BITGET_SECRET_KEY / BITGET_PASSPHRASE

旧版和新的云端 MCP 技术上可能同时写在配置文件里、不会互相报错（软冲突），但产品设计上只认一套——两边都留着会让调用混乱，这是硬冲突。看到旧版还在，调用时只用新版云端 MCP 的三个服务端 tool（guide / do_query / do_request_open_api），不要碰旧版 stdio MCP 的工具，也不要用旧版留下的 API Key。

不算旧版：只配置了云端地址 https://agent.bitget.com/mcp；@bitget-ai/bitget-agent-skill 是 skill。bgc、bitget-signal、它的行情 MCP、upgrade-all、不带 --skill agentic 的 UTA skill 也都不是这一步的旧版，不要拦住 OAuth，用户正要使用它们时提醒一句即可。

本机到底装过哪个 npm 包、有没有跑过 npm list / npm view，都不能拿来判断——不要联网查，也不要跑这些命令，只看上面两条配置内容。不要假设配置文件在某个固定路径，不要代用户改配置。

找不到配置位置时，不要当成没有旧版。告诉用户没查到，请用户自己确认这台电脑还有没有旧版本地 stdio MCP 包 @bitget-ai/bitget-agent-mcp，或手填 API Key 的本地 MCP。用户确认没有，就按新版流程继续；用户不确定或说还有，就给出下面的提醒。

看到旧版还在，把下面这段发给用户即可继续往 Step 3 走——不需要等用户明确回复「同意升级」才能打开授权窗口；只有用户明确说不想升级、不想处理旧版时才停下来，不发起 OAuth。

Step 3 · 打开授权窗口

触发 OAuth 有两条路径，看当前客户端支持哪种：① 客户端原生鉴权动作——Cursor 等客户端在这条 MCP 连接旁边会有「Connect」/鉴权入口（有的地方显示成 mcp_auth，但它不是服务端 tools/list 里的 tool，不能当 tool 用 tools/call 调）；② 没有这个入口时，直接调用一次私有接口，例如 do_request_open_api(operation_id="getAccountAssets", params={...})——未授权会返回 HTTP 401，客户端会据此自动弹出 OAuth 授权页，不需要 Agent 自己处理这个 401。

1. 先按上面两条路径之一触发鉴权（客户端侧 Connect 动作，或私有接口的 401）。

2. 没有弹出窗口、但返回了链接时，用当前环境打开浏览器的方式打开，不要先把链接发给用户。

3. 打不开时，才发送链接原文，并说明是因为当前环境没有打开窗口的权限。

告诉用户：即将打开浏览器完成授权，不用复制 API Key。不要改用户提示语里的 Bitget 域名。

Cursor：整段流程只触发一次客户端侧鉴权动作；不要连点 Authenticate / 重连。登录用当次打开的浏览器页。若出现「Authorization session ended」且回调链接里已经带 code，说明是旧会话作废，重新只走一轮再授权即可。

Step 4 · 网络与代理（bitget.com）

授权页和回调要访问 bitget.com。超时、ECONNREFUSED、ENOTFOUND、network、fetch failed、无法连接 bitget.com，或用户说打不开 Bitget，按网络问题处理，不要当成普通授权失败立刻重试。

1. 看当前环境里已经生效的代理，不要默认某一个端口或某一种配置文件。

2. 有代理：让 shell 或 MCP 启动环境走代理，从 Step 3 重试。

3. 没有代理：请用户打开。等用户说已经开好，再从 Step 3 重试。

4. 不要未查网络就让用户反复点允许，不要自己拼 bitget.com 链接，不要让用户手填 API Key。

Step 5 · 成功

用户在页面登录并确认。Agent 不代填密码。

已登录的标志：客户端显示该 MCP 已登录，且 do_request_open_api(operation_id="getAccountAssets", params={...}) 这类要登录的调用能通过。页面看起来走完了不算。除 getAccountAssets 外，也可用其他只读账户类 operation_id 确认（如 getDeductInfo，具体以 guide(surface="open_api") 返回的列表为准）。

后续 Key 失效、重新授权、交易规则仍按本文结论处理；不要把 token 写进任何本地文件。

用户要删掉旧版 API Key：新版账户没有 API Key，也不能在网页单独删 Key。先用 guide(surface="open_api") 找到能拿到账户名称的 operation_id 并调用，查不到就说明没查到，不要编。再用这段话，把名称填进去：

没成功

没有明确原因就不要猜，问要不要再发起一次。