## 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>
9.4 KiB
MCP Protocol Versions in Paperclip's MCP Client
Audience: engineers changing how Paperclip calls providers' remote (Streamable HTTP) and local (stdio) MCP servers.
Paperclip's MCP client speaks the stateless revision 2026-07-28 and stays
compatible with handshake-based servers on 2025-11-25, 2025-06-18, and
older. Paperclip's own public MCP server is covered separately in
server/src/routes/public-mcp.ts.
Code: server/src/services/mcp-http.ts (protocol helpers),
server/src/services/tool-access/catalog/discovery.ts (catalog tools/list),
and server/src/services/tool-gateway.ts (tools/call, context reads, stdio).
Two eras
| Modern (2026-07-28+) | Legacy (2025-11-25 and earlier) | |
|---|---|---|
| Setup | none | initialize + notifications/initialized |
| Session | none, never sends Mcp-Session-Id |
Mcp-Session-Id when the server issues one |
| Version and capabilities | in every request's params._meta |
once, in initialize |
| HTTP headers | MCP-Protocol-Version, Mcp-Method, Mcp-Name, Mcp-Param-* |
MCP-Protocol-Version (after the handshake), Mcp-Method, Mcp-Name |
| Server asks for input | resultType: "input_required" result (MRTR) |
elicitation/create request on the SSE stream, or error -32042 |
Every modern request carries:
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {
"elicitation": { "url": {} },
"extensions": { "io.modelcontextprotocol/ui": { "mimeTypes": ["text/html;profile=mcp-app"] } }
},
"io.modelcontextprotocol/clientInfo": { "name": "paperclip", "version": "1" }
}
The MCP Apps extension (io.modelcontextprotocol/ui) is also in the legacy
initialize capabilities, so both eras learn that Paperclip renders MCP Apps
views (see MCP-APPS.md). Only modern requests declare URL
elicitation, because only that era has a retry path for it (below).
Negotiation
- Probe once per server.
negotiateMcpProtocolVersionsendsserver/discoverwith the preferred modern version in_meta.- A
DiscoverResultgivessupportedVersions; Paperclip picks the newest version it also supports (selectMcpProtocolVersion). - A modern error (
-32020,-32021,-32022) also identifies a modern server.-32022listssupportedversions to choose from. - Anything else (another error, an empty
202, a non-JSON body, a network error) identifies a legacy server, which gets theinitializehandshake. 401/403is returned to the caller unchanged, so OAuth discovery still sees theWWW-Authenticatechallenge.
- A
- Remember the answer. The result is cached in memory per connection and
endpoint (
mcpEraKey) for 24 hours and saved on the connection asconfig.mcpProtocolVersionby catalog refresh. For a legacy server the saved value is the version Paperclip requests ininitialize(MCP_PROTOCOL_VERSION), not the version the server answered with. - Tool calls never probe.
tools/calland context reads use the saved version. A stateless server is called directly, so a tool call is one HTTP request with no handshake. This keeps agent boot and time to first token unchanged. - Re-probe only on failure. The saved era is checked again when a request
built from it is refused:
- A modern rejection (
400with-32020/-32021/-32022) of a request Paperclip sent in legacy shape: the server is probed and the request is sent once more in modern shape. The server rejected it before running anything, so the retry cannot repeat a side effect. -32022on a modern request: retried once with a version from the server'ssupportedlist, using the handshake when that version is older.- A plain
400to a statelesstools/call: the server is probed and the saved version is repaired (handshake, session required), but the call is not sent again, because a plain400does not prove the tool never ran. The next explicit call uses the handshake. Context reads, which are read-only, are sent again. - A remembered legacy server that now refuses
initialize(400/404/405): probed again before the call fails. - Catalog refresh that gets
400with a saved version: probed again and listed once more (listing is read-only).
- A modern rejection (
stdio follows the stdio backward-compatibility rule: send server/discover
first; a DiscoverResult or modern error means modern, anything else or no
answer within 2 seconds means legacy. A server that exits on the unknown method
is started again for the handshake. The result is remembered per connection and
template, because Paperclip starts a process for each call. A remembered
handshake server that refuses initialize (for example after an upgrade to
stateless MCP) is probed again once.
Results
- A result without
resultTypeis"complete"(all legacy results). "input_required"ontools/call:- URL elicitation requests: shown as the provider link
(
provider_interaction_required, the same flow as legacy URL elicitation, up to 8 links). Paperclip never answers them on the person's behalf: no person action is recorded, so sendingacceptwould claim consent nobody gave. The next call goes out fresh, and the server, which tracks the out-of-band step itself, completes it or asks again. - Only
requestState(for example load shedding): kept in memory for 30 minutes and sent on the next identical call (same connection, grant, agent, tool, and arguments) with a new JSON-RPC id. It survives an attempt the server rejected (for example a401before a token refresh). The call stops withprovider_retry_requestedso the agent retries. - Form requests only, on a call that belongs to a task: a question card in
the task chat; the repeated call sends
inputResponsesand the exactrequestState. See MCP-ELICITATION.md. Form beside a URL request: the link goes first. - Sampling or roots requests, form requests outside a task, or more than 8
links: the call stops with
provider_input_requiredand the message "This app needs information Paperclip can't collect yet." Paperclip declares form only on task calls and never declares sampling or roots, so compliant servers should not send them.
- URL elicitation requests: shown as the provider link
(
"input_required"on a context read (resources/read,prompts/get) or a stdio call stops withprovider_input_required.- Resource not found is
-32602from modern servers and-32002from legacy ones. Both surface asremote_mcp_errorwith the code in the details.
Caching
tools/list, resources/list, resources/read, resources/templates/list,
and prompts/list results with ttlMs > 0 are reused while fresh, capped at
10 minutes. cacheScope: "private" results are keyed by the credential that
read them; "public" results are shared by every credential on the same
connection, never across connections. Results of retries that carried
inputResponses or requestState are never cached. Results without ttlMs
(every legacy server) are not cached, so legacy behavior is unchanged.
Catalog refresh returns a fresh cached tool list without contacting the server. Health checks always list live, so an outage or a revoked credential is never hidden by a cached list. Catalog refresh saves the version its last successful request actually used, including after a credential refresh. Nothing is fetched ahead of time, so caching never adds work before an agent's first token.
x-mcp-header
A tool whose inputSchema marks properties with x-mcp-header gets those
argument values mirrored into Mcp-Param-{Name} headers on tools/call.
Values that are not plain ASCII, have leading or trailing spaces, or look like
the sentinel are sent as =?base64?…?=. Catalog refresh drops (and logs) a tool
whose annotations break the rules: not on a properties path, not a string,
integer, or boolean, not an HTTP token, or not unique.
OAuth (2026-07-28 authorization changes)
- RFC 9207
iss. The issuer from validated metadata is recorded when sign-in starts (expectedIssuer). A returnedissmust match it, on success and on error responses; a provider error with a mismatchedissis not acted on or shown. When the authorization server advertisesauthorization_response_iss_parameter_supported, a callback withoutissis refused (oauth_issuer_missing). - Client registration order. Preconfigured client, then Client ID Metadata
Document when the server advertises
client_id_metadata_document_supported, then Dynamic Client Registration (deprecated in 2026-07-28, kept for older servers). application_type. Sent in DCR and in the metadata document:webfor Paperclip's HTTPS callback,nativefor a local install's localhost callback.- Issuer binding. Registered client material is bound to the issuer, resource, callback, and company, and a different issuer registers again.
Not yet supported
Tracked as follow-ups:
- Recording that a person finished a provider URL step, so Paperclip can
answer it with
acceptand the provider'srequestState. - Retrying a
requestState-only result automatically instead of asking the agent to retry. subscriptions/listenchange notifications (cache invalidation relies onttlMs).- Cancellation, icons, and enterprise-managed authorization. (Progress is supported: see MCP-PROGRESS.md.)