> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bouncebox.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect AI assistants (MCP)

> Connect Claude Code or Claude Desktop to your BounceBox workspace over MCP — check the inbox, pull extraction results, and manage mailboxes from your AI assistant.

BounceBox runs a remote MCP server that gives AI assistants full access to the same actions you can take in the dashboard: list mailboxes, check the inbox, read extracted results, view attachments, approve or skip emails, manage mailboxes and the SKU catalog, and more.

The server endpoint is:

```text theme={null}
https://bouncebox.app/api/mcp
```

It speaks Streamable HTTP — the transport every modern MCP client uses. Any request that reads or changes your workspace needs an access token; tool discovery is anonymous.

## What the assistant can do

| Area                | Example tools                                                                         |
| ------------------- | ------------------------------------------------------------------------------------- |
| Inbox               | `list_emails`, `get_email`, `download_result`, `get_attachment`                       |
| Email actions       | `approve_email`, `save_order_review`, `reprocess_email`, `skip_email`                 |
| Mailboxes           | `list_mailboxes`, `get_mailbox`, `create_mailbox`, `update_mailbox`, `delete_mailbox` |
| Catalog & workspace | `list_skus`, `create_sku`, `update_sku`, `update_workspace_name`, `invite_member`     |
| Settings            | `get_notification_settings`, `update_notification_settings`, `test_webhook`           |

The assistant always works in your workspace, with your permissions — it can never reach another workspace's mail.

<Note>
  Write tools are approval-gated. Before the assistant approves an email, changes a mailbox, or deletes anything, it shows you a preview first and only proceeds when you explicitly confirm.
</Note>

## Get your access token

Access tokens are personal: each one is tied to your account and only lives while your session is fresh.

<Steps>
  <Step title="Sign in">
    Log in to your dashboard at `bouncebox.app`.
  </Step>

  <Step title="Open the token endpoint">
    Press `F12` (or `Option` + `Command` + `I`) to open your browser's developer tools, go to the **Console** tab, paste this and press Enter:

    ```js theme={null}
    fetch("/api/bubblav/token").then(r => r.json()).then(j => console.log(j.token))
    ```

    Copy the token that is printed — it's the long string of letters, digits, and dashes.
  </Step>
</Steps>

<Warning>
  Treat the token like a password — it grants read and write access to your workspace in your name. Don't paste it into untrusted apps or share it. Tokens expire after about 10 minutes, so mint a fresh one before each session.
</Warning>

## Connect

<Tabs>
  <Tab title="Claude Code">
    From your terminal:

    ```bash theme={null}
    claude mcp add --transport http bouncebox https://bouncebox.app/api/mcp \
      --header "Authorization: Bearer YOUR_TOKEN"
    ```

    Replace `YOUR_TOKEN` with the token you copied. Then ask, e.g., *"check my BounceBox inbox"*, *"show the extraction result for the latest email"*, or *"list emails waiting for review"*.
  </Tab>

  <Tab title="Claude Desktop">
    Claude Desktop reaches remote servers through a small local bridge (`mcp-remote`, requires Node.js). Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

    ```json theme={null}
    {
      "mcpServers": {
        "bouncebox": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://bouncebox.app/api/mcp",
            "--header",
            "Authorization: Bearer YOUR_TOKEN"
          ]
        }
      }
    }
    ```

    Restart Claude Desktop, then ask about your inbox or mailboxes.
  </Tab>
</Tabs>

<Note>
  Claude.ai's web connectors authenticate over OAuth, which the BounceBox MCP server doesn't offer yet — use Claude Code or Claude Desktop for now.
</Note>

## ChatGPT

ChatGPT's custom connectors currently authenticate only over OAuth, which the BounceBox MCP server doesn't offer yet — ChatGPT can't connect for now. Zapier is the way to reach BounceBox from ChatGPT-style workflows in the meantime; see [Zapier](/integrations/zapier).

## When the token expires

You'll notice the assistant starts failing with an authorization error. Mint a fresh token (the steps above) and re-add the connector, or update the header in the same command. A persistent API key option is planned so you won't need to re-mint.

## Security notes

* The token only ever grants what your dashboard account can do — members can't reach owner-only actions, and no token can cross workspaces.
* Discovery calls (listing available tools) carry no workspace data and don't need a token.
* Deleting a mailbox through the assistant is the same irreversible delete as in the dashboard — you'll always see a confirmation preview first.