> 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

> Add the ShipBob MCP Server to your AI assistant. The flow is the same for every client: paste a URL, sign in to ShipBob, grant access.

The ShipBob MCP Server is hosted by ShipBob. Setup is the same across every AI app that supports it:

1. Open your app's MCP or connector settings
2. Add a new server with the ShipBob URL
3. Your app opens a browser window where you sign in to ShipBob
4. Grant access on the consent screen
5. Start asking the assistant about your data

## Server URLs

Use the URL that matches the environment you want to talk to.

| Environment | URL                                                 |
| ----------- | --------------------------------------------------- |
| Sandbox     | `https://sandbox-api.shipbob.com/developer-api/mcp` |
| Production  | `https://api.shipbob.com/developer-api/mcp`         |

Sign in with the ShipBob account that matches the URL: sandbox account for the sandbox URL, production account for the production URL. Sandbox and production are isolated environments and accounts do not carry across.

## What the Consent Screen Asks For

On first connection, ShipBob asks you to create a **channel** for the AI client and shows the permissions the MCP tools need to function. A channel is how ShipBob tracks which app created which records — it is an installation of an application on top of the ShipBob API.

* **Reads cross channels**: The AI client can read data from every channel on your merchant account (orders from Shopify, Amazon, other apps, PAT-issued channels, etc.).
* **Permissions follow your account role**: The tools available to you depend on your ShipBob account's permission level. If a tool returns a 403 error, your account role may not have access to that operation — contact your ShipBob account admin to confirm.

For background on channels, see [Concepts > Channel](/concepts).

## Configure Your AI Assistant

