ShipHero AI Toolkit

ShipHero supports two ways to use AI with your ShipHero data: the ShipHero MCP and the Public API Skill.

Use the MCP if you want the simplest setup for asking ShipHero questions from an AI client. Use the Skill if you are an advanced user who wants to answer more complex ShipHero questions or if you are interested in building a ShipHero integration.

Why this exists

Warehouse operations generate constant questions: What’s the current inventory level on SKU ABC-123? Which orders have an address hold? Which shipments were created yesterday? Traditionally, answering those questions meant logging into ShipHero, running reports, or building custom integrations.

The ShipHero AI Toolkit gives AI clients a secure way to query live ShipHero data. It comprises two tools. The ShipHero MCP is the fastest path for common operational questions, while the ShipHero Public API Skill supports advanced analysis and ShipHero integration development.

ShipHero MCP

The ShipHero MCP is the easiest way to connect an AI client to ShipHero. It lets supported clients query your ShipHero account without requiring you to manually write GraphQL, manage Public API tokens, or install the full skill package.

ShipHero MCP works anywhere MCP is supported, including:

Use the MCP for questions like:

• What’s the current inventory level for SKU ABC-123?
• Show me orders with an address hold.
• Show shipments created yesterday.
• List purchase orders expected to arrive this week.
• Show returns created today.

If you grant read-write access, you can also ask it to make changes, like:

• Order tags: Add order tag abc to unfulfilled orders with SKU ABC-123.
• Holds: Remove the address hold from order 123456.
• Order editing: Add one GIFT-WRAP to order #10582.
• Kits: Turn existing SKU SUMMER-BUNDLE into a kit containing two shirts and one cap.
• Shipments: Create a shipment for order #10582 with UPS tracking number 1Z999....
• 3PL billing: Charge Acme $35 for relabeling 100 units.
• Products: Add an image of a plain white t-shirt for product T-SHIRT-WHITE.

The MCP is designed for simple ShipHero queries and updates. It is not intended for building full integrations or generating complex custom application code.

MCP Installation

Our MCP server URL is:

https://mcp.shiphero.com/mcp

Installation steps vary by AI client and subscription type. Follow your AI client’s documentation, or ask your AI client to help you configure the connection.

When you add the ShipHero MCP, your client opens a ShipHero authorization flow. Log in with your ShipHero credentials and select the access level (read-only or read-write) you want to grant to the client. You can change this later by reconnecting the MCP and going through the authorization flow again.

Claude

Claude calls MCP servers Connectors. See Claude’s official custom connector documentation.

ChatGPT and Codex

See OpenAI’s official Developer mode and MCP apps in ChatGPT.

ChatGPT calls MCP servers Plugins.

Enterprise accounts

On Enterprise accounts, account owners need to add the MCP configuration through the ChatGPT organization setup.

Personal and Team accounts

On Personal or Team accounts, you can add the ShipHero MCP through ChatGPT Web, your config file, or the CLI. Adding it through ChatGPT Web makes it available in all ChatGPT and Codex clients connected to your account. Adding it through the config file or CLI makes it available only to local Codex clients that share that configuration.

ChatGPT Web

The easiest way to add the MCP is through https://chatgpt.com. Log in to your account, then go to Settings > Plugins > Browse Plugins > Add.

Config file

Add the following to your ChatGPT/Codex configuration (official documentation):

[mcp_servers.shiphero]
url = "https://mcp.shiphero.com/mcp"
scopes = ["read:public-api", "read-write:public-api"]

[mcp_servers.shiphero.oauth]
client_id = "00ks8TNFn5J9SrqePsRSHKmiakONdWjU"
callback_port = 41592

Restart your app afterwards.

CLI

1. Add the ShipHero MCP server:

   codex mcp add shiphero --url https://mcp.shiphero.com/mcp

2. Codex opens a login page. The page currently returns an error because of a Codex bug.

3. Return to the terminal and press Ctrl+C.

4. Log in again with the required scopes:

   codex mcp login shiphero --scopes read:public-api,read-write:public-api

   When the login page opens, authorize the connection.

5. Open Codex and test the ShipHero MCP.

Others

See your AI client’s documentation for MCP setup instructions. You can also ask the client to add the ShipHero MCP and point it to this page.

The ShipHero MCP server URL is https://mcp.shiphero.com/mcp.

The server requires OAuth and, where available, supports Client ID Metadata Documents (CIMD). Otherwise, use the following settings:

• OAuth Client ID: 00ks8TNFn5J9SrqePsRSHKmiakONdWjU
• OAuth Callback port: 41592
• Scopes: read:public-api read-write:public-api

Alternatively, you can fall back to a stdio MCP configuration.

MCP stdio command:

npx -y mcp-remote@latest https://mcp.shiphero.com/mcp 41592 --transport http-only --static-oauth-client-info "{\"client_id\":\"00ks8TNFn5J9SrqePsRSHKmiakONdWjU\"}" --static-oauth-client-metadata "{\"scope\":\"read:public-api read-write:public-api\"}"

Troubleshooting

If the ShipHero MCP doesn’t show up or doesn’t respond right after you add it, restart your AI client. Most clients only pick up newly added MCP servers after a full restart.

Still stuck? Come ask in the ShipHero Community — we’re happy to help.

MCP Usage

After installation and authorization, ask your AI client a ShipHero question:

Get my last 50 ShipHero orders.

Keep prompts specific. Ask for the exact object, date range, SKU, order number, warehouse, or status you need. Specific prompts use fewer API credits and return better answers.

Public API Skill

The Public API Skill is for advanced users working from an agentic coding harness. It provides an agent with more advanced capabilities than those of the MCP option.

Use the Skill when you want an agent to:

• Analyze ShipHero data with custom query logic.
• Build or modify software that integrates with ShipHero.
• Know how to use the ShipHero Public API.

The Skill requires a coding agent. It is not meant for Claude Chat or Claude CoWork type of tools. Use the MCP on those clients.

Skill Installation

Download the current Skill package:

shiphero-public-api-skill-20260604.zip

The fastest installation path is to ask your coding agent to install it:

Download the Public API Skill from https://developer.shiphero.com/shiphero-ai-toolkit and install it

For manual installation, extract the zip into your agent’s skill folder.

unzip shiphero-public-api-skill-20260604.zip -d ~/.agents/skills/

Common skill folders:

Restart your agent if it does not load newly installed skills automatically.

Skill Usage

After installation, you can ask your agent ShipHero questions:

How many orders did I receive today on ShipHero?

For integration work, be explicit about the target language, framework, and workflow:

Use the ShipHero Public API Skill to add a Node.js function that fetches inventory by SKU from the ShipHero GraphQL API.

The Skill includes scripts for OAuth PKCE token setup, token refresh, and token revocation. When your work is done, ask the agent to revoke the token if it no longer needs access.

You can tell the agent to request only the permissions needed for a task or to omit access to protected personal data. See Scopes for the available permissions and prompt examples.

API Credits

Both the MCP and the Skill query the ShipHero Public API, but they use a separate AI Toolkit credit pool containing 2,002 credits. Credits used through the MCP or the Skill do not reduce the credits available for normal Public API usage.

AI agents can make several calls while answering one question. Those calls consume AI Toolkit credits. Ask for only the fields and date ranges you need, and monitor credit usage during testing.