> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.shipbob.com/llms.txt. > For full documentation content, see https://developer.shipbob.com/llms-full.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.shipbob.com/_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. 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](https://files.buildwithfern.com/ship.docs.buildwithfern.com/b9f7a20a82a7a8b47b6a5f6aada268fda3f5f9d04c59a5fe53c957c7a6432854/docs/assets/images/pat-screen.png) Treat this token like a password. Do not share it or commit it to source control. For more detail on token generation, see [Authentication](/auth). ## Step 2 - Configure Your AI Client Pick your app below and follow the instructions. 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](https://files.buildwithfern.com/ship.docs.buildwithfern.com/a3ba414729771059b7e2d8095f9322117c7230474a8f0ede74fa3ef51985a780/docs/assets/images/node-version.png) 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](https://files.buildwithfern.com/ship.docs.buildwithfern.com/be183ff537715eff08de007f05030e551dc634ec61e521253dd55ccf3ed9fd8a/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](https://files.buildwithfern.com/ship.docs.buildwithfern.com/7b141cd9bf71ae461ada2bcb48067156d2a687e823c6675d81293cf615377cbe/docs/assets/images/claude-desktop-config-file.png) ![Claude Desktop Config File Content](https://files.buildwithfern.com/ship.docs.buildwithfern.com/a0959f0608a3a477bb0e05e546f3f8a4cb00b8ae698f047e39c7402a8bbf865f/docs/assets/images/claude-desktop-config-file-content.png) 4. Add the ShipBob connection: 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](https://files.buildwithfern.com/ship.docs.buildwithfern.com/62c6f27a9cbad81c9763187a098e6b6753b8a6d37e8445d6f34c143a9b9acf10/docs/assets/images/claude-config.png) For sandbox, swap the URL to `https://sandbox-api.shipbob.com/developer-api/mcp`. 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" } } } } ``` 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. 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](https://files.buildwithfern.com/ship.docs.buildwithfern.com/456eb3f096ff76e0917ca9b9f735912ebd81a4e565093add7c6521f922719e50/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](https://files.buildwithfern.com/ship.docs.buildwithfern.com/64e59d6d35d7340bb56217c5a41d3ddc5ab5c34679df60b0d47338d7b7eb4194/docs/assets/images/force-stop-claude.png) 8. Reopen Claude Desktop ![Connectors list in Claude chat](https://files.buildwithfern.com/ship.docs.buildwithfern.com/28dcdd2194972b41e01bc76f39f3b54499c476791439750f119824bd1f719c2c/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](https://files.buildwithfern.com/ship.docs.buildwithfern.com/8171151922d73afdfe810be7dce9b9838fbf4f8f34903f3b52024bfa1e11a4cf/docs/assets/images/mcp-server-tools-list.png) 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`. 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 (only needed for Claude Desktop). 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](/auth) - more details on generating API tokens * [Troubleshooting & FAQ](./troubleshooting) - common issues and fixes