---
name: bitpanda-mcp-setup
description: "Connect an AI agent to a Bitpanda account through the Bitpanda MCP servers, for portfolio, prices, trading and Earn on the Public API, or orders and market data on Fusion. Use when the user asks to set up, connect or verify Bitpanda in their agent, or to set up bitpanda.com/skill.md."
---

# Bitpanda MCP setup

Bitpanda runs two remote MCP servers. This guide connects the user's MCP client
to one or both. The user does the setup in their own Bitpanda account and
client; you guide them through it.

## How to run this setup

- Go one step at a time, and do not combine steps. Give the user every
  instruction of the step, with its links and commands, instead of a summary.
  Say what they should see, and wait for them to confirm before you continue.
- The user performs every step. If you can run commands and a step involves no
  credential, you may offer to run it, and only do so once they agree.
- Never ask for, read or store the API key, and do not open config files that
  contain it. The user copies it from Bitpanda straight into their client. If
  a key is pasted into the conversation, tell the user to delete it in Bitpanda
  and create a new one.
- Setup is read-only. Do not trade, stake or set limits unless the user asks.
- If a step fails, stop and report what failed. Do not work around it with
  another connection method or direct API calls.

## 1. Choose the server

Ask what the user wants the agent to do, then recommend a server. Both can run
side by side.

| Server | Name | Endpoint | For |
| --- | --- | --- | --- |
| Bitpanda | `bitpanda` | https://mcp.public.bitpanda.com | Portfolio, balances, trade and transaction history, prices, buying and selling, Bitpanda Earn |
| Bitpanda Fusion | `bitpanda-fusion` | https://mcp.fusion.bitpanda.com | Market data, order book, placing and canceling orders, Fusion balances and fees |

Register each server under the name above. Two servers with the same name
overwrite each other.

## 2. Identify the client

Use reliable context about where you are running; otherwise ask. Both servers
authenticate with a Bitpanda API key in the `x-api-key` header, so the client
must support headers on remote MCP servers. Never use the client's sign-in,
Authenticate or login option for these servers; they only accept the API key.
Step 4 covers Claude Code, Codex, Cursor and Claude Desktop. For any other
client, do not invent steps; point the user to the MCP server guide at
https://docs.bitpanda.com/mcp-server-371916m0

## 3. Create an API key

First pick the fewest scopes that cover the request:

- `bitpanda`: **Balances** and **Transaction** for the portfolio and history,
  **Trade (Write)** only to buy or sell, **Earn (Read)** and **Earn (Write)**
  only for staking, **Trade (Read)** only for margin leverage. Prices and the
  asset list work with any key.
- `bitpanda-fusion`: **Read**, plus **Trade** only to place or cancel orders.
  Leave **Transfer** off.

Recommend read-only scopes unless the user asked to trade or stake. With
Trade (Write) or Earn (Write), also add **Transaction**, so you can check
whether an unclear trade or stake went through.

Always have the user create a new key: keys from the old Bitpanda web app do
not support trading or Fusion, and keys stop working when they expire.

Then give the user the list for their server as it is, with their client and
the scopes you picked filled in, so they only have to click the link and follow
along. If you can run commands, offer to open the link in their browser. For
both servers, they create one key each, one list at a time. Continue once they
confirm that the key is shown.

`bitpanda`:

1. Open https://app.bitpanda.com/my-account/apikey and sign in if asked.
2. Create a new API key, name it after your client, for example "Claude Code",
   and pick an expiry date (one year at most).
3. Tick only [the scopes you picked], then generate the key.
4. Open the confirmation email from Bitpanda and click its link.
5. Your key opens in a new tab and is shown only once. Keep that tab open for
   the next step, and do not paste the key into this chat.

`bitpanda-fusion`:

1. Open https://app.bitpanda.com/my-account/apikey?tab=Fusion and sign in if asked.
2. Create a new API key, name it after your client, for example "Claude Code",
   and pick an expiry date (one year at most).
3. Tick only [the scopes you picked], then generate the key.
4. Open the confirmation email from Bitpanda and click its link.
5. Your key opens in a new tab and is shown only once. Keep that tab open for
   the next step, and do not paste the key into this chat.

## 4. Connect the client

Show only the steps for the user's client, system and server.

The terminal blocks for Claude Code and Codex are written out for each server.
Use them exactly as they are: each block removes and re-adds only the server it
names, so a block edited by hand could remove the other server. Each comes in
two versions: bash or zsh for macOS, Linux and WSL, and PowerShell for Windows.
The user pastes the whole block and presses Enter. When it waits for input,
they copy the key for that server from its Bitpanda tab, paste it and press
Enter: it is not shown, and it stays out of the shell history. To connect both servers, they run the block for
each. Running a block again replaces that server's existing entry.

The config file examples use `bitpanda`; for Fusion, use the name
`bitpanda-fusion` and the endpoint of that server instead. In config files,
the user replaces `YOUR_BITPANDA_API_KEY` with their key.

