> 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.

# MCP Server

> The ShipBob MCP (Model Context Protocol) Server enables AI assistants and agents to interact with ShipBob's Developer API through a standardized protocol. Connect claude.ai, ChatGPT, Claude Desktop, or any MCP-compatible client to work with your ShipBob data through conversational commands.

## What is MCP?

The Model Context Protocol (MCP) is an open protocol that standardizes how AI assistants connect to external data sources and tools. The ShipBob MCP Server acts as a bridge between your AI assistant and the ShipBob API, enabling natural language interactions with your fulfillment operations.

### Transport Protocol

The ShipBob MCP Server uses **Streamable HTTP transport**, which provides:

* **HTTP-based communication** for easy integration
* **Server-Sent Events (SSE)** support for real-time streaming responses
* **RESTful architecture** compatible with standard HTTP clients
* **Stateful sessions** for maintaining connection context
* **HTTP-Based**: Uses standard Streamable HTTP transport for broad compatibility

This transport method is ideal for web-based AI assistants and provides reliable, secure communication over HTTPS.

The server exclusively uses Streamable HTTP transport as defined in the [MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http). Other transport protocols (stdio, sse) are not supported.

### Key Benefits

* **Natural Language Interface**: Ask your AI assistant to check orders, view inventory, or browse products using plain English
* **AI-Powered Workflows**: Let AI assistants help automate routine ShipBob tasks
* **Secure Access**: All API calls use your existing ShipBob authentication credentials
* **Real-Time Data**: Get live information about orders, inventory, and shipments
* **Developer Friendly**: Works with popular AI development tools like Claude Desktop and VS Code

## Prerequisites

Before you begin, you'll need:

