Files
PaperClipAI/doc/connections/MCP-TASKS.md
T
DottaandClaude Opus 5.5 944b1c64d7 feat(mcp): keep long provider calls durable with the MCP Tasks extension (#21263)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents use connected apps through Paperclip's MCP client in the tool
gateway
> - Some provider actions run for minutes: CI runs, deploys, batch jobs
> - Today such a call is lost if it outlives the tool timeout or if
Paperclip restarts or deploys mid-call, and a retry can start the work a
second time
> - Recovery must just work, and the target rate of runs that need a
manual retry is 0%
> - This pull request implements the MCP Tasks extension
(`io.modelcontextprotocol/tasks`, 2026-07-28) in the MCP client
> - The benefit is that a long provider call becomes a durable task: it
survives timeouts, restarts, and deploys, and it is never started twice

## Linked Issues or Issue Description

**Problem**
A long provider tool call holds an HTTP request open. When it passes the
tool timeout, or when Paperclip restarts or deploys during the call, the
result is lost. The agent then often repeats the call, and the provider
does the work again.

**Proposed solution**
Implement the client side of the MCP Tasks extension. Declare it on
stateless tool calls. Store each returned task durably, wait on it
during the call, keep polling it in the background after the call ends,
and let the same call attach to the stored task instead of sending
`tools/call` again.

**Why it matters**
CI, deploy, and batch actions are where agents lose the most work today.
A durable task handle makes these actions safe across timeouts,
restarts, and deploys, without a person.

Refs #21119, Refs #21140, Refs #21219 (the MCP Apps, stateless MCP
client, and MCP Skills work this builds on).

## What Changed

- **Off by default:** MCP Tasks are behind the new instance experimental
setting `enableMcpTasks` ("Durable app actions (MCP Tasks)"), default
off. When it is off, Paperclip never declares the extension, nothing
attaches to or polls tasks, pending rows do not block idle sleep, and
behavior matches master. A test covers the off state.

- `mcp-http.ts`: the tasks extension is declared per request, only on
HTTP `tools/call` and `tasks/*`. Discovery, listings, and stdio servers
do not declare it. `tasks/*` requests put the task ID in `Mcp-Name`.
- New `mcp-tasks.ts`: parses task results, bounds the server's timing
hints, sends `tasks/get`, `tasks/update`, and `tasks/cancel`, and seals
task IDs at rest (AES-256-GCM, bound to company and connection; a keyed
hash gives uniqueness).
- New company-scoped table `tool_mcp_tasks` (migration `0475`,
online-compatible). It links the task to the call, run, task,
connection, and grant. It stores no provider result.
- `tool-gateway.ts`:
- A returned task is recorded, then polled up to the normal tool
timeout. Its result goes through the same validation, redaction, and
recording as a direct result.
- Past the timeout, or when the caller disconnects, the agent gets
`provider_task_pending` ("call again with the same arguments"). The task
stays durable.
- A call with the same endpoint, tool, full arguments, grant, agent,
task, and actor attaches to the undelivered task. A retry with the same
idempotency key also attaches, and it can never start different work
under that key.
- Input: URL requests show the provider link (Paperclip never answers
them). Form requests become a question card; only the person's answer is
sent with `tasks/update`. Other requests stop with a clear "needs input"
error.
- Stopping the run sends `tasks/cancel` and marks the task cancelled. A
caller that only disconnects keeps the task.
- `failed` becomes a tool error with the provider's message. An unknown
task or a passed TTL becomes `provider_task_expired`. Every task stops
being tracked at its TTL, or after 7 days at most.
- Audit entries: `tool_gateway.task_started`, `task_input_sent`,
`task_cancelled`.
- New `mcp-task-work.ts`, registered at startup with the shared deadline
scheduler: it resumes polling pending tasks after a restart, cancels
tasks whose task closed or run was stopped, and wakes the assignee once
when a task settles after its run ended.
- Docs: `doc/connections/MCP-TASKS.md`, linked from
`doc/connections/README.md`.

Background work (per `rules/sleep-aware-background-work.mdc`): trigger
is a task row write or release (`mcp-tasks` queue) and one startup pass.
The deadline is the earliest `next_poll_at`. Cadence is the server's
`pollIntervalMs` within 5 s – 5 min, with backoff; 5 min while waiting
for a person. It is quiet when no row has a next poll. This is the
narrow external-source exception: providers give no wake Paperclip can
receive, and polling stops with the task.

## Verification

- `server/src/__tests__/mcp-tasks.test.ts`: 20 tests with a fake
2026-07-28 server that returns tasks only to a client that declares the
extension and checks `Mcp-Name`. They cover:
- polling to completion, with the result identical to a synchronous
call;
  - timeout, then an attaching call with no second `tools/call`;
  - a keyed retry, and a reused key with different arguments (refused);