**Claude Code.** The user quits Claude Code and runs the block for their server
and system in their terminal, so the key never enters the conversation.

`bitpanda`, bash or zsh:

```bash
{
  read -rs BITPANDA_API_KEY
  claude mcp remove bitpanda --scope user >/dev/null 2>&1
  claude mcp add --transport http --scope user bitpanda https://mcp.public.bitpanda.com \
    --header "x-api-key: $BITPANDA_API_KEY"
  unset BITPANDA_API_KEY
}
```

`bitpanda`, PowerShell:

```powershell
& {
  $key = [Net.NetworkCredential]::new('', (Read-Host 'Bitpanda API key' -AsSecureString)).Password
  claude mcp remove bitpanda --scope user *> $null
  claude mcp add --transport http --scope user bitpanda https://mcp.public.bitpanda.com --header "x-api-key: $key"
}
```

`bitpanda-fusion`, bash or zsh:

```bash
{
  read -rs BITPANDA_API_KEY
  claude mcp remove bitpanda-fusion --scope user >/dev/null 2>&1
  claude mcp add --transport http --scope user bitpanda-fusion https://mcp.fusion.bitpanda.com \
    --header "x-api-key: $BITPANDA_API_KEY"
  unset BITPANDA_API_KEY
}
```

`bitpanda-fusion`, PowerShell:

```powershell
& {
  $key = [Net.NetworkCredential]::new('', (Read-Host 'Bitpanda API key' -AsSecureString)).Password
  claude mcp remove bitpanda-fusion --scope user *> $null
  claude mcp add --transport http --scope user bitpanda-fusion https://mcp.fusion.bitpanda.com --header "x-api-key: $key"
}
```

They then start Claude Code again with `claude --continue` from the same
folder to resume this conversation, and run `/mcp` to check that the server
is connected.

**Codex.** The user quits Codex and runs the block for their server and system
in their terminal. It writes to `~/.codex/config.toml`, or to
`$CODEX_HOME/config.toml` when set. If `codex mcp remove` fails, the block
prints the error and changes nothing.

`bitpanda`, bash or zsh:

```bash
{
  read -rs BITPANDA_API_KEY
  codex mcp remove bitpanda >/dev/null &&
    printf '\n[mcp_servers.bitpanda]\nurl = "%s"\nhttp_headers = { "x-api-key" = "%s" }\n' \
      https://mcp.public.bitpanda.com "$BITPANDA_API_KEY" >> "${CODEX_HOME:-$HOME/.codex}/config.toml"
  unset BITPANDA_API_KEY
}
```

`bitpanda`, PowerShell:

```powershell
& {
  $key = [Net.NetworkCredential]::new('', (Read-Host 'Bitpanda API key' -AsSecureString)).Password
  $dir = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME .codex }
  codex mcp remove bitpanda > $null
  if ($?) { Add-Content (Join-Path $dir config.toml) '', '[mcp_servers.bitpanda]', 'url = "https://mcp.public.bitpanda.com"', ('http_headers = { "x-api-key" = "' + $key + '" }') }
}
```

`bitpanda-fusion`, bash or zsh:

```bash
{
  read -rs BITPANDA_API_KEY
  codex mcp remove bitpanda-fusion >/dev/null &&
    printf '\n[mcp_servers.bitpanda-fusion]\nurl = "%s"\nhttp_headers = { "x-api-key" = "%s" }\n' \
      https://mcp.fusion.bitpanda.com "$BITPANDA_API_KEY" >> "${CODEX_HOME:-$HOME/.codex}/config.toml"
  unset BITPANDA_API_KEY
}
```

`bitpanda-fusion`, PowerShell:

```powershell
& {
  $key = [Net.NetworkCredential]::new('', (Read-Host 'Bitpanda API key' -AsSecureString)).Password
  $dir = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME .codex }
  codex mcp remove bitpanda-fusion > $null
  if ($?) { Add-Content (Join-Path $dir config.toml) '', '[mcp_servers.bitpanda-fusion]', 'url = "https://mcp.fusion.bitpanda.com"', ('http_headers = { "x-api-key" = "' + $key + '" }') }
}
```

To edit the file by hand instead, the user adds this block to
`~/.codex/config.toml`, replacing any existing `[mcp_servers.bitpanda]`
block:

```toml
[mcp_servers.bitpanda]
url = "https://mcp.public.bitpanda.com"
http_headers = { "x-api-key" = "YOUR_BITPANDA_API_KEY" }
```

They then run `codex resume --last` from the same folder to resume this
conversation.

**Cursor.** The user adds the server to the `mcpServers` object in
`~/.cursor/mcp.json`, keeping any servers already there, then restarts Cursor:

```json
{
  "mcpServers": {
    "bitpanda": {
      "type": "http",
      "url": "https://mcp.public.bitpanda.com",
      "headers": { "x-api-key": "YOUR_BITPANDA_API_KEY" }
    }
  }
}
```