* **ShipBob Account**:
  * **Sandbox** (for testing): [Sign up for sandbox](https://webstage.shipbob.dev/app/merchant/#/SignUp?utm_source=app_partner)
  * **Production** (for live data): [Sign up at production](https://web.shipbob.com/app/Merchant/#/SignUp)
* **AI Assistant**: claude.ai, ChatGPT, Claude Desktop, VS Code with GitHub Copilot, or another MCP-compatible client
* **Browser**: The primary setup uses OAuth in your browser — no API tokens to generate or paste

## Quick Start

The ShipBob MCP Server is hosted and maintained by ShipBob. You don't need to install or run any server software — simply configure your AI assistant to connect to it. Setup is the same across every AI app that supports MCP:

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, and it controls what the AI client is allowed to write.

* **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.
* **Writes stay in the channel created at consent**: Create, update, and cancel operations only apply to records on the channel you created at the consent screen. The AI client cannot write into channels owned by other applications.

**Order, shipment, receiving, and return write operations are channel-scoped** — they require the record to belong to the channel created at consent. This covers Cancel Order, all Cancel Shipment variants (single, by-order, batch), Batch Update Tracking, Bulk Update Shipping Service, Update Shipment Address, Update Shipment Line Items, Cancel Receiving Order, Update Return, and Cancel Return. Product and variant write tools are **not** subject to this rule — they operate at the merchant/catalog level. Calls against records owned by other channels return `403` (or sometimes `404`).

## Configure Your AI Assistant

#### claude.ai

**Step 1: Open your Connectors settings**

Open [claude.ai](https://claude.ai) in your browser. From the sidebar, go to **Customize** → **Connectors**.

![claude.ai Customize → Connectors panel with the + icon visible](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/ship-stage.docs.buildwithfern.com/4dcb519d54c7df717fce7d2b640dbd1094c0a052c390f31e6abce9a90cff588a/docs/assets/images/claudeai-connectors-panel.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260811%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260811T160758Z&X-Amz-Expires=604800&X-Amz-Signature=39a7d0cc959d530bf6e5282bb9de87703f13b87dc1a75d6f40d5462d4ad35ff4&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

**Step 2: Add a custom connector**

Click the **+** icon → **Add custom connector**. Enter the name `ShipBob` and paste the server URL for your [environment](#server-urls). Click **Add**.

![Add custom connector dialog in claude.ai with Name = ShipBob and URL populated](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/ship-stage.docs.buildwithfern.com/314f8f551f3e5525535678afac47e44b5ed6bc9a71d9b815f681f959bc302cdf/docs/assets/images/claudeai-add-connector-dialog.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260811%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260811T160758Z&X-Amz-Expires=604800&X-Amz-Signature=3055536451c4e2b05a0f2ba41865341a3b4135315136ee39ce669a19154205f0&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

Or use a direct deep-link:

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

**Step 3: Sign in and grant access**

Claude opens a browser tab for ShipBob sign-in. Sign in with your ShipBob account and approve the permissions on the [consent screen](#what-the-consent-screen-asks-for).

**Step 4: Verify the connector is connected**

Back in your claude.ai settings, the connector shows as **Connected**.

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.

#### ChatGPT

ChatGPT supports remote MCP servers as **custom connectors** ("Apps"). The flow mirrors claude.ai — paste the ShipBob URL, then sign in through the browser tab ChatGPT opens.

**Prerequisites**

* A **ChatGPT Plus, Pro, Business, Enterprise, or Edu** account (custom connectors are not available on Free).
* **Developer Mode** enabled on your account (see Step 1).

**Step 1: Enable Developer Mode**

Sign in to [chatgpt.com](https://chatgpt.com), then open **Settings** → **Connectors** (labeled **Apps & Connectors** on newer accounts) → **Advanced settings** and toggle **Developer mode** on.

![ChatGPT Settings → Connectors → Advanced settings with Developer mode toggled on](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/ship-stage.docs.buildwithfern.com/a2f75df7097915dfbaed67302eb70819f44b529b29867b36f2f9d15c9e323685/docs/assets/images/chatgpt-developer-mode.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260811%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260811T160758Z&X-Amz-Expires=604800&X-Amz-Signature=ac4c90b37c183dc0a3245dd10fccf9f7509675a5a5709f0fcbe5ee945e655bec&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

**Step 2: Add a custom connector**

Back on the **Connectors** page, click **Add** (or **Create**) to add a custom connector. Fill in:

* **Name**: `ShipBob`
* **MCP Server URL**: the URL for your [environment](#server-urls)
* **Authentication**: **OAuth** (leave the default — ShipBob's server drives the OAuth flow itself, no client ID/secret needed)

Click **Create**.

![ChatGPT Add custom connector dialog with Name, MCP Server URL, and OAuth authentication populated](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/ship-stage.docs.buildwithfern.com/b370b7373554f82a1d0afe43f5cdb6472656d4ad8cb2ecd7c9ea6eee5de671fe/docs/assets/images/chatgpt-add-connector-dialog.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260811%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260811T160758Z&X-Amz-Expires=604800&X-Amz-Signature=ed77240f0c9d0368c413f455bdc4535bf9970f4a87167a73c733b52a324e7aff&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

**Step 3: Sign in and grant access**

ChatGPT opens a browser tab for ShipBob sign-in. Sign in with your ShipBob account and approve the permissions on the [consent screen](#what-the-consent-screen-asks-for). The connector then appears as **Connected** in your ChatGPT settings.

**Step 4: Use ShipBob in a chat**

In a chat, open the **+** (attach) menu, pick **ShipBob** under connectors, and start asking about your data.

The URL must be HTTPS. Both ShipBob environment URLs (sandbox and production) already meet this requirement.

If you don't see the **Developer mode** toggle or the **Add connector** button, your plan may not include custom connectors yet. Check OpenAI's documentation for connector availability for your plan.

#### Gemini

Gemini connects to remote MCP servers through **Gemini Spark**, Google's custom-app builder at [gemini.google.com/spark](https://gemini.google.com/spark). The flow mirrors claude.ai and ChatGPT — add a custom app pointing at the ShipBob URL, sign in through the browser tab Gemini opens, and grant access.

**Prerequisites**

* A Google account with access to [Gemini Spark](https://gemini.google.com/spark).

**Step 1: Open Connected Apps**

Sign in to [gemini.google.com/spark](https://gemini.google.com/spark). In the sidebar, under **Customize**, click **Connected Apps**.

**Step 2: Open the custom-app input**

Scroll to the **Custom apps for Spark** section:

* **First time (no custom apps yet)**: a URL input labeled **Add a custom app link to get started** is visible.
* **You already have custom apps**: click **Add a custom app** at the bottom of the list to reveal the same URL input.

**Step 3: Enter the MCP Server URL**

Paste the URL for your [environment](#server-urls) into the input field and click **Next**.

![Gemini Spark Custom apps for Spark section with the ShipBob MCP URL pasted](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/ship-stage.docs.buildwithfern.com/c7b3e019b0acbd1578e064825b1fba2b5b443b76ff69a915b68a876ca666987c/docs/assets/images/gemini-spark-add-custom-app.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260811%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260811T160758Z&X-Amz-Expires=604800&X-Amz-Signature=be3be3ffb23f05b116567a1e0437d431b21dc45c0c745c223d1f41d1722ab880&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

**Step 4: Provide the Client ID**

Gemini reads the server's OAuth metadata and prompts for a **Client ID**. Paste the ShipBob-issued OAuth client ID for Gemini Spark that matches the environment you chose in Step 3:

| Environment | Client ID                                                  |
| ----------- | ---------------------------------------------------------- |
| Sandbox     | `ExternalApplication_cfb94a93-b62b-409d-8c57-4da9075dd275` |
| Production  | `ExternalApplication_c69a7bc8-1ec6-4836-85c5-285172ec2139` |

Then continue.

![Gemini Spark Client ID prompt with the ShipBob-issued OAuth client ID entered](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/ship-stage.docs.buildwithfern.com/9bb4e4ac760b95c4a63c317aa556f4f25d1556a44f82a19366715e3be4e916a6/docs/assets/images/gemini-spark-client-id.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260811%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260811T160758Z&X-Amz-Expires=604800&X-Amz-Signature=4f8eef0187125db08fb6ad858daa9435a21bd04580d01eca645415886a341af8&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

Unlike claude.ai and ChatGPT, Gemini Spark requires a pre-registered OAuth **Client ID** in addition to the server URL. Use the Client ID that matches your server URL from Step 3 — sandbox and production have separate values.

**Step 5: Sign in and grant access**

Gemini opens a browser tab for ShipBob sign-in. Sign in with your ShipBob account and approve the permissions on the [consent screen](#what-the-consent-screen-asks-for). The app then appears as **Connected** in Spark.

**Step 6: Ask questions using ShipBob tools in Tasks**

In the Gemini Spark sidebar, click **Tasks**. Create a task that references a ShipBob MCP tool by name — Spark routes the call through the connected ShipBob app and returns the result inline. For example:

```
Use the Get Channels tool to list my channels.
```

You can reference any tool exposed by the ShipBob MCP server this way, and chain multiple tools in a single task. If Spark can't find the tool, see [Troubleshooting](#troubleshooting).

#### Gemini CLI

The [Gemini CLI](https://github.com/google-gemini/gemini-cli)

**Step 1: Add the ShipBob server**

```bash
gemini mcp add -s user --transport http ShipBob <MCP_SERVER_URL>
```

Replace `<MCP_SERVER_URL>` with the URL for your [environment](#server-urls).

* `--transport http` matches the Streamable HTTP transport the ShipBob server uses.
* `-s user` registers the server for your user across every Gemini CLI project. Drop the flag (or use `-s project`) to scope it to the current directory only.

**Step 2: Start the CLI**

```bash
gemini
```

**Step 3: Authenticate with ShipBob**

Inside the Gemini CLI, run:

```
/mcp auth ShipBob
```

The CLI opens a browser tab for ShipBob sign-in — sign in with your ShipBob account and approve the permissions on the [consent screen](#what-the-consent-screen-asks-for).

**Step 4: Verify the connection**

Ask:

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

You should see the list of ShipBob MCP tools. If nothing appears, see [Troubleshooting](#troubleshooting).

**Remove the server:**

```bash
gemini mcp remove ShipBob
```

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

#### Claude Desktop

**Step 1: Open Connectors settings**

Open **Claude Desktop**. From the sidebar, go to **Customize** → **Connectors**.

![Claude Desktop Customize → Connectors panel with the + icon visible](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/ship-stage.docs.buildwithfern.com/7545bacbe4a505923ad964bcc11c5d354c8e0aea60a7507ac8de64e505b9e19a/docs/assets/images/claude-desktop-connectors-panel.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260811%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260811T160758Z&X-Amz-Expires=604800&X-Amz-Signature=dee32fa6911001ccd5fef1a828300f2af7f9a118ad640b47cb2dca2bbd2948df&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

**Step 2: Add a custom connector**

Click the **+** icon → **Add custom connector**. Enter the name `ShipBob` and paste the server URL for your [environment](#server-urls). Click **Add**.

![Add custom connector dialog in Claude Desktop with Name = ShipBob and URL populated](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/ship-stage.docs.buildwithfern.com/53b59d4620864bcb617817b3a75969d96f72dd48334ea0a0094eae40cacd2639/docs/assets/images/claude-desktop-add-connector-dialog.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260811%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260811T160758Z&X-Amz-Expires=604800&X-Amz-Signature=b0fd89e3c71e5733ab7a9fde36d957612aaa265189acb7766d1d84f814181323&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

**Step 3: Sign in and grant access**

Claude opens a browser window for ShipBob sign-in. Sign in with your ShipBob account and approve the permissions on the [consent screen](#what-the-consent-screen-asks-for).

**Step 4: Verify the connector is connected**

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:

   #### Empty config file

   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`.

   #### File already has other servers

   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), use ShipBob's API token flow instead.

#### Claude Code CLI

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.

#### VS Code with GitHub Copilot

> **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`.

#### Other AI Apps

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

Your AI client controls tool approval — the ShipBob MCP Server does not enforce a prompt. Behavior varies:

* **claude.ai**, **Claude Desktop**, **VS Code with GitHub Copilot** — Prompt for confirmation before running write operations (create order, cancel order, etc.); read-only tools typically run without a prompt.
* **Claude Code CLI** — Follows Claude Code's per-tool permission rules. Write tools require explicit approval on first use (permission mode `default` or `plan`); users can `--allow` specific tools to skip the prompt in trusted workflows.
* **ChatGPT** — With Developer Mode connectors, tool calls run without a confirmation prompt by default. Review your ChatGPT connector settings if you need per-call approval for writes, and treat write-capable connectors accordingly.

Regardless of client, all write operations are still constrained to the [channel created at consent](#what-the-consent-screen-asks-for) — records owned by other channels return `403` or `404` when a write is attempted.

## Available Tools

The ShipBob MCP Server currently provides **27 tools** to interact with your ShipBob data across the following categories:

Currently, all tools provide read-only access to view and query your data. Tools for creating or modifying data are not yet available.

#### Orders (11 tools)

* Get Orders
* Get Order by Order ID
* Get Order Store JSON
* Get All Merchants Shipping Methods
* Get All Shipments for Order
* Get One Shipment by Shipment ID
* Get Logs for One Shipment by Shipment ID
* Get One Shipment by Order ID and Shipment ID
* Get Logs for One Shipment by Order ID and Shipment ID
* Get One Shipment's Status Timeline by Shipment ID
* Get One Shipment's Status Timeline by Order ID and Shipment ID

#### Products (7 tools)

* Gets Taxonomy
* Gets Product by ID
* Gets Taxonomy by ID
* Gets Taxonomy Parent
* Gets Packaging Requirement
* Gets Multiple Product Variants
* Retrieves List of Products Based on Filters Provided

#### Inventory (8 tools)

* Get Inventory
* Get All Inventories
* Get Inventory Levels
* Get All Inventory Levels
* Get Inventory Levels Grouped by Lot
* Get All Inventory Levels Grouped by Lot
* Get Inventory Levels Grouped by Fulfillment Center
* Get All Inventory Levels Grouped by Fulfillment Center

#### Channels (1 tool)

* Get Channels

## Using ShipBob with Your AI Assistant

Once configured, you can interact with ShipBob using natural language through your AI assistant.

### Example 1: Finding Orders That Need Attention

**You ask:**

```
"Show me orders that haven't been delivered yet"
```

**AI Response:** The assistant will filter orders by shipment status and display orders that are in processing, awaiting fulfillment, or in transit—helping you identify orders that need monitoring.

### Example 2: Checking Inventory Levels for a SKU

**You ask:**

```
"What's the current inventory level for SKU COFFEE-001?"
```

**AI Response:** The assistant will query inventory levels across all fulfillment centers and provide real-time stock information for that specific SKU.

### Example 3: Identifying Low Stock Products

**You ask:**

```
"Which products are low in stock?"
```

**AI Response:** The assistant will retrieve inventory levels for all products and highlight items with low on-hand quantities, helping you plan reorders and prevent stockouts.

### Example 4: Checking Product Details and Variants

**You ask:**

```
"What are all the variants for product SKU TSHIRT-BASIC?"
```

**AI Response:** The assistant will retrieve product details including all available variants (sizes, colors, etc.) along with their individual SKUs and inventory levels.

### Example 5: Checking Inventory Across Multiple Locations

**You ask:**

```
"Where is SKU WIDGET-001 stocked and how much inventory is at each location?"
```

**AI Response:** The assistant will show inventory distribution across all fulfillment centers, helping you understand stock allocation and plan transfers if needed.

### Example 6: Monitoring Order Shipment Timeline

**You ask:**

```
"Show me the shipment timeline for order 789456"
```

**AI Response:** The assistant will summarize the shipment's timeline as a list of time-stamped events (for example: shipment created, inventory allocated, fulfilled/shipped, in transit, delivered).

## Discovering Available Tools

To see all available ShipBob tools with detailed descriptions, ask your AI assistant:

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

## Security & Best Practices

When using the ShipBob MCP Server, follow these best practices to ensure security:

1. **Use environment-appropriate accounts**: Sign in with a sandbox ShipBob account for the sandbox URL, and a production account for the production URL. The two are fully isolated.
2. **Review the consent screen carefully**: The channel you create at consent controls which records the AI client can write to. See [What the Consent Screen Asks For](#what-the-consent-screen-asks-for).
3. **Approve write actions deliberately**: Most AI clients prompt you before running write tools (create order, cancel shipment, etc.). Review each action before it executes.
4. **HTTPS everywhere**: Both ShipBob MCP URLs are HTTPS; the OAuth handshake and every tool call are encrypted in transit.
5. **Understand your account's role**: The tools available to you depend on your ShipBob account's permission level. Insufficient role permissions surface as `403 Forbidden` errors.

## Troubleshooting

#### Connection Issues

**Problem**: AI assistant cannot connect to ShipBob MCP Server

**Solutions**:

1. Verify you're using the correct endpoint URL:
   * Sandbox: `https://sandbox-api.shipbob.com/developer-api/mcp`
   * Production: `https://api.shipbob.com/developer-api/mcp`
2. Check your internet connection
3. Ensure your AI assistant supports MCP protocol
4. Verify your configuration file syntax is correct

#### Authentication Errors

**Problem**: Requests fail with "401 Unauthorized" or "403 Forbidden"

**Solutions**:

1. Re-run the OAuth flow — remove and re-add the ShipBob connector in your AI client to trigger a fresh sign-in.
2. Confirm you signed in with the account that matches the environment (sandbox account for the sandbox URL, production account for the production URL).
3. For `403` on cancel or modify operations: the record likely belongs to a different channel. Writes only work against the channel created at consent — see [What the Consent Screen Asks For](#what-the-consent-screen-asks-for).
4. For `403` on other tools: your ShipBob account role may not have access to that operation. Contact your ShipBob account admin.

#### No Tools Available

**Problem**: AI assistant reports no ShipBob tools are available

**Solutions**:

1. Verify the MCP server configuration in your AI assistant
2. Restart your AI assistant after configuration changes
3. Check that your API token has the necessary permissions
4. Try asking: "What ShipBob tools are available?"

#### Tool Execution Failures

**Problem**: Tools execute but return errors

**Solutions**:

1. Check that required parameters are provided
2. Verify parameter formats match API requirements (e.g., dates, IDs)
3. Review error message for specific guidance
4. Consult [ShipBob API documentation](https://developer.shipbob.com/api) for parameter details
5. Ensure you have permissions for the operation

#### Rate Limiting

**Problem**: Requests are being throttled

**Solutions**:

1. Check ShipBob API rate limits
2. Reduce the frequency of requests
3. Use batch operations when available

#### Data Accuracy Issues

**Problem**: Data returned doesn't match expectations

**Solutions**:

1. Verify you're using the correct environment (sandbox vs production)
2. Check that data exists in your ShipBob account
3. Ensure you have the right permissions to view the data
4. Try the same query directly in the [ShipBob dashboard](https://web.shipbob.com)

## Frequently Asked Questions

#### What AI assistants are compatible?

Any MCP-compatible client with remote server + OAuth support. Tested clients include **claude.ai**, **ChatGPT** (custom connectors, on Plus/Pro/Business/Enterprise/Edu plans with Developer Mode), **Claude Desktop** (via custom connector), **Claude Code CLI**, and **VS Code with GitHub Copilot**. Any other modern MCP client that supports remote servers over Streamable HTTP will also work.

#### Is there a cost to use the MCP Server?

The MCP Server is free to use for ShipBob customers.

#### Can I use this in production?

Yes! Use the production endpoint (`https://api.shipbob.com/developer-api/mcp`) with your production API credentials.

#### How do I switch between sandbox and production?

Add a separate connector for each environment in your AI client, using the URL and account that match:

* **Sandbox**: `https://sandbox-api.shipbob.com/developer-api/mcp` — sign in with your sandbox account
* **Production**: `https://api.shipbob.com/developer-api/mcp` — sign in with your production account

#### Is my data secure?

Yes. All communication is encrypted via HTTPS. Authentication uses OAuth 2.0 with PKCE, no long-lived API tokens are exchanged, and no data is stored or shared by the MCP server.

#### Do I need to generate an API token?

No. The primary setup uses OAuth in your browser — sign in with your ShipBob account, grant access on the consent screen, and you're done. If your AI client can't open a browser (headless automation, for example), see the [ShipBob Authentication Guide](https://developer.shipbob.com/auth) for the API-token alternative.

#### Can I limit which tools my AI assistant can access?

The AI assistant will only perform actions you explicitly request. Your ShipBob API token's permissions also control what actions are possible.

## Support & Resources

### Getting Help

If you need assistance with the ShipBob MCP Server:

* **Email**: [techspecialists@shipbob.com](mailto:techspecialists@shipbob.com)
* **Documentation**: [https://developer.shipbob.com](https://developer.shipbob.com)
* **API Reference**: [ShipBob API Docs](https://developer.shipbob.com/api)

### When Contacting Support

Please include:

1. **Environment**: Development/Sandbox or Production
2. **AI Assistant and version**: e.g., claude.ai, ChatGPT, Claude Desktop, Claude Code CLI, VS Code with GitHub Copilot
3. **Error Messages**: Full error text if available
4. **Steps to Reproduce**: What you asked your AI assistant to do
5. **Expected Behavior**: What you expected to happen
6. **Actual Behavior**: What actually happened