> 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 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. > **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](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/ship.docs.buildwithfern.com/b9f7a20a82a7a8b47b6a5f6aada268fda3f5f9d04c59a5fe53c957c7a6432854/docs/assets/images/pat-screen.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260926%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260926T021553Z&X-Amz-Expires=604800&X-Amz-Signature=3721c48e0423373569dee9930afd927d5404752a46006005ba2d3d5a8f515ed5&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) > **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](/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](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/ship.docs.buildwithfern.com/a3ba414729771059b7e2d8095f9322117c7230474a8f0ede74fa3ef51985a780/docs/assets/images/node-version.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260926%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260926T021553Z&X-Amz-Expires=604800&X-Amz-Signature=c7dc777a55fe7c1a56a7f7a47ec1524d4d7185b90e11fb244fb6e1f4fc22c021&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) > **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](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/ship.docs.buildwithfern.com/be183ff537715eff08de007f05030e551dc634ec61e521253dd55ccf3ed9fd8a/docs/assets/images/local-mcp-servers.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260926%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260926T021553Z&X-Amz-Expires=604800&X-Amz-Signature=a2bd5acb8e645036553118e1a442f7c64b43c1df9cab73c08a864c4a787bd7f8&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) 3. A file called `claude_desktop_config.json` opens in your text editor (Notepad on Windows) ![Claude Desktop Config File](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/ship.docs.buildwithfern.com/7b141cd9bf71ae461ada2bcb48067156d2a687e823c6675d81293cf615377cbe/docs/assets/images/claude-desktop-config-file.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260926%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260926T021553Z&X-Amz-Expires=604800&X-Amz-Signature=0a33d8e99e019c0d1e96516e368c4c6ec649d7aa876210f7d2c706a5e0d4b872&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) ![Claude Desktop Config File Content](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/ship.docs.buildwithfern.com/a0959f0608a3a477bb0e05e546f3f8a4cb00b8ae698f047e39c7402a8bbf865f/docs/assets/images/claude-desktop-config-file-content.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260926%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260926T021553Z&X-Amz-Expires=604800&X-Amz-Signature=0913d2917779c1001706c515e328c55b236aa23ea565dfc3d2fffbae44b1ce84&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) 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](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/ship.docs.buildwithfern.com/62c6f27a9cbad81c9763187a098e6b6753b8a6d37e8445d6f34c143a9b9acf10/docs/assets/images/claude-config.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260926%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260926T021553Z&X-Amz-Expires=604800&X-Amz-Signature=e5d0c9672100ce51d0f8dbc972c5da1a6ffd635eaddf108fdada3b771ecf3dbd&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) 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](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/ship.docs.buildwithfern.com/456eb3f096ff76e0917ca9b9f735912ebd81a4e565093add7c6521f922719e50/docs/assets/images/claude-config-with-masked-token.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260926%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260926T021553Z&X-Amz-Expires=604800&X-Amz-Signature=7cf28de597dfc679acd48928cf5a30baa10cfdcaec455bc0dd09c79b9f1114ec&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) 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://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/ship.docs.buildwithfern.com/64e59d6d35d7340bb56217c5a41d3ddc5ab5c34679df60b0d47338d7b7eb4194/docs/assets/images/force-stop-claude.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260926%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260926T021553Z&X-Amz-Expires=604800&X-Amz-Signature=caada3b53180dfed7c236685505528e971c2b7a97ff953c9827c82627775f718&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) 8. Reopen Claude Desktop ![Connectors list in Claude chat](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/ship.docs.buildwithfern.com/28dcdd2194972b41e01bc76f39f3b54499c476791439750f119824bd1f719c2c/docs/assets/images/connectors-list-in-claude-chat.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260926%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260926T021553Z&X-Amz-Expires=604800&X-Amz-Signature=bfa316fb55211dc8da48ee61407c1bb8d68c214b7a2cd691005e98f7817d07f7&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) 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://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/ship.docs.buildwithfern.com/8171151922d73afdfe810be7dce9b9838fbf4f8f34903f3b52024bfa1e11a4cf/docs/assets/images/mcp-server-tools-list.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260926%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260926T021553Z&X-Amz-Expires=604800&X-Amz-Signature=cd3595a0d7c8375f9fea46493400b6bc144f22f016d73fad419820bf03be301c&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) #### 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](/auth) - more details on generating API tokens * [Troubleshooting & FAQ](./troubleshooting) - common issues and fixes