## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents call tools from connected apps through the Paperclip MCP gateway > - Some tool calls take a long time: exports, builds, large searches > - The MCP progress utility lets an app report how far a call is, but Paperclip ignored it > - So the task chat showed only a spinner until the call finished, with no sign of life > - This pull request reads the app's progress and shows it on the tool's row while the call runs > - The benefit is that people can see that a long call is working, how far it is, and how long it has run ## Linked Issues or Issue Description **Subsystem affected** Connected apps (MCP gateway) and the task chat. **Problem or motivation** A long tool call from a connected MCP app shows only a spinner in the task chat. Paperclip does not send a `progressToken`, and it drops `notifications/progress` from the app. **Proposed solution** Send a `progressToken` on each `tools/call` that an agent run makes. Read the app's progress notifications from the call's response stream. Show a progress bar (or an indeterminate sweep), the latest message, and elapsed time on the running tool row. Keep the latest state so that a reload mid-call shows it. **Alternatives considered** A new transport for progress. The existing company live-events socket already carries per-run events with run read checks, so this change uses it. **Additional context** Spec: https://modelcontextprotocol.io/specification/2026-07-28/basic/utilities/progress ## What Changed - `mcp-http.ts`: `mcpHttpRequestInit` can add `_meta.progressToken`. `readMcpHttpResponse` gives each notification on the response stream to an observer before the result. The observer cannot fail or delay the call. New `mcpProgressNotificationOf` matches a notification to its token. - `tool-gateway.ts`: remote HTTP and local stdio `tools/call` from an agent run send a per-call token and forward progress to a reporter. Calls without a run send no token. - New `server/src/services/tool-call-progress.ts`: checks each update (finite, increasing, plain single-line text of at most 200 characters). It publishes a `heartbeat.run.tool_progress` live event at most every 250 ms (latest wins) and saves the latest update on the invocation at most every 1 s. Nothing is awaited by the call. A final `done` event goes out when the call ends. - DB: nullable `tool_invocations.progress` jsonb column (migration `0479`, `ADD COLUMN` only). A save never writes onto a finished call. - Live delivery: the new event follows its run like transcript output. A client gets it only for runs it follows, after the run read check, in the run's company only. - New route `GET /api/issues/:issueId/tool-call-progress` (task read check) returns the latest progress of the task's running calls, for a reload mid-call. Documented in `docs/api/issues.md`. - UI: `ToolCallProgressProvider` (one per chat) keeps the latest update per call. A running tool row subscribes and shows a bar or sweep, the message, the percent and elapsed time (design tokens, reduced motion honored). Finished rows drop it and never fetch or re-render for progress. `LiveUpdatesProvider` ignores the event for query invalidation. - `packages/kv-demo-mcp-server`: new `slow_with_progress` demo tool (`steps`, `stepMs`, `withTotal`) in its own file. - Storybook: `Tasks/Tool progress` stories (running with total, running without total, done). - Docs: new `doc/connections/MCP-PROGRESS.md`; `MCP-PROTOCOL-VERSIONS.md` no longer lists progress as unsupported. ## Verification - Red/green: on the original source, 5 of the new server tests fail (token in `_meta`, SSE with interleaved progress and result, notification matching, run-interest delivery, gateway end-to-end). With this change they pass. - `server/src/__tests__/mcp-http.test.ts` (13), `tool-call-progress.test.ts` (9: throttling, latest wins, bounded text, out-of-order drop, finish, failures never throw, company/run/tool scoping), `tool-call-progress-store.test.ts` (2, embedded Postgres: company and task scoping, no write onto a finished call), `realtime/live-event-delivery.test.ts` (run interest), `tool-gateway.test.ts` end-to-end against the real SDK kv demo server over Streamable HTTP: 6 provider updates over about 1.2 s give 3 to 7 throttled events, all for the right company, run, task and tool, the last one `done`; no event reaches another company; the invocation keeps the progress; the result is unchanged. - UI: `tool-call-progress.test.tsx` (10: name matching, row states, plain-text rendering, drop on complete, restore after reload, no fetch for finished rows). All 67 task-chat test files pass. - `packages/kv-demo-mcp-server`: 13 tests, including progress over HTTP with and without a total. - Storybook: checked the three stories in a browser. The bar fills to 40%, the sweep animates, the elapsed time ticks, and the done row shows no progress. - `pnpm verify`: see the CI checks for the final revision. ## Risks - Low. The migration adds one nullable column. - An SSE response is now bounded per message, not per stream, so handled notifications (such as progress) do not use up the result's size limit. Each message is still bounded. - Progress code runs only while a run's tool call is in flight. It adds a few bytes to the request and throttled, fire-and-forget work. Agent boot and time to first token do not change. - A row finds its call by run and tool name. If one run calls the same tool twice at the same time, both rows show the newer call's progress. - Progress from a call that became an MCP Task is not shown. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Claude Code agent with tool use and code execution. ## 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>
3.7 KiB
Progress for long MCP tool calls
When an agent run calls a connected app's tool and the app reports progress, the task chat shows it on the tool's row while the call runs: a bar that fills when the app knows the total (a quiet sweep when it does not), the app's latest status line, and elapsed time. The row drops it when the call finishes.
Spec: MCP 2026-07-28, Progress.
How it works
- Request. For a
tools/callmade by an agent run, the gateway adds a per-call_meta.progressToken(paperclip-progress-<uuid>). This applies to remote (Streamable HTTP) and local stdio connections, under every protocol version. Calls not made by a run (board test calls, MCP Apps views) send no token. - Response stream. The app sends
notifications/progress(progress, optionaltotal, optionalmessage) on the call's own response stream: SSE events on the POST response for HTTP, stdout lines for stdio. Under 2026-07-28, request-scoped notifications always stay on that stream.readMcpHttpResponsehands each notification to an observer before it reaches the result, and the observer can never fail or delay the call. - Reporter (
server/src/services/tool-call-progress.ts). Each update is checked (finite, non-negative, increasing;totalkept only when positive and at leastprogress) and its message reduced to plain single-line text of at most 200 characters. The reporter then:- publishes a
heartbeat.run.tool_progresslive event at most every 250 ms (the latest update wins); - saves the latest update on the
tool_invocations.progresscolumn at most every second, and never onto a finished call; - publishes a final event with
done: truewhen the call ends. Nothing the reporter does is awaited by the call.
- publishes a
- Delivery. The event goes to the run's company only. The live socket treats it like transcript output: a client receives it only for runs it asked to follow, after the same run read check.
- Task chat.
ToolCallProgressProvider(one per chat) keeps the latest update per call. A running tool row subscribes to it and finds its call by run and tool name. Each update carries both the gateway name and the name native runners give the tool (assignedToolName: shortened, with a hash), since native transcripts show the latter. When a running row first mounts, the chat readsGET /api/issues/:issueId/tool-call-progress(again on mount and on tab focus), so a reload mid-call shows the latest saved state. The read also marks recently finished callsdone; a call is never dropped just because the read does not list it, since its first save may still be in flight. Finished rows never fetch or re-render for progress.
Speed
The token adds a few bytes to the request. Parsing happens on the stream that was already being read. Publishing and saving are throttled, fire-and-forget, and stop when the call ends. Agent boot and time to first token are untouched: the code runs only while a tool call is in flight.
Trying it
packages/kv-demo-mcp-server has a slow_with_progress tool
(steps, stepMs, withTotal). Connect the demo server, then ask an agent to
call it with, say, { "steps": 20, "stepMs": 1000 }; the tool row fills over
20 seconds. withTotal: false shows the indeterminate state.
Not covered
- Matching uses the run and the tool name. If one run calls the same tool twice at once, both rows show the newer call's progress.
- Progress from a call that became an MCP Task (see
MCP-TASKS.md) is not shown. - Progress is not forwarded to the agent's own MCP client.