Bitget Agentic Account Connection Guide

What this is: The first-time connection guide for a Bitget Agentic account (online document, formerly called Agent sub-account). Once an AI Agent reads this, it will walk you through the first connection — install the local skill → connect the cloud MCP → quick legacy check → browser OAuth — and you never need to manually create or paste an API Key.

What the Agent should do: After reading this, follow Step 0–5: download and hot-load the local bitget-agentic skill into this chat (order relative to Step 1 is flexible — both must happen in this chat) → write the cloud MCP https://agent.bitget.com/mcp directly into the current client's MCP config; in most cases the tool becomes available in this chat right away, no new chat needed → run the quick legacy check, and if legacy is found, remind the user to close out positions and pending orders first, then create a new account on the authorization page after upgrading → trigger client-side authentication (Cursor's mcp_auth/Connect action — not a server tool) to open the authorization window and trigger OAuth, then wait for the user to finish logging in in the browser → confirm with one concrete account-level call (e.g. getAccountAssets) that the cloud MCP has saved the login state → give a completion message. Don't let the user manually create or paste an API Key, and don't construct an authorization link or listen for the callback yourself.

After that: Once the first authorization is done, this document's job is finished; after that, Key expiry, re-authorization, trading, and risk rules are all handled by the local bitget-agentic skill you've already read (npx @bitget-ai/bitget-agent-skill --skill agentic).

Only skip starting OAuth when the user explicitly says not to authorize. Saying "just check the market first" does not count as declining.

Read these first

• Market data can be checked without logging in. Trading, account, and Reality / rToken calls need OAuth. Check with guide before calling — if an endpoint isn't available, say so. Standard call chain: market data — guide(surface="market_data") → get params → do_query; trading/account — guide(surface="open_api") → get operation_id → do_request_open_api.

• Not supported: withdrawals, transferring from the main account to a sub-account, or changing the main account's email / phone / 2FA. US stock direct access, CFD, tax, staking/lending, and institutional lending are not integrated.

• The new login state is an OAuth token, not an API Key. One Agentic account can only be authorized to one Agent, and one Agent can only connect to one Agentic account — re-binding (the same Agent switching to a new account, or a different Agent connecting to an already-authorized account) replaces the existing authorization (any existing monitored/pending orders may stop working — be sure to tell the user).

• You can use multiple Agents at the same time, each bound to its own sub-account, to manage several Agentic sub-accounts that way; if you want one Agent to manage multiple sub-accounts, tell the user to join the group and give feedback to the product team.

• The authorization window is opened by the cloud MCP. Do not fabricate an authorization link yourself.

• If the user shows clear product-level confusion or questions during use (not operational details this document can answer), tell them to join the group and give feedback to the product team.

Step 0 · Install the local skill and hot-load it into this chat

npx @bitget-ai/bitget-agent-skill --target all --skill agentic

Must include --skill agentic — without it, you'll end up with the UTA skill that requires manually filling in a Key.

After installing, the Agent must read the full SKILL.md printed by the install command in this same chat — this is the action that hot-loads the skill into this chat and makes the later authorization and trading rules apply here; it cannot be skipped, and don't make the user open this file themselves. If no path is printed, look in the current client's own skills directory for the newly installed file.

The order between this step and Step 1 (connecting the cloud MCP) is not fixed — you can connect the MCP first and then hot-load the skill, or the other way around; neither has to finish first. But both must happen in this same chat — don't send either one off to a new chat.

If this skill still asks you to install the old local stdio MCP package @bitget-ai/bitget-agent-mcp, or asks the user to manually fill in an API Key, ignore those steps. Follow this document for connecting and authorizing. npx is just the install channel. @bitget-ai/bitget-agent-skill is the skill, not the legacy MCP.

Step 1 · Connect the cloud MCP

Do not configure BITGET_API_*. Register only this one HTTP address: https://agent.bitget.com/mcp.

• Claude Code: claude mcp add bitget-mcp-server -s user --transport http https://agent.bitget.com/mcp (-s user registers it at the user level, not just for the current project; Claude Code does not need, and does not have, Cursor's auth.CLIENT_ID mechanism)

