> This page is for version v1.0. > For other versions, use one of these documentation indexes: > - 2026-07 (default): https://developer-stage.shipbob.dev/2026-07/llms.txt > - 2026-01: https://developer-stage.shipbob.dev/2026-01/llms.txt > - 2025-07: https://developer-stage.shipbob.dev/2025-07/llms.txt > - v2.0: https://developer-stage.shipbob.dev/v2.0/llms.txt > - v1.0: https://developer-stage.shipbob.dev/v1.0/llms.txt > - Experimental: https://developer-stage.shipbob.dev/experimental/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer-stage.shipbob.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer-stage.shipbob.dev/_mcp/server. # Setup with API Token > Connect to the ShipBob MCP Server by generating an API token from your ShipBob dashboard and pasting it into your AI assistant's configuration. > **Note** > > This page shows how to connect using an **API token** that you generate from your ShipBob dashboard. If your AI app supports sign-in with your browser (most modern versions do), the [standard Setup](./setup) is easier - you just paste a URL and sign in. No token needed. ## When to Use This Method Use this setup if: * Your AI app doesn't offer a "sign in with browser" option when you add the ShipBob server * Your workplace requires you to use an API token instead of signing in through the browser * You prefer to generate and manage a token yourself If you're not sure, try the [standard setup](./setup) first. You can always come back here if it doesn't work with your app. ## Step 1 - Generate a ShipBob API Token 1. Log in to your ShipBob dashboard: * **Production**: [web.shipbob.com](https://web.shipbob.com) * **Sandbox**: [webstage.shipbob.dev](https://webstage.shipbob.dev) 2. In the left sidebar, click **Integrations** 3. Click **API Tokens**, then **Generate New Token** 4. Give the token a name (e.g., `Claude Desktop`) and click **Generate** 5. **Copy the token immediately** - it is only shown once ![PAT Screen](D:\Code\fern-documentation\fern\docs\assets\images\pat-screen.png) > **Warning** > > Treat this token like a password. Do not share it or commit it to source control. For more detail on token generation, see [Authentication](/v1.0/auth). ## Step 2 - Configure Your AI Client Pick your app below and follow the instructions. #### Claude Desktop Claude Desktop needs a helper tool called `mcp-remote` to send your token to ShipBob. This requires **Node.js** to be installed on your computer. **Before you start**: Download and install [Node.js (LTS)](https://nodejs.org/en/download). After installing, open a terminal (Command Prompt on Windows, Terminal on Mac) and type `node --version` to confirm it's working. You should see a version number like `v24.15.0`. ![Node Version](D:\Code\fern-documentation\fern\docs\assets\images\node-version.png) > **Note** > > If you see `'node' is not recognized` or `command not found`, restart your computer and try again. 1. Open **Claude Desktop** 2. Open the configuration file: * **Windows**: Click **File** → **Settings** → **Developer** → **Edit Config** * **Mac**: Click **Claude** in the menu bar → **Settings** → **Developer** → **Edit Config** ![Local MCP Servers](D:\Code\fern-documentation\fern\docs\assets\images\local-mcp-servers.png) 3. A file called `claude_desktop_config.json` opens in your text editor (Notepad on Windows) ![Claude Desktop Config File](D:\Code\fern-documentation\fern\docs\assets\images\claude-desktop-config-file.png) ![Claude Desktop Config File Content](D:\Code\fern-documentation\fern\docs\assets\images\claude-desktop-config-file-content.png) 4. Add the ShipBob connection: #### Empty config file If the file is empty or contains only `{}`, delete everything and paste this: ```json { "mcpServers": { "shipbob-developer-api": { "command": "npx", "args": [ "mcp-remote", "https://api.shipbob.com/developer-api/mcp", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer PASTE_YOUR_TOKEN_HERE" } } } } ``` ![Claude Config](D:\Code\fern-documentation\fern\docs\assets\images\claude-config.png) For sandbox, swap the URL to `https://sandbox-api.shipbob.com/developer-api/mcp`. #### File already has other servers If the file already has content, add the `"shipbob-developer-api"` block inside the existing `"mcpServers"` section. Do **not** delete what's already there. ```json { "mcpServers": { "some-other-server": { "...": "..." }, "shipbob-developer-api": { "command": "npx", "args": [ "mcp-remote", "https://api.shipbob.com/developer-api/mcp", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer PASTE_YOUR_TOKEN_HERE" } } } } ``` > **Note** > > Not sure where to paste it? Take a screenshot of your file and share it with support - we'll tell you exactly where. 5. Find the line that says `PASTE_YOUR_TOKEN_HERE` and replace it with the token you copied in Step 1. > **Note** > > Keep the word `Bearer` and the space before your token. The line should look like: `"AUTH_HEADER": "Bearer D4AC36BF5C5...4-1"` ![Claude Config with Masked Token](D:\Code\fern-documentation\fern\docs\assets\images\claude-config-with-masked-token.png) 6. Save the file (`Ctrl+S` on Windows, `Cmd+S` on Mac) 7. Fully close Claude Desktop - don't just minimize it: * **Windows**: Open Task Manager (`Ctrl+Shift+Esc`) → find **Claude** → right-click → **End Task** * **Mac**: Right-click Claude in the Dock → **Quit** ![Claude Force Stop](D:\Code\fern-documentation\fern\docs\assets\images\force-stop-claude.png) 8. Reopen Claude Desktop ![Connectors list in Claude chat](D:\Code\fern-documentation\fern\docs\assets\images\connectors-list-in-claude-chat.png) Open a new chat and you should see the ShipBob connector listed. Ask Claude, `What ShipBob tools are available?`, to verify the connection. ![MCP Server tools list](D:\Code\fern-documentation\fern\docs\assets\images\mcp-server-tools-list.png) #### VS Code with GitHub Copilot VS Code can connect to ShipBob directly with your token - no extra tools needed. Add the following to `.vscode/mcp.json` or your user MCP config: ```json { "servers": { "shipbob-developer-api": { "type": "http", "url": "https://api.shipbob.com/developer-api/mcp", "headers": { "Authorization": "Bearer ${input:shipbob_token}" } } }, "inputs": [ { "type": "promptString", "id": "shipbob_token", "description": "ShipBob API Token", "password": true } ] } ``` When you start the server for the first time, VS Code asks you to enter your token. Paste the token you copied in Step 1 (without `Bearer ` - VS Code adds that automatically). For sandbox, swap the URL to `https://sandbox-api.shipbob.com/developer-api/mcp`. #### Other AI Apps If your app lets you add a remote server with custom headers, configure it with: | Setting | Value | | ------------------------ | ---------------------------------------------------------------------------------------------------------------- | | **Server URL** | `https://api.shipbob.com/developer-api/mcp` (or `https://sandbox-api.shipbob.com/developer-api/mcp` for sandbox) | | **Authorization header** | `Bearer ` | If your app uses a JSON config file, the entry typically looks like: ```json { "type": "http", "url": "https://api.shipbob.com/developer-api/mcp", "headers": { "Authorization": "Bearer PASTE_YOUR_TOKEN_HERE" } } ``` If your app only supports running a local command (not a URL), you can use `mcp-remote` as a bridge. This requires [Node.js](https://nodejs.org/en/download): ```bash npx mcp-remote https://api.shipbob.com/developer-api/mcp --header "Authorization:Bearer PASTE_YOUR_TOKEN_HERE" ``` ## Step 3 - Verify the Connection Start a new chat and type: ``` "What ShipBob tools are available?" ``` If set up correctly, your AI client lists the available ShipBob tools. ## Common Errors | Error | What to do | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `npx: command not found` | Node.js is not installed. It's required for any client that uses the `mcp-remote` bridge — Claude Desktop and the **Other AI Apps** fallback above. Download from [nodejs.org/en/download](https://nodejs.org/en/download) and restart your computer. | | "Unauthorized" or 401 error | Your token may be incorrect. Go back to your ShipBob dashboard, generate a new token, and paste it again carefully. Make sure there's a space between `Bearer` and the token. | | ShipBob tools don't appear after restart | Make sure you fully closed your AI app - not just minimized it. On Windows, use Task Manager; on Mac, right-click in the Dock and click Quit. | | Config file shows a red error | The JSON formatting may be broken. Paste the entire file contents into [jsonlint.com](https://jsonlint.com) - it will highlight exactly where the problem is. | ## Need Help? * [Standard Setup](./setup) - easier setup that works by signing in through your browser * [Authentication](/v1.0/auth) - more details on generating API tokens * [Troubleshooting & FAQ](./troubleshooting) - common issues and fixes