> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer-dev.shipbob.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer-dev.shipbob.dev/_mcp/server.

# Troubleshooting & FAQ

> Security best practices, common issues, frequently asked questions, and support contacts for the ShipBob MCP Server.

This page covers what to do when something goes wrong, how to keep your connection secure, and answers to common questions.

## Security Best Practices

The ShipBob MCP Server supports two authentication flows, each with different exposure. Follow the practices that match how you connected:

**If you use the standard OAuth setup ([Setup](./setup))** — there is no static API token to leak. The client holds a short-lived OAuth session that you can revoke by removing the server entry.

**If you use the API-token setup ([Setup with API Token](./setup-with-token))** — a long-lived Bearer token sits in your config file. Treat it like a password:

* **Never commit the token to source control.** Prefer your client's secret mechanism instead of hard-coding tokens in shared config files (for example, in VS Code `mcp.json`, use `${input:shipbob_token}` or `${env:SHIPBOB_API_TOKEN}`).
* **Rotate periodically.** Regenerate the token from your ShipBob dashboard on a regular cadence, and after any suspected exposure.
* **Revoke immediately on exposure.** Delete the token in your ShipBob dashboard under **Account → API Access** the moment it leaks — that invalidates it server-side before anyone can use it.
* **Use environment-specific tokens.** Never reuse a production token in sandbox configs or vice versa.

**Regardless of flow:**

1. **Disconnect clients you no longer use**: Remove the server entry from any AI client you no longer use.
2. **Use HTTPS only**: All ShipBob MCP endpoints are HTTPS. Never accept an `http://` URL claiming to be the ShipBob MCP server.
3. **Mind your scopes**: Your ShipBob account's permissions control which tool calls succeed. Insufficient permissions return `403 Forbidden`.
4. **Treat consent screens seriously**: Only approve OAuth consent in clients you trust.

## Troubleshooting

**Problem**: AI assistant cannot reach the ShipBob MCP Server.

**Solutions**:

1. Verify the URL matches the one listed on the [Setup](./setup) page for your environment.
2. Check your internet connection and any corporate proxy / firewall rules.
3. Confirm your client supports **remote MCP servers over Streamable HTTP**. stdio-only clients are not supported.
4. If the client uses a config file (such as VS Code's `mcp.json`), validate the JSON syntax.

**Problem**: The browser sign-in never completes, or the client says it is not authorized.

**Solutions**:

1. Confirm the URL + account environment match. See the callout on [Setup](./setup) for the sandbox vs production rule.
2. Allow pop-ups for your AI client. Some browsers block the OAuth window.
3. If you signed in but the client still shows "not connected", remove the server entry and add it again to trigger a fresh OAuth flow.
4. Clear stale OAuth sessions: sign out of the client, restart it, and re-add the server.

**Problem**: The assistant says no ShipBob tools are available.

**Solutions**:

1. Confirm the server is in the **Connected** state in your client.
2. Restart the AI client after adding the server.
3. Re-run the verification prompt from [Setup](./setup#verify-the-connection).
4. Check that your ShipBob account has access to the Developer API.

**Problem**: A tool runs but returns an error.

**Solutions**:

1. Check that you supplied any required parameters (order IDs, SKUs, dates).
2. Validate parameter formats against the [ShipBob API documentation](https://developer.shipbob.com/api).
3. Read the error message. `403 Forbidden` means your account lacks permission for that operation.
4. Confirm the data exists in the environment you are connected to.
5. If a write tool fails on a record you can read fine, the record may belong to a different channel. The AI client can only write on the channel created at the consent screen. See [Setup > What the Consent Screen Asks For](./setup#what-the-consent-screen-asks-for).

**Problem**: A cancel or modify tool returns `403 Forbidden` (or sometimes `404 Not Found`) even when the assistant can clearly read the record.

**Cause**: These operations require the request's channel to match the channel that **originally created** the record. Using a different channel's session returns `403` (or `404`) even when the OAuth session has the correct write scopes. A `404` here usually means "record exists but does not belong to your channel," not "record missing."

**Affected operations** — writes against orders, shipments, receiving orders, and returns are channel-scoped:

**Orders / shipments**

* Cancel Order
* Cancel Shipment by Shipment ID
* Cancel Shipment by Order ID and Shipment ID
* Batch Cancel Shipments
* Batch Update Tracking
* Bulk Update Shipping Service
* Update Shipment Address
* Update Shipment Line Items

**Receiving**

* Cancel Receiving Order

**Returns**

* Update Return
* Cancel Return

Product and variant write tools (Create/Update/Delete Bundle Product, Create/Update Variants, Convert Variant to Bundle, Merge Variant, Move Variants) operate at the merchant/catalog level and are **not** subject to the channel-scope rule.

**Solutions**:

1. Fetch the record first (read tools work across all channels) and check its `channel_id`.
2. Reconnect the MCP server using a session whose channel matches that `channel_id`.
3. If you manage multiple channels, add a separate MCP server entry per channel and use the matching one for write operations.

See [Concepts > Channel](/concepts) for background on channel ownership.

**Problem**: Requests are being throttled.

**Solutions**:

1. Reduce request frequency.
2. Use batch / "All" variants of tools where available.
3. Review the [Rate Limit](/rate-limit) page for current limits.

**Problem**: Returned data does not match what you expect.

**Solutions**:

1. Confirm you are connected to the right environment. Sandbox and production are isolated and do not share data.
2. Cross-check the same query directly in the [ShipBob dashboard](https://web.shipbob.com).

## Frequently Asked Questions

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.

Not for the standard [Setup](./setup) — it uses OAuth. You sign in with your ShipBob account on first connection and the client stores the OAuth session.

An API token is only needed if you follow the alternative [Setup with API Token](./setup-with-token) flow, which is intended for AI clients or automation that cannot open a browser to complete OAuth.

OAuth token lifetime matches the rest of the ShipBob API. See [Authentication](/auth) for token and refresh details.

The MCP server is free to use for ShipBob customers.

Yes. Use the production URL listed on [Setup](./setup) and sign in with your production ShipBob account.

Add two server entries, one for each URL, and sign in to each with the matching account. You can keep both active and pick the right one in conversation.

Yes. All traffic uses HTTPS, authentication uses OAuth (no static credentials), and the MCP server does not store your data. It proxies live calls to the ShipBob Developer API.

Two layers control this. First, your AI client only performs actions you explicitly request. Second, your ShipBob account's permissions determine which tool calls succeed against the API.

The AI client can read data from every channel on your merchant account, but can only write (create, update, cancel) on the channels created at the consent screen. It cannot modify records that belong to other applications' channels. See [Concepts > Channel](/concepts) for background.

Revocation is controlled by your AI client. Remove the server entry (or disconnect / delete the connector) inside the client.

## Support

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

### When contacting support, include

1. **Environment**: Sandbox or Production
2. **AI client and version**: e.g., claude.ai, ChatGPT, Claude Desktop, Claude Code CLI, VS Code with GitHub Copilot
3. **Error message**: Exact text
4. **Prompt**: What you asked the assistant
5. **Expected vs actual**: What you expected and what happened