• Cursor: Agent writes this config directly into ~/.cursor/mcp.json (merge with any existing server entries — don't overwrite the whole file). No need to wait for the user to fill it in via Settings; the tool usually appears in this chat right away (pending authorization)

• Other clients: use the same address following that client's way of registering an HTTP MCP

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

After writing the config, check whether this connection is already usable in this chat: the server only exposes three tools — guide / do_query / do_request_open_api. mcp_auth is not one of them — don't treat it as a tool to tools/call; not seeing it does not mean the MCP isn't connected. The real connection signal is seeing those three tools. In most cases the connection you just wrote becomes available in this chat right away — no new chat needed, no client restart needed. Don't assume it's unavailable by default.

Only open a new chat if, after writing the config, you've actually checked and still don't see guide / do_query / do_request_open_api in this chat — don't treat opening a new chat as the default step. The most common cause: the current client's MCP config still has the old local stdio MCP package @bitget-ai/bitget-agent-mcp, or a local MCP with a manually filled-in API Key — the old and new configs can technically sit in the file together without erroring (a soft conflict), but the product only supports one of them at a time; the old one left in place can block the new connection from taking effect, which is a hard conflict. Say this plainly to the user and guide them to clean it up — don't just say "let me check again." Only open a new chat once you've confirmed there's no such legacy leftover and the tools are still missing. Claude Code: quit and restart claude. Cursor: open a new Agent chat. Other clients: reconnect however that client does it. In the new chat, send:

I've written https://agent.bitget.com/mcp into my local MCP config, but this chat still can't see the guide / do_query / do_request_open_api tools. Please check whether my MCP config still has the old local stdio MCP package @bitget-ai/bitget-agent-mcp, or a local MCP with a manually filled-in API Key — if so, that's likely blocking the new connection. Tell me how to clean it up, then confirm whether the new connection works.

Step 2 · Quick legacy check before authorizing

A quick glance right before OAuth is enough — no state file, no remembering this across chats; just check where the current client stores its MCP config each time. Skip it if the user explicitly says not to authorize. Either of these counts as legacy:

• The config launches @bitget-ai/bitget-agent-mcp via local stdio

• This MCP config has BITGET_API_KEY / BITGET_SECRET_KEY / BITGET_PASSPHRASE manually filled in

The old and new cloud MCP can technically both sit in the config file without erroring each other (a soft conflict), but the product only supports one of them at a time — having both can make calls behave unpredictably, which is a hard conflict. If the legacy one is still there, only use the new cloud MCP's three server tools when calling (guide / do_query / do_request_open_api) — don't touch the legacy stdio MCP's tools or the API Key it left behind.

Not legacy: only configuring the cloud address https://agent.bitget.com/mcp; @bitget-ai/bitget-agent-skill being a skill. bgc, bitget-signal, its market-data MCP, upgrade-all, and the UTA skill without --skill agentic are also not legacy for this step — do not let them block OAuth. If the user is about to use them, remind them per the local skill you have already read.

Which package happens to be installed on this machine, or whether npm list / npm view has been run, cannot be used to judge this — do not go online to check, and do not run those commands; only look at the config content above. Do not assume the config file lives at some fixed path. Do not edit the config on the user's behalf.

If you can't find where the config lives, don't treat that as "no legacy version." Tell the user you couldn't find it, and ask them to confirm whether this machine still has the old local stdio MCP package @bitget-ai/bitget-agent-mcp, or a local MCP with a manually filled-in API Key. If they confirm there isn't one, continue with the new flow; if they're unsure or say there still is one, give the notice below.

If legacy is found, send the message below and go ahead toward Step 3 — you don't need to wait for the user to explicitly reply "I agree to upgrade" before opening the authorization window. Only stop and skip OAuth if the user explicitly says they don't want to upgrade or deal with the legacy setup.

Step 3 · Open the authorization window

There are two paths to trigger OAuth — use whichever the current client supports: ① a native client-side auth action — Cursor and similar clients show a "Connect"/auth entry next to this MCP connection (sometimes displayed as mcp_auth, but it is not a tool in the server's tools/list — don't call it via tools/call); ② if there's no such entry, call a private operation directly, e.g. do_request_open_api(operation_id="getAccountAssets", params={...}) — an unauthenticated call returns HTTP 401, and the client automatically pops the OAuth authorization page in response; the Agent does not need to handle that 401 itself.

1. Trigger auth via one of the two paths above (client-side Connect action, or the 401 from a private call).

2. If no window pops up but a link is returned, open it using whatever method this environment has for opening a browser — don't send the link to the user first.

3. Only if it can't be opened, send the raw link and explain that this environment doesn't have permission to open a window.

Tell the user: a browser window is about to open to complete authorization, and they don't need to copy an API Key. Don't change the Bitget domain in the message to the user.

Cursor: only trigger the client-side auth action once for the whole flow — don't click Authenticate / reconnect repeatedly. Log in using the browser tab that opened this time. If "Authorization session ended" appears but the callback link already has a code, that just means the old session expired — simply go through one more round of authorization.

Step 4 · Network and proxy (bitget.com)

The authorization page and callback need to reach bitget.com. Timeouts, ECONNREFUSED, ENOTFOUND, network errors, fetch failed, being unable to reach bitget.com, or the user saying Bitget won't open — treat these as network issues, not as a plain authorization failure to retry immediately.

1. Check whatever proxy is already active in the current environment — don't assume a specific port or config file.

2. If there's a proxy: route the shell or MCP launch environment through it, then retry from Step 3.

3. If there's no proxy: ask the user to turn one on. Retry from Step 3 once they confirm it's set up.

4. Don't make the user repeatedly click allow without first checking the network, don't construct a bitget.com link yourself, and don't ask the user to manually fill in an API Key.

Step 5 · Success

The user logs in and confirms on the page. The Agent does not fill in the password on their behalf.

Sign of being logged in: the client shows this MCP as logged in, and a call like do_request_open_api(operation_id="getAccountAssets", params={...}) succeeds. The page appearing to finish doesn't count. Besides getAccountAssets, any other read-only account-level operation_id also works to confirm (e.g. getDeductInfo — check guide(surface="open_api") for the exact list).

Then continue with the local skill you've already read. Don't write the token into the local skill.

If the user wants to remove the old API Key: the new account has no API Key, and there's no separate Key to delete on the website. First use guide(surface="open_api") to find the operation_id that returns the account name and call it — if it can't be found, say so, don't make one up. Then fill the name into this message:

Not successful

Don't guess if the reason isn't clear — ask whether to try again.