Skip to content
Merged
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
4 changes: 2 additions & 2 deletions docs/mcp/home.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -842,9 +842,9 @@ Extracted data and the source email are text that people outside your account wr

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:

- **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 carry a client interaction hint and explain that consequence; your client controls its permission UI.
- **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.

- **Tier C** tools need your approval of a preview. They are marked destructive, and they carry `_meta["anthropic/requiresUserInteraction"]`, to request user interaction in clients that support this hint. `stop_shipment_tracking` and `cancel_tracking_request` ask on every call. `set_party_role` and `set_custom_field` change up to 50 records per call. They ask only when a record in the call would lose a party or a value. A call that only adds runs at once. `update_record` works the same way on one record: adding reference numbers or tags runs at once, and removing any asks first.
- **Tier C** tools need your approval of a preview. They are marked destructive. `stop_shipment_tracking` and `cancel_tracking_request` ask on every call. `set_party_role` and `set_custom_field` change up to 50 records per call. They ask only when a record in the call would lose a party or a value. A call that only adds runs at once. `update_record` works the same way on one record: adding reference numbers or tags runs at once, and removing any asks first.

A call that needs your approval never changes anything the first time. It reads the record, or every record in the batch, and builds a preview of the record now and after the change. For a batch, the preview lists each record that changes and counts the rest, and one approval covers the whole call. How you approve the preview depends on your AI client.

Expand Down
5 changes: 4 additions & 1 deletion packages/mcp/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Fixed
- Write tools no longer carry `_meta["anthropic/requiresUserInteraction"]`. Claude hid the "Always allow" permission for every tool with that key, so bulk loads (tracking plus custom fields) needed a manual approval on every call. Writes that would lose a value or a party still ask through the preview flow.

### Changed
- `get_container` always returns every transport event in `events.timeline` (oldest first, with vessel, voyage, location, `invalidated_at`, and `reported_at`), instead of a count and the event with the largest timestamp. That event was often a far-out estimate on another voyage, so agents quoted a stale ETA. `events.latest_event` is gone; `include: ["transport_events"]` is accepted and changes nothing. When estimates for the same milestone conflict, the one with the latest `reported_at` is current.
- `set_party_role` and `set_custom_field` are tier C tools that ask for the user's approval only when a record in the call would lose a party or a value. `add`, a `replace` that detaches nobody, and filling empty fields run at once. `remove`, a `replace` that detaches another party, and overwriting or clearing a value return one preview of every record that changes in the batch, and write after the user approves it on either confirmation channel. The approval is bound to the state of every record read, so a change to any of them re-asks. A `remove` whose `party_id` matches no role while the record holds another party in that role fails with guidance instead of reporting `unchanged`; a `party_id` Terminal49 does not know stops the call as `party_not_found`.
Expand All @@ -15,7 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- `get_container_transport_events`. `get_container` returns the same timeline in `events.timeline`.

### Added
- Tier C write tools (`stop_shipment_tracking`, `cancel_tracking_request`) confirm with the user through MCP 2026-07-28 form elicitation when the request declares it: the first call returns `input_required` with the preview and a signed `requestState`, the client asks the user, and the write runs only on their accept. A `confirmation_token` on such a request is refused (`token_not_accepted`), and a decline returns `status: "declined"`. Other clients keep the preview-then-token flow. Tier C tools now carry `_meta["anthropic/requiresUserInteraction"]: true`, so Claude Code prompts on every call.
- Tier C write tools (`stop_shipment_tracking`, `cancel_tracking_request`) confirm with the user through MCP 2026-07-28 form elicitation when the request declares it: the first call returns `input_required` with the preview and a signed `requestState`, the client asks the user, and the write runs only on their accept. A `confirmation_token` on such a request is refused (`token_not_accepted`), and a decline returns `status: "declined"`. Other clients keep the preview-then-token flow.
- Trade intelligence tools for US ocean import market data (US Customs bill-of-lading records, January 2022 onward): `search_importers`, `get_importer_profile`, `search_commodities`, `rank_importers`, `get_trade_trends`, `get_trade_breakdown`, and `get_trade_data_coverage`. All are read-only and gated per account; without the feature they reply that trade intelligence isn't enabled instead of failing. Responses are compacted (rounded numbers, capped lists, internal fields dropped), and the tool descriptions and server instructions carry the data caveats agents need. Record-level container and bill of lading lookups stay out of MCP.

