How to Connect Codex CLI to the Easyship MCP Server

This article explains how to set up the Easyship MCP server in Codex CLI so you can manage shipping tasks, including comparing rates, creating shipments, buying labels, scheduling pickups, and tracking deliveries all through natural language.

Before You Begin

You'll need:

• Codex CLI installed with Node.js 18+
• 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

1. Go to your Easyship Dashboard and click Connect
2. Click New Integration
3. Scroll down to API Integration
4. Under Integration Type, select I am developing a custom integration
5. Name the key Easyship MCP for easy reference
6. Keep the default version 2024-09 and click Connect
7. 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 Codex CLI

1. Add the following to ~/.codex/config.toml:

toml

[mcp_servers.easyship]
url = "https://mcp.easyship.com/mcp"
bearer_token_env_var = "EASYSHIP_API_ACCESS_TOKEN"

2. Set the environment variable in your terminal:

bash

export EASYSHIP_API_ACCESS_TOKEN="YOUR_TOKEN"

3. To make this persist across terminal sessions, add it to your shell profile:

bash

# For bash
echo 'export EASYSHIP_API_ACCESS_TOKEN="YOUR_TOKEN"' >> ~/.bashrc
source ~/.bashrc


# For zsh (macOS default)
echo 'export EASYSHIP_API_ACCESS_TOKEN="YOUR_TOKEN"' >> ~/.zshrc
source ~/.zshrc

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

Note: The bearer_token_env_var field tells Codex to read your token from an environment variable at runtime, rather than storing it directly in the config file. This means you can safely commit ~/.codex/config.toml without exposing your credentials.

Security: Never share your API token in the chat window. If you accidentally expose it, revoke and rotate your key immediately in the Easyship Dashboard under Connect → API.

Step 3: Verify the Connection

1. Start a Codex CLI session by running codex
2. Confirm easyship tools are available in your session
3. Confirm all tools are successfully loaded

If you get an authentication error, verify the environment variable is set correctly:

bash

echo $EASYSHIP_API_ACCESS_TOKEN

Step 4: Try It Out

Start a Codex CLI session and 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.

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.

Why does Codex CLI use an environment variable instead of the token directly? 

The bearer_token_env_var field in config.toml tells Codex to read the token from an environment variable at runtime, rather than storing it in the config file. This means you can safely commit ~/.codex/config.toml without exposing your credentials.

What if Easyship tools don't appear in my session? 

Check that EASYSHIP_API_ACCESS_TOKEN is exported in your shell before starting Codex (run echo $EASYSHIP_API_ACCESS_TOKEN to verify). Also confirm the [mcp_servers.easyship] block is correctly formatted in ~/.codex/config.toml and that the URL is https://mcp.easyship.com/mcp.

What if not all tools are loaded?

• Verify your API token is valid and active
• Confirm the environment variable is set in the same shell session
• Check your network connection
• Verify all required scopes are enabled in the Easyship Dashboard

Why is my 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, and the agent will tell you which scope is needed. You can update scopes in the Easyship Dashboard without creating a new token.

Do I need to pay for the 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 token across multiple clients (Codex CLI, Cursor, Claude, etc.)? 

Yes. The same 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).

Codex CLI says 'EASYSHIP_API_ACCESS_TOKEN not set'? 

The environment variable must be set in the same terminal session where you run codex. If you added it to ~/.bashrc or ~/.zshrc, run source ~/.bashrc (or source ~/.zshrc) to reload, or open a new terminal window.

Need Further Assistance?

If you're experiencing an error that isn't covered above, submit a bug report. Include the tool name, error code, and request ID from the error response - these help us diagnose the issue faster.