**Claude Desktop.** Its config file only runs local servers, so it connects
through the `mcp-remote` bridge, which needs Node.js (https://nodejs.org). The
user adds this to the `mcpServers` object in the config file, keeping any
servers already there, then quits and reopens Claude Desktop. On Windows,
closing the window is not enough: quit it from the system tray icon.

```json
{
  "mcpServers": {
    "bitpanda": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.public.bitpanda.com",
        "--header",
        "x-api-key:${BITPANDA_API_KEY}"
      ],
      "env": { "BITPANDA_API_KEY": "YOUR_BITPANDA_API_KEY" }
    }
  }
}
```

Keep `x-api-key:${BITPANDA_API_KEY}` without spaces: Claude Desktop on
Windows does not escape spaces inside `args`, which breaks the header.

| System | Config file |
| --- | --- |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |

On Windows, `npx` can fail to start from a path with spaces; the Fusion MCP
guide has a workaround: https://docs.fusion.bitpanda.com/getting-started-370710m0

## 5. Verify the connection

Once the client has restarted, check that the Bitpanda tools are available.
Call one read-only tool the key's scopes allow, using the exact name and schema
the server exposes:

- `bitpanda`: `get_portfolio_holdings` if the key has Balances, otherwise
  `list_assets`, which works with any key.
- `bitpanda-fusion`: `get_account_balances`.

An empty result still means the connection works.

Report success only after that call returns without an error, and summarize it
without listing account details. If no Bitpanda tools appear, say that
verification is blocked and work through Troubleshooting with the user.

## 6. Cap trading

Skip this step unless the `bitpanda` key has Trade (Write). Recommend a
daily trading limit before the agent trades: Bitpanda enforces it on the key
itself, so it holds even if an agent misbehaves or is prompt-injected. The
server has one tool to read the limit and one to set it.

1. Read the current limit. `trading_limit.not_configured` means none is set.
2. Ask for a daily buy limit, a daily sell limit and the currency. Buy and sell
   are tracked separately; if the user gives one number, ask whether it applies
   to both.
3. Tell the user the limit is permanent for this key: it cannot be changed or
   removed, only replaced by creating a new key. Set it only once they confirm
   the values.

## After setup

- Confirm every trade, stake or order with the user before calling the tool:
  asset, side, amount and, for limit orders, price.
- If a trade, stake or order call times out or returns an unclear error, it may
  still have gone through. Do not retry it; check `list_operation_history`
  (`bitpanda`) or `list_orders` (`bitpanda-fusion`) first, or ask the user
  to check the Bitpanda app.
- Reading this file gives you instructions for this conversation only. If the
  user wants them available later, save this file as
  `bitpanda-mcp-setup/SKILL.md` with the client's own skill mechanism,
  frontmatter included; the folder name must match the skill name.
- To revoke access, the user deletes the API key in their Bitpanda settings.
  Removing the server from the client alone leaves the key valid.

## Troubleshooting

| Symptom | What to tell the user |
| --- | --- |
| `401`, no Bitpanda tools after restart, Claude Code showing "Needs authentication", or "Failed to connect" with "JSON Parse error" or "Dynamic Client Registration rejected" | The `x-api-key` header is missing or the key is wrong. Do not use the client's sign-in option; check the header in the client config, or create a new key. |
| Codex reports `duplicate key` in `config.toml` | The file has a server's block more than once, for example two `[mcp_servers.bitpanda]` blocks. The user deletes all blocks of that server in `config.toml`, then runs its setup again. |
| `codex mcp list` shows "Not logged in" or "Unsupported" in the Auth column | That column does not apply to API keys. Ignore it and do not run `codex mcp login`; the `x-api-key` header is what authenticates. |
| It worked before and now fails with `401` | The key expired or was deleted. Create a new key. |
| A tool fails with a permission or scope error | The key lacks the scope. Create a new key with the scope needed. |
| `429 Too Many Requests` | A per-user rate limit was hit (Public API: 50 read, 5 trade and 5 stake requests per second; Fusion: 1000 requests per minute in total, 240 for market data and 300 for new orders). Wait before retrying and avoid tight polling. |
| One server rejects a key that works on the other, for example with `401` | Public API and Fusion keys are not interchangeable. Use a Public API key for `bitpanda` and a key from the Fusion tab for `bitpanda-fusion`. |
| One server replaced the other | Both were registered under one name. Use `bitpanda` and `bitpanda-fusion`. |

## Reference

- MCP server guide: https://docs.bitpanda.com/mcp-server-371916m0
- Public API MCP tools: https://docs.public.bitpanda.com/getting-started-589286f0
- Fusion MCP tools: https://docs.fusion.bitpanda.com/available-tools-370711m0
- Developer documentation: https://docs.bitpanda.com/welcome-372072m0
- Help and community: https://docs.public.bitpanda.com/community-hub