Cooperative request cancellation for long-running tools.

MCP clients can abort an in-flight request by sending notifications/cancelled with the original request's id. Because ConduitMCP is stateless and each HTTP request runs in its own Bandit process, the notification (which arrives on a different request) cannot directly preempt the in-flight handler. Instead, the handler records the cancellation in a shared ETS table and tool code polls this module to decide whether to abort.

The handler also tracks which requests are in flight: track/2 when a request is dispatched, untrack/2 when it completes. A cancellation is recorded only for a request in_flight?/2 in the caller's scope; one for an unknown or already-completed request is ignored, as MCP permits. cancel/3 itself does not check, so a library caller can still record a cancellation directly.

Tool integration

Inside a long-running tool, periodically check the conn:

def my_long_tool(conn, params) do
  if ConduitMcp.Cancellation.cancelled?(conn) do
    {:error, %{"code" => ConduitMcp.Errors.request_cancelled(), "message" => "Request cancelled"}}
  else
    continue_work(...)
  end
end

Tools that complete in tens of milliseconds typically do not need cancellation at all — the client's notification will arrive after the response has already been sent.

Modern streams: disconnect is cancellation

The modern (2026-07-28) HTTP transport has no client-to-server notifications; a client cancels by closing the stream. When a streamed tools/call response (ConduitMcp.StreamSpec) fails to write because the client is gone, the transport records the cancellation here, under the request's own scope, so cancelled?/1 turns true for the running tool. A tool that has not returned within the transport's :stream_cancel_timeout is killed.

Scoping

JSON-RPC ids are client-chosen and conventionally small integers, so the table cannot be keyed on the id alone: a single POST {"method":"notifications/cancelled","params":{"requestId":"1"}} would abort every concurrent client's request id 1, and looping 1..1000 would abort every in-flight tool call on the node.

Rows are therefore keyed {scope, id}, where scope/1 derives the caller from the Plug.Conn, most specific first:

1. "session:" <> id from conn.private[:mcp_session_id] — set by ConduitMcp.Transport.StreamableHTTP when sessions are configured.
2. "principal:" <> id from ConduitMcp.Principal.id/1 — the authenticated principal, when its id is a string (as ConduitMcp.Principal.put/2 guarantees).
3. "ip:" <> bucket from ConduitMcp.Principal.client_bucket/1 — the last resort. That is the address for IPv4, and the /64 prefix for IPv6 ("ip:2001:db8:1:2::/64"), because a host is routinely handed a whole /64 and could otherwise rotate addresses to multiply its quota.

The prefix keeps the three namespaces apart: a principal whose id happens to equal a client's IP string does not share that client's rows or quota.

Bounds

notifications/cancelled is reachable unauthenticated. Through the handler, a row is written only for a request in flight in the caller's scope, so a client can hold no more rows than it has requests running. The table is still bounded two ways, as a backstop for direct cancel/3 callers and for requests that are long-running or leaked:

• Per-scope quota. cancel/3 refuses to insert past config :conduit_mcp, :cancellations_max_rows_per_scope (default 256) and returns {:error, :cancellation_limit_reached}. This is the bound that matters, and the only one that rejects: a global cap alone is a cross-tenant denial of service, because one unauthenticated client filling the table stops every other client's cancellations from being recorded.
• Global cap. A memory backstop at config :conduit_mcp, :cancellations_max_rows (default 10000; :infinity disables it). It never rejects — a caller under its own quota is always served. Reaching it evicts a batch of max_rows / 20 rows, oldest first from the largest scope, then from the next largest, so a client holding fewer rows than the largest scopes is evicted only after them. When every scope holds one row they all tie and eviction falls back to age, so the oldest rows go whoever owns them. The batch is always full, even then, so a lone writer runs the full-table scan that picks the rows at most once per batch of inserts; writers that hit the cap together each scan but evict overlapping rows. The per-scope quota is checked first: 40 sessions x 256 rows exceeds 10 000 without any single scope being over quota, and a global check that rejected would hand exactly that flood a cross-tenant denial of service.

A row is normally removed inline: the handler calls clear/2 in a try/after once the request completes. clear/2 reads before it writes, so the common request, which was never cancelled, takes no write lock on the table. The cap and janitor cover the cases where the inline removal never happens — a cancel that races the request's completion, or a request process killed before clear/2 runs.

Ids must be an integer or a string of at most 256 bytes (JSON-RPC requires a string or number); anything else is rejected with {:error, :invalid_request_id} rather than crashing the request process. Reasons are truncated and stripped of control characters via ConduitMcp.Reflect.

In-flight rows

track/2 writes one row per request process, {{scope, id}, pid}, to a duplicate_bag, so concurrent requests reusing an id in one scope each hold their own row and one completing (untrack/2 deletes only its own {key, pid} object) leaves the other cancellable. A request process killed before untrack/2 runs (as an HTTP/2 stream can be) leaves its row behind; cleanup/1 deletes rows whose process is no longer alive.

Emits [:conduit_mcp, :request, :cancelled] telemetry on cancellation with metadata %{request_id: id, scope: scope, reason: reason}, where scope is the prefixed value described under Scoping, and [:conduit_mcp, :cancellation, :cleanup] on each cleanup/1 pass with measurements %{removed: count, in_flight_removed: count}: expired cancellation rows and in-flight rows of dead processes respectively.