Safety & Write Access

Read-Only by Default

The hosted Shipwell MCP Server ships with all write tools disabled. Out of the box, your AI assistant can query and read any data your token has access to, but it cannot create, update, or delete anything.

This is intentional — AI agents should not be able to mutate production freight data without an explicit decision to enable that capability. Read-only access requires no additional configuration beyond a valid Shipwell API token.

Note

Even with write access enabled at the account level, the actual permissions available to the AI are bounded by the Shipwell platform permissions set on the user whose token you supply. If that user cannot edit shipments in the Shipwell app, the AI cannot edit them through MCP either. See Best Practices for how to set this up with a dedicated integration user.

Enabling Write Access

Write access must be explicitly enabled — it is not on by default, even if your account supports it. Contact your Shipwell account representative to turn on write tools for your account.

Once enabled, write tools become available automatically to agents authenticating with your API token. Write tools cover:

Creating and updating shipments, stops, and carrier assignments
Creating and updating orders
Creating notes and messages
Full CRUD on facilities, dock appointments, routing guides, and custom fields

Contact your Shipwell account representative to enable write access.

Dry-Run Mode

Before enabling live writes, use dry-run mode to simulate any write operation without side effects:

Copy

Copied

SHIPWELL_MCP_DRYRUN=true

In dry-run mode the agent runs in full simulation — every write tool executes its pre-flight checks and planning logic but makes no actual API calls. Each simulated operation returns a structured risk report:

Identified side effects
Required state preconditions
Risk level: low / medium / high / critical

Use dry-run to build confidence in your agent's behavior before touching real freight data.

Agent-Safe Tool Design

Every write tool in the Shipwell MCP Server explicitly documents:

Side effects — what downstream state changes to expect
State preconditions — what must be true before the operation is valid
Risk level — one of low , medium , high , or critical

This metadata is surfaced to the AI agent at tool-discovery time, so the agent can reason about consequences before acting.

State Machine Reference

The server includes built-in tools and a machine-readable JSON resource that describe valid state transitions, locked fields, and side effects for every shipment, stop, and order status. Agents can call get_shipment_state_info (and equivalent tools for stops and orders) to check what actions are permitted before attempting a write.

This prevents the agent from attempting invalid transitions — for example, trying to assign a carrier to a shipment that is already delivered.