For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
DocumentationAPI Reference
DocumentationAPI Reference
  • Get Started
    • Introduction
    • Quickstart
    • Authentication
    • Rate Limit
    • Webhooks
  • Integration Guides
    • Overview
    • Tracking
    • Receiving
    • Returns
    • Billing
  • Other
    • Concepts
    • Status Reference
      • Overview
      • Setup
      • Tools & Examples
      • Troubleshooting & FAQ
      • Setup with API Token
    • Errors
    • FAQ
LogoLogo
On this page
  • Security Best Practices
  • Troubleshooting
  • Frequently Asked Questions
  • Support
  • When contacting support, include
OtherMCP Server

Troubleshooting & FAQ

||View as Markdown|
Was this page helpful?

Last updated May 19, 2026

Previous

Tools & Examples

Next

Setup with API Token

Built with

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 uses OAuth, so there is no static API token to leak. To keep your connection secure:

  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

Connection Issues

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.
OAuth / Sign-In Issues

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.
No Tools Available

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.
Tool Execution Failures

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

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.
Data Looks Wrong

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.

Frequently Asked Questions

What AI assistants are compatible?

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.

Do I need an API token?

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

How long does sign-in last?

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

Is there a cost?

The MCP server is free to use for ShipBob customers.

Can I use this in production?

Yes. Use the production URL listed on Setup and sign in with your production ShipBob account.

How do I switch between sandbox and production?

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.

Is my data secure?

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.

Can I limit which tools the assistant can call?

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.

Which records can the assistant read?

The AI client can read data from every channel on your merchant account. See Concepts > Channel for background.

How do I revoke access?

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

Support

  • Email: support@shipbob.com
  • Documentation: developer.shipbob.com
  • API Reference: ShipBob API Docs

When contacting support, include

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