1. Open [claude.ai](https://claude.ai) in your browser
2. Open the sidebar and go to **Customize** → **Connectors** → Click on **+** icon → **Add custom connector** (or use the direct link below)
3. Enter the name `ShipBob` and paste the server URL for your environment
4. Click **Add**. Claude opens a browser tab for sign-in.
5. Sign in with your ShipBob account and grant access on the consent screen
6. The connector shows as **Connected** in your claude.ai customization settings

**Direct deep-link to add the connector:**

* Production: [`Link`](https://claude.ai/customize/connectors?modal=add-custom-connector\&connectorName=ShipBob\&connectorUrl=https%3A%2F%2Fapi.shipbob.com%2Fdeveloper-api%2Fmcp)
* Sandbox: [`Link`](https://claude.ai/customize/connectors?modal=add-custom-connector\&connectorName=ShipBob+Sandbox\&connectorUrl=https%3A%2F%2Fsandbox-api.shipbob.com%2Fdeveloper-api%2Fmcp)

MCP connectors are available on claude.ai Pro and higher plans. If you don’t see the Connectors option, check that your plan includes MCP support.

1. Open **Claude Desktop**
2. Open the sidebar and go to **Customize** → **Connectors** → Click on **+** icon → **Add custom connector**
3. Enter the name `ShipBob` and paste the server URL for your environment
4. Click **Add**. Claude opens a browser window for sign-in.
5. Sign in with your ShipBob account and grant access on the consent screen
6. Back in Claude Desktop, the connector shows as **Connected**

Custom connectors require a current Claude Desktop release. If the menu item is missing, update Claude Desktop.

### If you don't see the option to add a custom connector

Register the ShipBob MCP Server by editing Claude Desktop's config file directly. This uses the `mcp-remote` helper to bridge Claude Desktop to the hosted server while still keeping the browser-based OAuth sign-in.

**Prerequisite — Node.js**

The `mcp-remote` helper runs on Node.js. If you don't already have it, download and install [Node.js (LTS)](https://nodejs.org/en/download). After installing, open a terminal and run `node --version` to confirm — you should see a version like `v24.15.0`.

**Steps**

1. Open the config file:

   * **Windows**: **File** → **Settings** → **Developer** → **Edit Config**
   * **Mac**: **Claude** (menu bar) → **Settings** → **Developer** → **Edit Config**

   A file called `claude_desktop_config.json` opens in your text editor (Notepad on Windows, the default editor on Mac).

2. Add the ShipBob server:

   If the file is empty or contains only `{}`, replace its contents with:

   ```json
   {
     "mcpServers": {
       "shipbob-mcp": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "https://api.shipbob.com/developer-api/mcp"
         ]
       }
     }
   }
   ```

   For sandbox, swap the URL for `https://sandbox-api.shipbob.com/developer-api/mcp`.

   If `"mcpServers"` already exists, add **only** the `"shipbob-mcp"` entry inside it. Do **not** delete or overwrite the other entries.

   ```json
   {
     "mcpServers": {
       "some-other-server": { "...": "..." },
       "shipbob-mcp": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "https://api.shipbob.com/developer-api/mcp"
         ]
       }
     }
   }
   ```

3. Save the file and **fully quit** Claude Desktop (don't just close the window). Reopen it.

4. On first use of a ShipBob tool, Claude Desktop opens a browser for the ShipBob sign-in / consent screen — same flow as the GUI path.

This is the OAuth flow — there are no API tokens to paste. If you'd rather use an API token (for example, for automation that can't open a browser), follow [Setup with API Token](./setup-with-token) instead.

Claude Code registers MCP servers from the terminal — no config-file editing needed.

**Add the ShipBob server (production):**

```bash
claude mcp add --transport http shipbob-mcp --scope user https://api.shipbob.com/developer-api/mcp
```

**Add the sandbox server:**

```bash
claude mcp add --transport http shipbob-sandbox --scope user https://sandbox-api.shipbob.com/developer-api/mcp
```

* `--transport http` matches the Streamable HTTP transport the ShipBob server uses.
* `--scope user` registers the server for your user across every Claude Code project. Use `--scope project` (or omit the flag) if you only want it inside the current project.

The first tool call against the server opens a browser for ShipBob sign-in and the consent screen — the same OAuth flow every other client uses.

**Remove the server:**

```bash
claude mcp remove "shipbob-mcp"
```

Run `claude mcp list` at any time to see which servers are registered.

> **Prerequisites**
>
> * Latest [Visual Studio Code](https://code.visualstudio.com/download)
> * Access to [GitHub Copilot](https://code.visualstudio.com/docs/copilot/setup)

**One-click install:**

Click the link below to add the ShipBob MCP server to VS Code automatically:

* Production: [Install ShipBob MCP Server in VS Code](vscode:mcp/install?%7B%22name%22%3A%22shipbob%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.shipbob.com%2Fdeveloper-api%2Fmcp%22%7D)
* Sandbox: [Install ShipBob Sandbox MCP Server in VS Code](vscode:mcp/install?%7B%22name%22%3A%22shipbob-sandbox%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fsandbox-api.shipbob.com%2Fdeveloper-api%2Fmcp%22%7D)

VS Code opens a prompt to confirm the server installation. After confirming, it opens a browser for sign-in.

**Manual setup:**

1. Choose where the MCP config lives:
   * **Workspace** (`.vscode/mcp.json`): use this for project-specific access. Teammates who check out the repo also get the server.
   * **User profile** (run `MCP: Open User Configuration` from the Command Palette with `Ctrl+Shift+P` / `Cmd+Shift+P`): use this to make the server available across all your projects.
2. Add the ShipBob server:

   ```json
   {
     "servers": {
       "shipbob": {
         "type": "http",
         "url": "https://api.shipbob.com/developer-api/mcp"
       }
     }
   }
   ```

   Swap the URL for `https://sandbox-api.shipbob.com/developer-api/mcp` to point at sandbox.
3. Run `MCP: List Servers` and start `shipbob`. VS Code opens a browser for sign-in.
4. Sign in with your ShipBob account and grant access.

See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) for full details on `mcp.json`.

Any app that supports remote MCP servers works the same way:

1. Add a new remote / custom MCP server in the app
2. Paste the ShipBob URL for your environment
3. Sign in to ShipBob in the browser window your app opens

No API tokens, headers, or extra tools are needed.

## Verify the Connection

Once the server is added, ask the assistant:

```
"What ShipBob tools are available?"
```

You should see a list of all available ShipBob tools. If nothing appears, see [Troubleshooting](./troubleshooting).

## Tool Approval Behavior

The ShipBob MCP Server exposes read-only tools. Your AI client controls whether tool calls require approval. **claude.ai**, **Claude Desktop**, and **VS Code with GitHub Copilot** typically run read-only tools without a confirmation prompt, so responses are fast and conversational.

## Next Steps

* [**Tools & Examples**](./tools) - See what you can ask
* [**Troubleshooting & FAQ**](./troubleshooting) - Fix common issues
* [**Setup with API Token**](./setup-with-token) - Alternative setup using an API token you generate from your ShipBob dashboard, for apps or workflows that don't support sign-in through the browser