Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 0 additions & 5 deletions .env.local.example
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,6 @@ T49_API_BASE_URL=http://localhost:3000/v2
# WORKOS_MCP_RESOURCE=https://<your-https-tunnel-url> # must equal the WorkOS Resource Indicator
# T49_CONNECTED_CLIENTS_RESOLVE_SECRET=<must match your local t49>

# --- Toolsets (see packages/mcp/README.md#toolsets) ---
# T49_MCP_TOOLSETS=core,documents,operations,trade
# T49_MCP_READ_ONLY=false
# T49_MCP_ALLOW_SHARED_TOKEN_WRITES=false

# --- Write confirmation (see packages/mcp/README.md#confirming-writes) ---
# Signs the confirmation tokens that destructive write tools need. Use at least
# 32 random characters, for example from `openssl rand -hex 32`. Without it,
Expand Down
2 changes: 1 addition & 1 deletion MCP_README.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@ Search for bill of lading 123456789
| `get_trade_breakdown` | Nested totals over one to three dimensions (trade intelligence) |
| `get_trade_data_coverage` | Where trade data starts, the latest and last full month (trade intelligence) |

The opt-in `tracking_lifecycle` toolset adds three write tools. A deployment serves them only when `T49_MCP_TOOLSETS` lists `tracking_lifecycle`. `stop_shipment_tracking` and `cancel_tracking_request` return a preview first and change data only after you approve it. A client that declares MCP 2026-07-28 form elicitation shows an `input_required` dialog and asks you to confirm. Any other client gets the preview and a `confirmation_token`, and sends the token back on a second call after you approve. See [Confirming writes](packages/mcp/README.md#confirming-writes).
The `tracking_lifecycle` toolset adds three write tools, and every session serves them. `stop_shipment_tracking` and `cancel_tracking_request` return a preview first and change data only after you approve it. A client that declares MCP 2026-07-28 form elicitation shows an `input_required` dialog and asks you to confirm. Any other client gets the preview and a `confirmation_token`, and sends the token back on a second call after you approve. See [Confirming writes](packages/mcp/README.md#confirming-writes).

| Tool | Description |
|------|-------------|
Expand Down
32 changes: 1 addition & 31 deletions api/mcp.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,6 @@ import { captureMcpException } from '../packages/mcp/src/sentry.js';
import { protectedResourceMetadataUrl } from '../packages/mcp/src/resource.js';
import { logMcpEvent } from '../packages/mcp/src/logging.js';
import type { McpCredentialType } from '../packages/mcp/src/tools/context.js';
import type { ToolSelection } from '../packages/mcp/src/tools/registry.js';
import {
READ_ONLY_HEADER,
resolveToolSelection,
ToolSelectionRequestError,
TOOLSETS_HEADER,
} from '../packages/mcp/src/toolsets.js';

type RequestLike = {
method?: string;
Expand Down Expand Up @@ -58,7 +51,7 @@ function setCorsHeaders(res: ResponseLike): void {
res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
res.setHeader(
'Access-Control-Allow-Headers',
`Content-Type, Authorization, X-Account-ID, X-T49-Credential-Type, ${TOOLSETS_HEADER}, ${READ_ONLY_HEADER}, MCP-Protocol-Version, Mcp-Method, Mcp-Name, Mcp-Session-Id`,
'Content-Type, Authorization, X-Account-ID, X-T49-Credential-Type, MCP-Protocol-Version, Mcp-Method, Mcp-Name, Mcp-Session-Id',
);
}

Expand Down Expand Up @@ -678,30 +671,9 @@ export default async function handler(
};
}

let toolSelection: ToolSelection;
try {
toolSelection = resolveToolSelection({
env: process.env,
credentialType: resolvedTerminal49Auth.credentialType,
toolsetsHeader: getHeaderValue(req.headers['x-t49-mcp-toolsets']),
readOnlyHeader: getHeaderValue(req.headers['x-t49-mcp-read-only']),
});
} catch (error) {
if (!(error instanceof ToolSelectionRequestError)) {
throw error;
}
res.status(400).json({ error: 'Bad Request', message: error.message });
logLifecycle('mcp.request.complete', requestId, {
reason: 'invalid_tool_selection',
});
return;
}

logLifecycle('mcp.request.auth', requestId, {
auth_source: resolvedTerminal49Auth.authSource,
credential_type: resolvedTerminal49Auth.credentialType,
toolsets: [...toolSelection.toolsets],
read_only: String(toolSelection.readOnly),
});

setCorsHeaders(res);
Expand All @@ -727,8 +699,6 @@ export default async function handler(
transport: 'http',
authSource: resolvedTerminal49Auth.authSource,
credentialType: resolvedTerminal49Auth.credentialType,
toolsets: toolSelection.toolsets,
readOnly: toolSelection.readOnly,
// Serverless instances share no memory, so HTTP has no fallback
// secret: without this env var, tier C tools refuse to write.
confirmationSecret: process.env.T49_MCP_CONFIRMATION_SECRET,
Expand Down
38 changes: 37 additions & 1 deletion chatgpt-app-submission.json
Original file line number Diff line number Diff line change
Expand Up @@ -367,6 +367,42 @@
"open_world_justification": "Changes only records in the user's own Terminal49 account; does not publish content or change public or third-party systems.",
"destructive_justification": "Removing a reference number or tag takes it off the record, so searches, filters, and integrations that use it stop finding the record. A call that removes anything never changes anything on its first call: it builds a preview of the lists now and after, and the user approves it before the change is made, either in a confirmation dialog the client shows (MCP form elicitation) or by approving the preview in the chat so the client can call again with the confirmation token from that preview. A call that only adds runs at once and keeps every value already there. The record is not deleted."
}
},
"stop_shipment_tracking": {
"annotations": {
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
},
"justifications": {
"read_only_justification": "Stops carrier and terminal updates for a shipment in the user's own account; it changes tracking state, so it is not read-only.",
"open_world_justification": "Changes only tracking state in the user's own Terminal49 account; does not publish content or change third-party systems.",
"destructive_justification": "Stopping tracking halts the updates the user was receiving. It is reversible with resume_shipment_tracking, and the user must approve a preview first."
}
},
"resume_shipment_tracking": {
"annotations": {
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": false
},
"justifications": {
"read_only_justification": "Resumes tracking for a shipment the user previously stopped in their own account; it changes tracking state, so it is not read-only.",
"open_world_justification": "Changes only tracking state in the user's own Terminal49 account; does not publish content or change third-party systems.",
"destructive_justification": "Re-enables tracking for a shipment the user already tracks; it does not delete or overwrite data."
}
},
"cancel_tracking_request": {
"annotations": {
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true
},
"justifications": {
"read_only_justification": "Cancels a pending tracking request in the user's own account; it changes request state, so it is not read-only.",
"open_world_justification": "Changes only records in the user's own Terminal49 account; does not publish content or change third-party systems.",
"destructive_justification": "Cancelling a pending request discards it and cannot be undone; the user must approve a preview first."
}
}
},
"test_cases": [
Expand Down Expand Up @@ -396,7 +432,7 @@
},
{
"description": "List the 10 most recently updated shipments without nested containers.",
"user_prompt": "Show my 10 most recently updated shipments. Don’t include nested containers.",
"user_prompt": "Show my 10 most recently updated shipments. Don\u2019t include nested containers.",
"file_attachment_urls": null,
"tools_triggered": "list_shipments",
"expected_output": "Returns up to 10 of the most recently updated shipments with a page size of 10, include_containers=false, no carrier, status, or port filters, and no nested containers. Mentions pagination if present.",
Expand Down
3 changes: 3 additions & 0 deletions claude-connector-submission.json
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
"icon": "public/store-icons/terminal49-light.png",
"icon_dark": "public/store-icons/terminal49-dark.png",
"tool_names": [
"cancel_tracking_request",
"get_container",
"get_container_route",
"get_document",
Expand All @@ -42,12 +43,14 @@
"list_shipments",
"list_tracking_requests",
"rank_importers",
"resume_shipment_tracking",
"search_commodities",
"search_container",
"search_docs",
"search_importers",
"set_custom_field",
"set_party_role",
"stop_shipment_tracking",
"summarize_containers",
"track_container",
"update_record",
Expand Down
9 changes: 3 additions & 6 deletions docs/api-docs/in-depth-guides/mcp.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -163,7 +163,7 @@ Once configured, verify everything works:
<Step title="Ask Claude to list tools">
> "List the tools available in the Terminal49 MCP server."

Claude should respond with a list of 30 tools including `search_container`, `track_container`, the list tools, and the trade intelligence tools.
Claude should respond with a list of 33 tools including `search_container`, `track_container`, the list tools, and the trade intelligence tools.
</Step>
<Step title="Search for a test container">
> "Using the Terminal49 MCP server, search for container TCLU1234567 and summarize its status."
Expand Down Expand Up @@ -236,7 +236,7 @@ printf '%s\n' \
| `search_docs` | Search the public Terminal49 documentation | `query: string`, `limit?` (1-10, default 5) |
| `whoami` | Identify the credential, its account, available features, and the session's toolsets | none |

The `operations` toolset adds `set_party_role` and `set_custom_field` and is in the default toolsets. Send `X-T49-MCP-Toolsets: core,documents,trade` to leave them out. The `tracking_lifecycle` toolset adds `stop_shipment_tracking`, `resume_shipment_tracking` and `cancel_tracking_request`; a deployment serves it only when `T49_MCP_TOOLSETS` lists it.
The `operations` toolset holds `set_party_role`, `set_custom_field` and `update_record`. The `tracking_lifecycle` toolset holds `stop_shipment_tracking`, `resume_shipment_tracking` and `cancel_tracking_request`. Every session serves every registered tool; toolsets are grouping labels, not switches.

| Tool | Description | Parameters |
|------|-------------|------------|
Expand Down Expand Up @@ -366,9 +366,6 @@ The `vercel.json` configures the MCP server (excerpt):
| `T49_API_BASE_URL` | No | Override API URL (default: `https://api.terminal49.com/v2`) |
| `T49_MCP_ALLOWED_HOSTS` | No | Comma-separated host allowlist for request Host validation |
| `T49_MCP_ALLOWED_ORIGINS` | No | Comma-separated origin allowlist for request Origin validation |
| `T49_MCP_TOOLSETS` | No | Comma-separated toolsets the server allows; defaults to `core,documents,operations,trade`. An unknown name or a value made only of commas stops stdio and fails HTTP requests |
| `T49_MCP_READ_ONLY` | No | Serves only read-only tools when set to `true` or `1`; defaults to `false` |
| `T49_MCP_ALLOW_SHARED_TOKEN_WRITES` | No | Serves toolsets other than `core` and `trade` when callers share `T49_API_TOKEN`; defaults to `false` |
| `T49_MCP_CONFIRMATION_SECRET` | For write tools over HTTP | Signs the preview approvals that `stop_shipment_tracking`, `cancel_tracking_request`, and a destructive `set_party_role` or `set_custom_field` call need, on both the elicitation and the token channel. Use at least 32 random characters. Without it, those tools change nothing over HTTP. Local stdio makes a random secret when it is unset |
| `SENTRY_DSN` | No | Enables Sentry MCP Monitoring |
| `SENTRY_ENVIRONMENT` | No | Sentry environment name; defaults to `NODE_ENV` |
Expand All @@ -378,7 +375,7 @@ The `vercel.json` configures the MCP server (excerpt):
| `SENTRY_MCP_RECORD_OUTPUTS` | No | Records MCP outputs in Sentry when set to `true`; defaults to `false` |
| `SENTRY_SEND_DEFAULT_PII` | No | Enables Sentry default PII behavior; defaults to `false` |

Clients can remove tools per request with the `X-T49-MCP-Toolsets` and `X-T49-MCP-Read-Only` headers. A header can only narrow what the env allows. See [Limit the tools](/mcp/home#limit-the-tools).
Every session serves every registered tool, so there are no per-request or per-deployment switches that hide tools. Write safety comes from the write tiers and their preview approvals. See [Toolsets](/mcp/home#toolsets).

---

Expand Down
31 changes: 9 additions & 22 deletions docs/mcp/home.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -132,34 +132,21 @@ See [Other MCP clients](/mcp/setup/other-clients) for details on OAuth discovery

The same [rate limits](/api-docs/in-depth-guides/rate-limiting) apply to MCP endpoints as the REST API.

### Limit the tools
### Toolsets

Two optional request headers reduce the tools your client sees. They can only remove tools.
Every session serves every registered tool. There is no per-request or per-deployment tool hiding, so the tools below are all always available.

- `X-T49-MCP-Read-Only: true` lists only read-only tools. It removes `track_container` and every write tool.
- `X-T49-MCP-Toolsets` takes a comma-separated list of toolsets.
The tools group into toolsets, which are labels for documentation and for the `whoami` report, not switches:

The toolset names are:

- `core`: every tool except the document reads, the write tools below, and the trade intelligence tools. `whoami` reports the toolsets a session serves.
- `core`: every tool except the document reads, the write tools below, and the trade intelligence tools. `whoami` reports the toolsets that have tools.
- `documents`: `list_documents` and `get_document`.
- `operations`: `set_party_role`, `set_custom_field` and `update_record`. It is in the default toolsets. Send `X-T49-MCP-Toolsets: core,documents,trade` to keep every other tool without them.
- `tracking_lifecycle`: `stop_shipment_tracking`, `resume_shipment_tracking` and `cancel_tracking_request`. It is not in the default toolsets; a deployment serves it only when `T49_MCP_TOOLSETS` lists it.
- `operations`: `set_party_role`, `set_custom_field` and `update_record`.
- `tracking_lifecycle`: `stop_shipment_tracking`, `resume_shipment_tracking` and `cancel_tracking_request`.
- `documents_write`: no tools yet.
- `developer`: no tools yet.
- `trade`: the [trade intelligence tools](#trade-intelligence-tools).

```json
{
"url": "https://mcp.terminal49.com",
"headers": {
"Authorization": "Token YOUR_API_KEY",
"X-T49-MCP-Read-Only": "true"
}
}
```

The read-only header accepts `true`, `false`, `1` or `0`, in any case. Any other read-only value, an unknown toolset name, or a toolsets value made only of commas returns `400 Bad Request`.
Write safety does not come from hiding tools. Each write tool carries annotations and a tier: additive writes (tier A) run in one call, and destructive writes (tier C) always show a preview the user must approve before anything changes.

---

Expand All @@ -180,7 +167,7 @@ Each call to a write tool, `track_container` included, logs one `mcp.write.audit
## Tools reference

<Note>
In the default toolsets, every tool is read-only except `track_container` and the write tools in the `operations` toolset, which are described under [Write tools](#write-tools). `track_container` creates a tracking request. If your account already has an in-progress tracking request for the number, or a container with that number that is still being tracked, `track_container` returns it instead of creating a new request. A container whose shipment has stopped tracking does not count. A request is in progress while its status is `pending` or `awaiting_manifest`. When you pass `scac`, only an in-progress request under that SCAC counts. Failed or cancelled requests do not block a new one.
Every tool is read-only except `track_container` and the write tools in the `operations` toolset, which are described under [Write tools](#write-tools). `track_container` creates a tracking request. If your account already has an in-progress tracking request for the number, or a container with that number that is still being tracked, `track_container` returns it instead of creating a new request. A container whose shipment has stopped tracking does not count. A request is in progress while its status is `pending` or `awaiting_manifest`. When you pass `scac`, only an in-progress request under that SCAC counts. Failed or cancelled requests do not block a new one.
</Note>

### `search_container`
Expand Down Expand Up @@ -840,7 +827,7 @@ Extracted data and the source email are text that people outside your account wr

### Write tools

Seven tools can change your account's data. `track_container` is in the default `core` toolset. The `operations` toolset, which is in the default toolsets, holds `set_party_role`, `set_custom_field` and `update_record`. The `tracking_lifecycle` toolset, which a deployment serves only when `T49_MCP_TOOLSETS` lists it, holds `stop_shipment_tracking`, `resume_shipment_tracking`, and `cancel_tracking_request`. Each write tool has a tier:
Seven tools can change your account's data, and every session serves all of them. `track_container` is in the `core` toolset. The `operations` toolset holds `set_party_role`, `set_custom_field` and `update_record`. The `tracking_lifecycle` toolset holds `stop_shipment_tracking`, `resume_shipment_tracking`, and `cancel_tracking_request`. Each write tool has a tier:

- **Tier A** tools run in one call. Starting or resuming tracking consumes tracking quota and may incur pay-as-you-go charges. These additive tools explain that consequence in their descriptions; your client controls its permission UI.

Expand Down
Loading
Loading