Connecting AI assistants

Overview

ShipGenius runs a remote MCP (Model Context Protocol) server, so an AI assistant such as Claude can work in a ShipGenius account for its user. The user signs in to ShipGenius and approves the connection, and the assistant then reads and changes data through the public GraphQL API as that user.

https://api.lite.shipgeni.us/mcp

With the connector, an assistant can answer questions about shipments, orders, items and inventory, track packages, rate shop a package across every carrier ShipGenius offers, buy and void labels, check addresses, and update orders, items and inventory.

Requirements

The connector works on ShipGenius Plus accounts and above, the same plans that include API access. It does not work on Core accounts.

Labels bought through the API, including through an assistant, are paid from prepaid credits. To buy labels through the connector, the account needs prepaid credits set up with a balance that covers the label. Everything else works without them.

Connecting Claude

1. In Claude, open Customize, then Connectors, and choose Discover.
2. Find ShipGenius and click Connect.
3. Sign in to ShipGenius, including your second factor.
4. The consent page lists what Claude is asking to do. Click Approve.

On a Team or Enterprise plan, an owner may need to add ShipGenius for the organization before members can connect it.

There is no API key to create and nothing to set up in ShipGenius first.

Connecting Cursor

1. Add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project:

   {
       "mcpServers": {
           "shipgenius": {
               "url": "https://api.lite.shipgeni.us/mcp"
           }
       }
   }
   

2. In Cursor, open Customize, then MCPs, and connect ShipGenius.

3. Sign in to ShipGenius, including your second factor.

4. The consent page lists what Cursor is asking to do. Click Approve.

There is no API key to create and nothing to set up in ShipGenius first.

Cursor's default Auto-review mode can run a tool without asking you, and that includes a tool that buys a label. To control this, change the mode under Cursor Settings, then Agents, then Approvals & Execution.

Other MCP Clients

ChatGPT connects to the same server URL with no setup in ShipGenius. Any other MCP client needs an app set up as an OAuth client, as described in Connecting with OAuth. Its role must hold the permissions the server lists in its protected resource metadata, or authorization fails with invalid_scope.

Tools

Tool	Title	Hint	Arguments
search_schema	Search the ShipGenius API	Read-only	terms, namespace, kind, limit
graphql_query	Read ShipGenius data	Read-only	query, variables, operation_name
graphql_mutation	Change ShipGenius data	Destructive	mutation, variables, operation_name

• search_schema searches the public schema by keyword and returns the matching operations, the permission each one requires, and a starter document to copy. Given a namespace, such as Query.searches.shipment_record, it describes that namespace in full. Given nothing, it lists every namespace. kind chooses between queries and mutations.
• graphql_query runs a document that holds only queries.
• graphql_mutation runs a document that holds only mutations. It is marked destructive, so an assistant that follows the hint asks the user before each call.

The tools run on the same public schema as the API reference, so every operation documented there is available to the assistant.

Permissions

Every call runs as the user who approved the connection, with the same permission and ownership checks as a request to /v1/graphql. A user whose role cannot buy labels cannot buy them through the assistant either.

The first time anyone on an account approves an assistant, ShipGenius adds an app for it to the account, with a role holding the connector's permissions. On the Apps page, account admins can edit that role to limit what the assistant can do for everyone on the account, or turn the app off. A permission removed from the role stops working for every connection shortly after.

A user can disconnect at any time from Connected apps with Revoke Access, or by removing the connector in the assistant. Either way, the assistant loses access right away.

Access tokens last 1 hour and refresh tokens last 30 days. The assistant refreshes them on its own; a user who stops using it for 30 days signs in again on their next request.

Labels

A purchased Shipment has a label with png, zpl and scan_code.

Field	Contents
png	The label's first page as an image, for viewing or printing on an ordinary printer.
zpl	The label in Zebra Programming Language, for thermal label printers.
scan_code	Set only for labels bought with label_delivery: SCAN_CODE; a carrier location scans it to print.

png and zpl each carry a url, a mime_type and base64_encoded, the file itself. A url opens only for someone signed in to ShipGenius. A label with more than one page lists the rest among the shipment's documents as LABEL documents.

The server cannot send a label to a printer. To print on a thermal printer, use the ShipGenius desktop app.

A label bought through the assistant is paid from the account's prepaid credits and can be voided until the carrier scans it.

Limits

Limit	Value
Result size	50,000 characters of JSON; a larger result is refused.
Document depth	12 levels of nested fields.
Operation type	Each tool refuses a document holding the other kind.

A refused document comes back as a tool error carrying the API's message, so the assistant can narrow the selection or add a filter and try again.

Data and Privacy

The server receives only each tool's arguments: a search term, or a GraphQL document and its variables. It never receives the conversation, the assistant's memory, or files shared with the assistant. ShipGenius does not use the data it serves to train AI models.

What the assistant's provider does with the results it receives is governed by that provider's own terms. See the ShipGenius privacy policy for how ShipGenius handles data shared with connected apps.

Troubleshooting

Symptom	Cause
The assistant asks you to connect again	The refresh token expired or was revoked. Connect again.
invalid_scope during sign-in	A client set up as an app asked for a permission its role does not hold.
A tool error naming a permission	Your own role does not allow that operation.
A label purchase is refused	The account has no prepaid credits, or not enough to cover the label.
A tool error about result size	The result was over 50,000 characters. Ask for fewer fields or rows.

For help, contact info@shipgeni.us.