Agents & orchestration

A late delivery claim settled on the record

A road haulier receives a claim over a late delivery. Answering it means cross-checking shipment tracking, the transport contract and the penalty schedule, across three tools that do not talk to each other. This case is invented.

Invented caseThis case is not an engagement. It is invented end to end, and the code below is the real code that would run it.

1. Human·The claim arrives

   The claims desk writes: the customer on shipment EXP-48231 is complaining. They say the delivery landed at the end of the day, when the contract promises noon. Is the late penalty owed, and what goes back to them?

2. The agent·Choosing the tool

   Three MCP servers are connected: shipment tracking, contract management, invoicing. I start from tracking, because the penalty is computed on field timestamps, not on an invoice. I rule out invoicing: it carries the amount billed, nothing about the promised slot or what happened at the dock.

   I rule the third tool out for a stated reason, not because it was never found.

3. Tool call·Calling tracking

   {
     "jsonrpc": "2.0",
     "id": 7,
     "method": "tools/call",
     "params": {
       "name": "read_shipment_tracking",
       "arguments": {
         "reference": "EXP-48231"
       }
     }
   }

4. Tool response·Server response

   {
     "jsonrpc": "2.0",
     "id": 7,
     "result": {
       "content": [
         {
           "type": "text",
           "text": "{\"reference\": \"EXP-48231\", \"customer\": \"CL-7742\", \"contractual_slot\": \"2026-08-25T12:00:00+02:00\", \"events\": [{\"timestamp\": \"2026-08-24T06:12:00+02:00\", \"code\": \"PICKUP\", \"site\": \"north-dock\", \"reason\": null}, {\"timestamp\": \"2026-08-25T11:48:00+02:00\", \"code\": \"DELIVERY_ATTEMPT\", \"site\": \"customer-site\", \"reason\": \"dock unavailable\"}, {\"timestamp\": \"2026-08-25T19:41:00+02:00\", \"code\": \"DELIVERY\", \"site\": \"customer-site\", \"reason\": null}]}"
         }
       ],
       "structuredContent": {
         "reference": "EXP-48231",
         "customer": "CL-7742",
         "contractual_slot": "2026-08-25T12:00:00+02:00",
         "events": [
           {
             "timestamp": "2026-08-24T06:12:00+02:00",
             "code": "PICKUP",
             "site": "north-dock",
             "reason": null
           },
           {
             "timestamp": "2026-08-25T11:48:00+02:00",
             "code": "DELIVERY_ATTEMPT",
             "site": "customer-site",
             "reason": "dock unavailable"
           },
           {
             "timestamp": "2026-08-25T19:41:00+02:00",
             "code": "DELIVERY",
             "site": "customer-site",
             "reason": null
           }
         ]
       },
       "isError": false
     }
   }

   The caller's token must carry the read scope on shipments. Without it, the same call returns an error, not a record.

5. The agent·The cross-check, then the stop

   Two reads follow on the same channel: the transport contract, then the penalty schedule. The contract sets the slot at noon. Tracking shows a first delivery attempt at 11:48, turned away because the customer's dock was unavailable. So the article 8 penalty does not trigger: the delay is not on the carrier. A goodwill gesture is still on the table, and that is where I stop. No write tool is exposed to me: I draft the offer, I do not grant it.

   The agent cannot issue a credit note, even by mistake: the server exposes reads only.

6. Answer·What comes back

   The answer goes back to the claims desk. The penalty is not owed: the first delivery attempt falls inside the contractual slot, and the refusal comes from the receiving dock. Sources cited, in order: tracking EXP-48231, transport contract, article 8 of the schedule. Proposal held for human approval: a goodwill gesture on the next shipment, for the desk to grant or refuse. Nothing is written to invoicing until someone decides.

from dataclasses import asdict, dataclass

from fastmcp import FastMCP
from fastmcp.exceptions import ToolError
from fastmcp.server.dependencies import get_access_token

mcp = FastMCP("transport-claims")

SCOPE_BY_DOMAIN = {"shipments": "claims:shipments:read"}


@dataclass(frozen=True)
class Event:
    timestamp: str
    code: str
    site: str
    reason: str | None = None


RECORDS = {
    "EXP-48231": {
        "customer": "CL-7742",
        "domain": "shipments",
        "contractual_slot": "2026-08-25T12:00:00+02:00",
        "events": [
            Event("2026-08-24T06:12:00+02:00", "PICKUP", "north-dock"),
            Event("2026-08-25T11:48:00+02:00", "DELIVERY_ATTEMPT", "customer-site", "dock unavailable"),
            Event("2026-08-25T19:41:00+02:00", "DELIVERY", "customer-site"),
        ],
    }
}


@mcp.tool()
def read_shipment_tracking(reference: str) -> dict:
    """Return the tracking events of a shipment, read only."""
    record = RECORDS.get(reference)
    if record is None:
        raise ToolError(f"unknown reference: {reference}")
    token = get_access_token()
    # A missing token counts as a refusal: otherwise the guard falls and the record leaves its department.
    if token is None or SCOPE_BY_DOMAIN[record["domain"]] not in set(token.scopes):
        raise ToolError(f"read denied on record {reference}")
    return {
        "reference": reference,
        "customer": record["customer"],
        "contractual_slot": record["contractual_slot"],
        "events": [asdict(e) for e in record["events"]],
    }


# No write tool is exposed: a goodwill gesture stays a human decision.
if __name__ == "__main__":
    mcp.run(transport="http")

I do not give an agent write access to a business system: here it reads three of them, proposes a goodwill gesture, and stops there, because no tool lets it grant one.