## 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>
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
- Specification: MCP Tasks extension, 2026-07-28 (overview).
- Extension id:
io.modelcontextprotocol/tasks. It is defined for stateless MCP (2026-07-28), so Paperclip uses it only with servers on that version. See MCP-PROTOCOL-VERSIONS.md. - Input requests use the multi round-trip shape (MRTR).
The protocol works like this:
- 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. tools/callmay return a task (resultType: "task", withtaskId,status,ttlMs,pollIntervalMs). The server decides per call.tasks/get {taskId}returns the task:working,input_required(withinputRequests),completed(withresult, the normal tool result),failed(with a JSON-RPCerror), orcancelled.tasks/update {taskId, inputResponses}answers input requests.tasks/cancel {taskId}asks the server to stop. Cancellation is cooperative.- Over HTTP,
Mcp-Namecarries the task ID on everytasks/*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-tasksqueue; 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/tasksoversubscriptions/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.