### Fixed
Expand Down
4 changes: 2 additions & 2 deletions packages/mcp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -462,11 +462,11 @@ Each tool belongs to one toolset in `src/tools/registry.ts`: `core`, `documents`

### Confirming writes

Clients own the permission UI. The server supplies write annotations, consequence descriptions and preview flows so clients and models can distinguish consequential actions even when routine tool calls are auto-approved. Additive does not mean free: `track_container` and `resume_shipment_tracking` consume tracking quota and may incur pay-as-you-go charges. Both carry the client interaction hint without being mislabeled destructive; explain the cost consequence before acting. The hint's effect depends on the client.
Clients own the permission UI. The server supplies write annotations, consequence descriptions and preview flows so clients and models can distinguish consequential actions even when routine tool calls are auto-approved. Additive does not mean free: `track_container` and `resume_shipment_tracking` consume tracking quota and may incur pay-as-you-go charges. Neither is marked destructive; their descriptions explain the cost consequence before acting.

State checks are best-effort reads, not atomic preconditions on the Terminal49 write. A concurrent edit after the check can still be overwritten, including a field classified as empty before another writer fills it. Preventing that race requires backend conditional writes.

Each write tool has a tier in the registry. A tier A tool, such as `resume_shipment_tracking`, is additive or reversible and runs in one call. Its result names the tool that undoes it. A tier C tool, such as `stop_shipment_tracking` or `cancel_tracking_request`, has `destructiveHint: true`, carries `_meta["anthropic/requiresUserInteraction"]: true` to request interaction in clients that support this hint, and needs the user's approval of a preview. Its first call never writes. It reads the record, builds a `preview` with `current`, `proposed` and `reach`, and issues a confirmation token: an HMAC-SHA256, keyed with `T49_MCP_CONFIRMATION_SECRET`, over the channel, the tool name, the other arguments, the account, the credential, an expiry five minutes out, a random nonce and a fingerprint of the record fields the preview showed. Which channel carries the token depends on the request.
Each write tool has a tier in the registry. A tier A tool, such as `resume_shipment_tracking`, is additive or reversible and runs in one call. Its result names the tool that undoes it. A tier C tool, such as `stop_shipment_tracking` or `cancel_tracking_request`, has `destructiveHint: true` and needs the user's approval of a preview. Its first call never writes. It reads the record, builds a `preview` with `current`, `proposed` and `reach`, and issues a confirmation token: an HMAC-SHA256, keyed with `T49_MCP_CONFIRMATION_SECRET`, over the channel, the tool name, the other arguments, the account, the credential, an expiry five minutes out, a random nonce and a fingerprint of the record fields the preview showed. Which channel carries the token depends on the request.

**Elicitation channel.** A request whose 2026-07-28 `_meta` envelope declares form elicitation (`io.modelcontextprotocol/clientCapabilities.elicitation.form`, or a bare `elicitation: {}`) gets an `input_required` result per the MCP multi round-trip pattern: one embedded `elicitation/create` request whose message is the preview as text and whose form has one boolean `confirm` field, plus the token as `requestState`. The client shows the user the preview, then retries the call with the user's answer in `inputResponses` and the `requestState` echoed back. The tool verifies the state against the same call, account, credential, expiry and record fingerprint, and:

Expand Down
2 changes: 1 addition & 1 deletion packages/mcp/src/__snapshots__/tools-list.json

Large diffs are not rendered by default.

