Files
PaperClipAI/doc/connections/MCP-PROGRESS.md
T
DottaandClaude Opus 5.5 a726dce4f0 feat(mcp): show live progress for long connected-app tool calls in the task chat (#21449)
## 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>
2026-11-13 20:14:22 -06:00

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

  1. Request. For a tools/call made 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.
  2. Response stream. The app sends notifications/progress (progress, optional total, optional message) 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. readMcpHttpResponse hands each notification to an observer before it reaches the result, and the observer can never fail or delay the call.
  3. Reporter (server/src/services/tool-call-progress.ts). Each update is checked (finite, non-negative, increasing; total kept only when positive and at least progress) and its message reduced to plain single-line text of at most 200 characters. The reporter then:
    • publishes a heartbeat.run.tool_progress live event at most every 250 ms (the latest update wins);
    • saves the latest update on the tool_invocations.progress column at most every second, and never onto a finished call;
    • publishes a final event with done: true when the call ends. Nothing the reporter does is awaited by the call.
  4. 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.
  5. 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 reads GET /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 calls done; 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.