This article explains how to set up the Easyship MCP server in VS Code so you can manage shipping tasks, including comparing rates, creating shipments, buying labels, scheduling pickups, and tracking deliveries directly through GitHub Copilot Chat.
Before You Begin
You'll need:
- A VS Code installation with the GitHub Copilot and GitHub Copilot Chat extensions installed
- 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:readYou 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 VS Code
- In your project root, create or open the file .vscode/mcp.json
- Add the following configuration:
json
{
"servers": {
"easyship": {
"type": "http",
"url": "https://mcp.easyship.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}- Replace YOUR_TOKEN with the API token you copied in Step 1
Note: This configuration is project-scoped — the Easyship MCP server will only be available when this project is open. To make it available across all projects, add the same configuration to your User Settings: open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P), search for Preferences: Open User Settings (JSON), and add the mcp.servers block there.
Security: Never share your API token in a chat window or commit .vscode/mcp.json to version control. Add .vscode/mcp.json to your .gitignore. If you accidentally expose your token, revoke and rotate it immediately in the Easyship Dashboard under Connect → API.
Step 3: Verify the Connection
- Open the GitHub Copilot Chat panel in VS Code
- Click the Tools icon, or type # to open the tool picker
- Confirm that easyship is listed and its tools are available
If easyship doesn't appear, reload VS Code: open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and run Developer: Reload Window.
Step 4: Try It Out
Once connected, open GitHub Copilot Chat 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.
What if "easyship" doesn't appear in the tool picker?
Double-check that .vscode/mcp.json is saved in your project root and that the JSON is valid. Make sure the Authorization header uses Bearer YOUR_TOKEN with a space between "Bearer" and the token, and there are no extra spaces or line breaks. Reload the VS Code window (Cmd/Ctrl+Shift+P → Developer: Reload Window) if the server doesn't appear immediately.
What if not all tools are loaded?
- Verify your API token is valid and active
- Reload the VS Code window
- Check your network connection
- Make sure you're connecting to https://mcp.easyship.com/mcp
If the issue persists, remove the server entry from .vscode/mcp.json and re-add it.
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.
Is it safe to commit .vscode/mcp.json to version control?
No. The file contains your API token in plain text. Add .vscode/mcp.json to your .gitignore to prevent accidental exposure. For team environments, consider using an environment variable reference instead of hardcoding the 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 (VS Code, 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).
MCP server only works in one project?
The .vscode/mcp.json config is project-scoped. To use Easyship across all projects, add the config to your User Settings instead (Command Palette → Preferences: Open User Settings (JSON)).
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.