4 changes: 1 addition & 3 deletions packages/mcp/src/billing-signals.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,7 @@ it('advertises billing consequences and client interaction for tracking writes',
for (const tool of tracking) {
expect(tool.description, tool.name).toMatch(/quota/);
expect(tool.description, tool.name).toMatch(/pay-as-you-go charges/);
expect(tool._meta, tool.name).toMatchObject({
'anthropic/requiresUserInteraction': true,
});
expect(tool._meta, tool.name).toBeUndefined();
expect(tool.annotations, tool.name).toMatchObject({
readOnlyHint: false,
destructiveHint: false,
Expand Down
16 changes: 6 additions & 10 deletions packages/mcp/src/confirmation-protocol.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -249,16 +249,12 @@ describe('confirming a tier C write', () => {
const { tools } = await session.client.listTools();
const byName = new Map(tools.map((tool) => [tool.name, tool]));

expect(byName.get('stop_shipment_tracking')?._meta).toEqual({
'anthropic/requiresUserInteraction': true,
});
expect(byName.get('cancel_tracking_request')?._meta).toEqual({
'anthropic/requiresUserInteraction': true,
});
expect(byName.get('resume_shipment_tracking')?._meta).toEqual({
'anthropic/requiresUserInteraction': true,
});
expect(byName.get('search_container')?._meta).toBeUndefined();
// No tool may carry anthropic/requiresUserInteraction: Claude then drops
// "Always allow", which breaks bulk workflows (DEV-14831). The preview
// flow is what guards a write that loses data.
for (const tool of tools) {
expect(tool._meta, tool.name).toBeUndefined();
}
expect(byName.get('stop_shipment_tracking')?.description).toMatch(
/On a client that can ask the user \(form elicitation\).*never pass confirmation_token there\. On any other client, the first call returns the preview with a confirmation_token/,
);
Expand Down
4 changes: 1 addition & 3 deletions packages/mcp/src/record-writes.transport.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -536,9 +536,7 @@ describe('batch record writes', () => {

for (const name of ['set_party_role', 'set_custom_field']) {
const tool = byName.get(name);
expect(tool?._meta, name).toEqual({
'anthropic/requiresUserInteraction': true,
});
expect(tool?._meta, name).toBeUndefined();
expect(tool?.annotations, name).toMatchObject({
readOnlyHint: false,
destructiveHint: true,
Expand Down
6 changes: 0 additions & 6 deletions packages/mcp/src/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1382,7 +1382,6 @@ export function createTerminal49McpServer(
buildResourceLinks?: (result: unknown) => ResourceLinkContent[],
): ToolRegistrar =>
(definition) => {
const confirmed = definition.tier === 'C';
server.registerTool(
definition.name,
{
Expand All @@ -1394,11 +1393,6 @@ export function createTerminal49McpServer(
annotations: definition.annotations,
inputSchema: spec.inputSchema,
outputSchema: spec.outputSchema,
// Claude Code shows the permission prompt on every call of a tool
// with this key, whatever the permission mode.
...((confirmed || definition.requiresUserInteraction) && {
_meta: { 'anthropic/requiresUserInteraction': true },
}),
},
// SAFETY: the callback takes the parsed output of `spec.inputSchema`,
// which is what ToolCallback<InputArgs> resolves to. TypeScript cannot
Expand Down
4 changes: 0 additions & 4 deletions packages/mcp/src/tools/registry.ts
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,6 @@ interface ToolBase {
title: string;
toolset: Toolset;
annotations: ToolAnnotations;
/** Ask the client to involve the user even for consequential additive writes. */
requiresUserInteraction?: boolean;
}

export type ToolDefinition =
Expand Down Expand Up @@ -76,7 +74,6 @@ export const TOOL_REGISTRY = [
readTool('search_container', 'Search Containers'),
{
name: 'track_container',
requiresUserInteraction: true,
title: 'Track Container',
toolset: 'core',
tier: 'A',
Expand Down Expand Up @@ -159,7 +156,6 @@ export const TOOL_REGISTRY = [
},
{
name: 'resume_shipment_tracking',
requiresUserInteraction: true,
title: 'Resume Shipment Tracking',
toolset: 'tracking_lifecycle',
tier: 'A',
Expand Down
Loading