Best Practices

Use a Dedicated Integration User

For any non-personal or production use of the Shipwell MCP Server, create a dedicated integration user in the Shipwell platform rather than using a personal user's API token. This gives you explicit control over what the AI can and cannot do, independent of any individual's account.

Steps

1. Create an integration user in Shipwell

In the Shipwell app, go to Settings → Users and create a new user account specifically for this integration. Use a name that makes the purpose clear, e.g. mcp-integration or ai-agent.

2. Set permissions on that user

Assign the user only the Shipwell platform permissions it needs. The MCP server can only do what the underlying user is permitted to do in the Shipwell app — if the integration user cannot edit shipments, the AI cannot edit them through MCP either.

Start with read-only permissions and only expand them once you are confident in the agent's behavior. See Safety & Write Access for more on dry-run mode and the write access tier.

3. Generate an API token for the integration user

4. Use that token in your MCP config

Supply the integration user's token in the Authorization header of your MCP server config — not your personal token. See the Quickstart for the config format for each AI client.

Why This Matters

Least privilege — the AI only has the permissions you have explicitly granted, not the full permissions of whoever set it up
Auditability — API calls and actions in Shipwell logs are attributed to the integration user, making it easy to review what the AI did
Safe rotation — you can revoke or rotate the integration token without affecting any individual's access
Shared team use — multiple team members or AI clients can share the integration token without tying access to one person's account