- restart mid-task: a fresh gateway with no in-memory state polls the
row, wakes the agent once, and the recovered run gets the result once
with no second `tools/call`;
  - no wake while the run is still going;
- URL input (link, never answered), and form input (question card, then
`tasks/update` with the answer);
- cancellation by the run, by closing the task, and no cancellation when
only the caller leaves;
- failure, an unknown task, and TTL expiry (ends in under 3 s, no hang);
  - another agent never attaches;
- synchronous calls unchanged and older servers never see the extension.
- Red/green: with attach disabled, the timeout, keyed-retry, and restart
tests fail (3). With `tasks/cancel` disabled, both cancellation tests
fail (2). Before `tools/call` declared the extension, 13 end-to-end
tests failed. All pass with the change.
- Existing suites pass: `mcp-protocol-versions`, `mcp-http`, `mcp-apps`,
`mcp-skills`, `server-startup-feedback-export`, `tool-gateway`,
`tool-gateway-discovery-http`, `remote-mcp-connectors` (342 tests).
- `tsc --noEmit -p server` is clean. `pnpm --filter @paperclipai/db
check:migrations` passes (the migration is classified
online-compatible). Snapshots pruned to five.
- Agent boot and time-to-first-token: no change in the boot or
first-turn path. The only new per-call cost is one indexed lookup on
stateless tool calls.
- Not run: a live provider that returns tasks. No public MCP server that
returns tasks was available without new credentials.

## Risks

- Shipped off by default. Review findings that only affect the
setting-on path after this merge are tracked as follow-ups.

- Migration: a new table with indexes and foreign keys to `companies`,
`tool_invocations`, and `tool_connections`. Online-compatible.
- Behaviour change only for servers that return tasks, which they may do
only to clients that declare the extension. Older servers and stdio
servers are unchanged.
- A task that settles while nobody is waiting stays attachable for 1
hour, so a deliberate repeat of the same call within that hour collects
the earlier result instead of starting new work.
- The wake after a background task settles uses the generic task wake;
the agent must call the tool again to collect the result.
- Follow-ups: `notifications/tasks` via `subscriptions/listen`; sampling
and roots input requests; showing a long action's progress in the task
chat.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, in Claude Code with
tool use (shell, file edits, local test runs).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 08:32:06 -06:00

9.4 KiB

MCP Tasks: long provider calls that survive timeouts, restarts, and deploys

Some provider actions take minutes: a CI run, a deploy, a batch job. An MCP server that supports Tasks answers such a tools/call with a durable task handle instead of the result. Paperclip stores that handle, waits on it, and hands the agent the final result exactly as a quick call would return it. If the call outlives its timeout, or Paperclip restarts or deploys mid-call, the work is not lost and is never started a second time.

Turning it on

MCP Tasks are behind the experimental setting Durable app actions (MCP Tasks) (enableMcpTasks), off by default. Find it under Instance settings → Experimental.

  • Off: Paperclip never declares io.modelcontextprotocol/tasks, so servers never return a task and every call behaves as before. Nothing polls, attaches to, or wakes for stored tasks, and they do not keep an idle host awake.
  • On: everything below applies. Turning it off later stops new tasks; stored ones resume if it is turned on again before they expire.

The standard

