Other

MCP Server

View as Markdown

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

EnvironmentURL
Sandboxhttps://sandbox-api.shipbob.com/developer-api/mcp
Productionhttps://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.

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

Step 1: Open your Connectors settings

Open claude.ai in your browser. From the sidebar, go to Customize → Connectors.

claude.ai Customize → Connectors panel with the + icon visible

Step 2: Add a custom connector

Click the + icon → Add custom connector. Enter the name ShipBob and paste the server URL for your environment. Click Add.

Add custom connector dialog in claude.ai with Name = ShipBob and URL populated

Or use a direct deep-link:

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.

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

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

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

Step 1: Open Connectors settings

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

Claude Desktop Customize → Connectors panel with the + icon visible

Step 2: Add a custom connector

Click the + icon → Add custom connector. Enter the name ShipBob and paste the server URL for your environment. Click Add.

Add custom connector dialog in Claude Desktop with Name = ShipBob and URL populated

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.

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.

Prerequisites

One-click install:

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.
    • User profile (run MCP: Open User Configuration from the Command Palette): use this to make the server available across all your projects.

  2. Add the ShipBob server:

    1{
    2  "servers": {
    3    "shipbob": {
    4      "type": "http",
    5      "url": "https://api.shipbob.com/developer-api/mcp"
    6    }
    7  }
    8}

    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 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 for the OAuth flow.

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.

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

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

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.
  4. For 403 on other tools: your ShipBob account role may not have access to that operation. Contact your ShipBob account admin.

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?”

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 for parameter details
  5. Ensure you have permissions for the operation

Problem: Requests are being throttled

Solutions:

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

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

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.

The MCP Server is free to use for ShipBob customers.

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

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

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.

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 for the API-token alternative.

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:

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