How to Connect the OpenAI API to the Easyship MCP Server

This article explains how to set up the Easyship MCP server with the OpenAI Responses API or Agents SDK so your AI agents can manage shipping tasks, including comparing rates, creating shipments, buying labels, scheduling pickups, and tracking deliveries all through natural language.

Compatibility: This integration works with the Responses API and Agents SDK today. Direct integration with the ChatGPT consumer UI (chat.openai.com) requires OAuth support..

Before You Begin

You'll need:

Access to the OpenAI Responses API or Agents SDK
Access to your Easyship Dashboard
An Easyship account (API access is available on all plans at no extra cost)

Step 1: Get Your Easyship API Token

Go to your Easyship Dashboard and click Connect
Click New Integration
Scroll down to API Integration
Under Integration Type, select I am developing a custom integration
Name the key Easyship MCP for easy reference
Keep the default version 2024-09 and click Connect
On the next page, click Access Token and copy it using the copy button

Required scopes: Your API token must include the following scopes. Missing scopes will cause some tools to fail while others continue to work.

public.shipment:read              public.shipment:write
public.label:write                public.pickup:read
public.pickup:write               public.address_validation:write
public.address_validation_domestic:write
public.shipment_document:read     public.transaction_record:read
public.analytics:read             public.rate:read
public.track:read

You can check and update scopes at any time in Dashboard → Connect → API without creating a new token.

Step 2: Add the Easyship MCP Server to the Responses API

Pass the Easyship MCP server as a tool in your responses.create() call. See the OpenAI MCP tools documentation for full reference.

python

from openai import OpenAI
client = OpenAI()


resp = client.responses.create(
    model="gpt-4.1",
    tools=[{
        "type": "mcp",
        "server_label": "easyship",
        "server_url": "https://mcp.easyship.com/mcp",
        "require_approval": "never",
        "headers": {
            "Authorization": "Bearer YOUR_EASYSHIP_TOKEN"
        }
    }],
    input="What are the cheapest shipping options from HK to NYC for a 1.5kg package?"
)


print(resp.output_text)

Replace YOUR_EASYSHIP_TOKEN with the API token you copied in Step 1.

Note: require_approval: "never" tells the model to call Easyship tools automatically without pausing for confirmation. Set it to "always" if you want the model to prompt for approval before taking actions such as creating shipments or buying labels.

Security: Never hardcode your API token in source code or share it in a chat window. Store it as an environment variable (e.g. EASYSHIP_API_ACCESS_TOKEN) and reference it at runtime. If you accidentally expose it, revoke and rotate your key immediately in the Easyship Dashboard under Connect → API.

Step 3: Verify the Connection

Run your script. If the Easyship MCP server is connected correctly, the model will call Easyship tools automatically and return shipping results in resp.output_text.

If you see a connection or authentication error, double-check your token and confirm all required scopes are enabled in the Easyship Dashboard.

Step 4: Try It Out

Once connected, try a prompt like:

I want to ship a parcel from New York, USA to Toronto, Canada. Origin: 350 5th Avenue, New York, US 10001. Destination: 220 Yonge Street, Toronto, ON, Canada M5B 2H1. Parcel: 1.98 lb, 6 × 4 × 2 cm. Item: Business documents, quantity 1, HS Code 4911.99, declared value $1.00 USD, category documents, DDU. Show me the cheapest and best value shipping options with delivery times and courier names.

For a full list of available tools and workflows, see the Easyship MCP Developer Docs.

ChatGPT Consumer UI — Coming Soon

Direct integration with the ChatGPT consumer UI at chat.openai.com requires OAuth support. This is not yet available for the Easyship MCP server. Once OAuth is supported, users will be able to connect Easyship directly from the ChatGPT interface without any code.

FAQs

Can I use an existing API token, or do I need a new one?

You can use an existing token from your Easyship account. Just make sure it has all the required scopes listed in Step 1. If some scopes are missing, certain tools will fail while others work.

Does this work with the ChatGPT app or chat.openai.com?

Not yet. The Responses API and Agents SDK integration is available today for developers building with OpenAI. The ChatGPT consumer UI requires OAuth support from the MCP server, which is coming soon.

What does require_approval: "never" do?

This setting tells the OpenAI model to call Easyship MCP tools automatically without pausing to ask for user approval on each tool call. Set it to "always" if you want the model to prompt for confirmation before taking actions like creating shipments or buying labels.

What if the model doesn't call Easyship tools?

Double-check your token and that the server_url is https://mcp.easyship.com/mcp. Make sure the Authorization header value starts with Bearer (with a space) followed by your token. Also confirm all required scopes are enabled in the Easyship Dashboard.

What if not all tools are loaded?

Verify your Easyship API token is valid and active
Confirm all required scopes are enabled in the Easyship Dashboard
Check your network connection from the machine running the script
Check the OpenAI API response for any error messages related to the MCP server

Why is my Easyship API token not working?

Check the scopes for your token in the Easyship Dashboard under Connect → API. A token might work for some actions but fail for others depending on which scopes it has. For full access to all tools, enable all the scopes listed in Step 1.

What happens if I don't grant all the required scopes?

Only the tools that match your granted scopes will work. Other tools will return an error. You can update scopes in the Easyship Dashboard without creating a new token.

Do I need to pay for the Easyship API token?

No. Easyship provides API access across all plans at no extra cost. If you exceed the included API limits for your plan, overage fees may apply. See [pricing plans and included limits].

Can I use the same Easyship token with other clients (Claude, Cursor, etc.)?

Yes. The same Easyship API token works across any MCP client. Be mindful of rate limits and avoid running conflicting operations (like editing the same shipment from two clients at once).