The protocol works like this:

  1. The client declares the extension per request in _meta["io.modelcontextprotocol/clientCapabilities"].extensions. A server must never return a task to a request that did not declare it.
  2. tools/call may return a task (resultType: "task", with taskId, status, ttlMs, pollIntervalMs). The server decides per call.
  3. tasks/get {taskId} returns the task: working, input_required (with inputRequests), completed (with result, the normal tool result), failed (with a JSON-RPC error), or cancelled.
  4. tasks/update {taskId, inputResponses} answers input requests.
  5. tasks/cancel {taskId} asks the server to stop. Cancellation is cooperative.
  6. Over HTTP, Mcp-Name carries the task ID on every tasks/* request so load balancers route it to the instance holding the task.

Optional notifications/tasks over subscriptions/listen are not used; Paperclip polls, which the specification makes the default.

How Paperclip implements it

Step What happens Code
Declare Only the HTTP tools/call and tasks/* requests declare the extension. Discovery, listings, and local (stdio) servers do not, so no other path can receive a task it cannot handle. mcpHttpRequestInit(..., { declareTasks }) in server/src/services/mcp-http.ts
Record A returned task is stored before Paperclip waits on it: a tool_mcp_tasks row linked to the call, run, task, connection, and grant. createMcpTaskRecord in server/src/services/tool-gateway.ts
Wait The live call polls tasks/get at the server's pollIntervalMs (kept between 0.2 s and 5 s) until the normal tool timeout. A completed task's result then goes through the same validation, redaction, and recording as a direct result. waitForMcpTask
Hand off If the timeout passes or the caller disconnects, the agent is told the app is still working and to call the tool again with the same arguments. The row keeps the task and background polling takes over. provider_task_pending
Attach A call with the same endpoint, tool, full arguments, grant, agent, task, and actor attaches to the undelivered task instead of sending tools/call again. So does a retry with the same idempotency key, including after a crash mid-wait; the same key with other arguments is refused and leaves the original retry intact. One holder at a time (a lease): a second simultaneous caller is told to call again. findAttachableMcpTask, mcpTaskForKeyedRetry, claimMcpTask
Deliver A completed task counts as delivered only once its result is recorded on the call. A crash in between leaves it collectable again. markMcpTaskDelivered
Restart Background work reads pending rows at startup and polls each at its next deadline, with each request bounded to 30 s. It rechecks the same access a live call needs (grant, audience, delegation). When a task settles, or asks a new question, after its run has ended, the assignee is woken once; the agent's repeated call collects the result or shows the question. pollDueMcpTasks, server/src/services/mcp-task-work.ts
Input URL requests show the provider link, as for a direct request; Paperclip never answers them for the person. Form requests become a question card on the task; only the person's answer is sent with tasks/update. Other requests (sampling, roots) stop with a clear "needs input" error. planMcpTaskInput
Cancel Stopping the run sends tasks/cancel and marks the row cancelled. Closing the task or stopping its run does the same for a task in the background; a later call reports the cancellation and never revives it. A caller that only disconnects keeps the task. cancelMcpTaskRecord, mcpTaskStopReason
Finish failed becomes a tool error with the provider's message. An unknown task (-32602) or a passed TTL becomes a clear error telling the agent to run the action again. Nothing waits forever: every task stops being tracked after its TTL, and seven days after Paperclip first saw it at most. provider_task_failed, provider_task_expired

What is stored

  • The provider's task ID is sealed at rest (AES-256-GCM, a key derived from the instance's tool-action secret, bound to the company and connection). The specification lets servers treat task IDs as bearer tokens. Uniqueness uses a keyed hash, never the ID.
  • No provider result is stored in the task row. The result stays with the provider until it is delivered, and the delivered result is recorded on the call exactly as a direct result is.
  • A task is read only with the grant that created it, after the same access check a live call makes. If that access is removed, the connection is disabled, or its endpoint changes, background polling stops and the task is reported as no longer available.
  • A provider's error body is read only up to 64 KiB.

Agent-facing errors

Reason code When What the agent should do
provider_task_pending Still working at the timeout, or the caller left Call the same tool again with the same arguments
provider_interaction_required The app needs the person to open a link Wait for the person, then call again
elicitation_required The app asked a question; a card is on the task Wait for the answer, then call again
provider_input_required The app needs input Paperclip cannot collect Ask the person to finish in the app
provider_task_failed The app reported a failure Treat as a tool error
provider_task_cancelled The app cancelled, or the run was stopped Run again if still needed
provider_task_expired The app no longer has the task Run the action again

Background work

registerMcpTaskWork uses the shared deadline scheduler (registerDeadlineWork). It is quiet when nothing is pending:

  • Trigger: writing or releasing a task row notifies the mcp-tasks queue; startup runs once and rebuilds from the rows.
  • Deadline: the earliest next_poll_at, never earlier than a live call's lease.
  • Cadence: the server's pollIntervalMs, kept between 5 s and 5 min, with backoff after failures. A task waiting for a person is checked every 5 min: the person's answer wakes the agent, whose call checks immediately.
  • Quiet: once every task is delivered, settled and woken, cancelled, or expired, no row has a next poll and no query or provider request runs.

This is the narrow exception in rules/sleep-aware-background-work.mdc: the provider offers no wake Paperclip can receive, so an active task is polled. Polling stops with the task. A pending task is an idle-sleep blocker (tool_mcp_tasks in idle-sleep-safety.ts), so a host that sleeps when idle stays awake until every task is settled. Recovery runs even when heartbeat scheduling is off; only the agent wake needs the scheduler.

An approved action whose task outlives the wait keeps its approval: the action returns to approved, and its next execution attaches to the same task.

Follow-ups

  • notifications/tasks over subscriptions/listen, to replace polling where servers support it.
  • Sampling and roots input requests.
  • Showing a long-running provider action's progress (statusMessage) in the task chat.
  • Validating question-card answers against the provider's form schema (types, required fields) and letting the person correct them before tasks/update.

Tests

server/src/__tests__/mcp-tasks.test.ts runs a fake 2026-07-28 server that returns tasks. It covers polling to completion, a timeout followed by an attaching call, a keyed retry, a restart mid-task (fresh gateway, no second tools/call, one wake, one delivery), URL and form input, cancellation by the run and by closing the task, failure, an unknown task, TTL expiry, another agent never attaching, and synchronous calls left unchanged.