Architecture & Authentication

Authentication

Agents authenticate using a standard Shipwell API token passed in the Authorization header on every request:

Authorization: Bearer YOUR_SHIPWELL_API_TOKEN

No tokens are stored on the MCP server. Authentication is stateless and per-request — the server forwards the token to the Shipwell API and returns the result. If your token is revoked or rotated in Shipwell, it takes effect immediately with no MCP-side changes needed.

Hosted Deployment

The production MCP Server is hosted behind HTTPS:

• Stateless — no session state, no server-side token storage
• Horizontally scalable — each request is fully independent
• HTTPS only — all traffic is encrypted in transit

Local Deployment (Stdio)

You can also run the MCP server as a local stdio process. This is useful for individual developer setups or environments where outbound HTTPS to the hosted server is not permitted.

Set your token as an environment variable:

export SHIPWELL_API_TOKEN=your_token_here

Then configure your AI client to launch the server process via stdio. Refer to your client's MCP documentation for the exact config format.

Security Model

• The server acts as a pass-through proxy — it holds no Shipwell credentials of its own
• Write tools are disabled by default (see Safety & Write Access )
• Each tool documents its side effects, preconditions, and risk level so agents can reason safely before acting