Troubleshooting & FAQ

Problem: AI assistant cannot reach the ShipBob MCP Server.

Solutions:

1. Verify the URL matches the one listed on the 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 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.
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.
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.

Problem: Requests are being throttled.

Solutions:

1. Reduce request frequency.
2. Use batch / “All” variants of tools where available.
3. Review the 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.

Any MCP-compatible client with remote server + OAuth support. This includes Claude Desktop (via custom connector), VS Code with GitHub Copilot, and other modern MCP clients.

No. The MCP server uses OAuth. You sign in with your ShipBob account on first connection and the client stores the OAuth session.

OAuth token lifetime matches the rest of the ShipBob API. See Authentication for token and refresh details.

The MCP server is free to use for ShipBob customers.

Yes. Use the production URL listed on 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. See Concepts > Channel for background.

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