{"componentChunkName":"component---src-templates-simple-markdown-js","path":"/docs/mcp/safety/","matchPath":"","result":{"data":{"markdownRemark":{"html":"

Safety & Write Access

\n

Read-Only by Default

\n

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.

\n

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.

\n
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.

\n

Enabling Write Access

\n

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.

\n

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

\n\n

Contact your Shipwell account representative to enable write access.

\n

Dry-Run Mode

\n

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

\n
\n
\n
Copy
\n
Copied
\n
\n 
SHIPWELL_MCP_DRYRUN=true
\n
\n

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:

\n\n

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

\n

Agent-Safe Tool Design

\n

Every write tool in the Shipwell MCP Server explicitly documents:

\n\n

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

\n

State Machine Reference

\n

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.

\n

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

","headings":[{"value":"Safety & Write Access","depth":1},{"value":"Read-Only by Default","depth":2},{"value":"Enabling Write Access","depth":2},{"value":"Dry-Run Mode","depth":2},{"value":"Agent-Safe Tool Design","depth":2},{"value":"State Machine Reference","depth":2}]},"contentItem":{"data":{"lastModified":"2026-05-14T19:02:55.000Z","enableToc":null,"disableLastModified":null,"tocMaxDepth":null,"requestLogin":false}},"siteConfig":{"enableToc":true,"disableLastModified":false,"tocMaxDepth":4}},"pageContext":{"matchPath":"","id":"c87ccac8-018b-5121-8f3e-2c8a82948699__redocly content/docs/mcp/safety/","seo":{"title":"Safety & Write Access","description":null,"image":"","keywords":null,"jsonLd":null,"lang":null,"siteUrl":null},"pageId":"docs/mcp/safety.md","pageBaseUrl":"/docs/mcp/safety","type":"markdown","toc":{"enable":true,"maxDepth":4,"headings":[{"depth":1,"value":"Safety & Write Access","id":"safety--write-access"},{"depth":2,"value":"Read-Only by Default","id":"read-only-by-default"},{"depth":2,"value":"Enabling Write Access","id":"enabling-write-access"},{"depth":2,"value":"Dry-Run Mode","id":"dry-run-mode"},{"depth":2,"value":"Agent-Safe Tool Design","id":"agent-safe-tool-design"},{"depth":2,"value":"State Machine Reference","id":"state-machine-reference"}]},"data":{"title":""},"catalogInfo":null,"link":"/docs/mcp/safety/","sidebarName":"developerPortal","isLanding":false,"showPrevButton":null,"showNextButton":null,"apiVersions":null,"apiVersionId":null,"isDefaultApiVersion":null}},"staticQueryHashes":["1123603147","1302185487","1344209882","1398840060","1520077861","1975142765","2667623876","2950305614","3240152602","3743992808","561138138"]}