## 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>
KV Demo MCP Server
A standalone, self-contained MCP server for demos. One process exposes four key/value MCP tools (plus a progress demo tool) and a tiny web UI that renders the values those tools mutate — so you can call a tool from a Paperclip agent and watch the value appear in a browser tab.
The shared in-memory store is the whole point: the same Map<string, string>
backs every tool call and every UI render. There is no database, no file, no
persistence. Restart the process and the store is empty again. That makes this
the right fixture for showing what Paperclip stores versus what the demo
package stores — the package stores the values, Paperclip stores the
connection, the profile/policy decisions, and the audit log.
This package pairs with the operator guide in doc/MCP-ACCESS-GOVERNANCE.md and the recorded walkthrough in doc/MCP-DEMO-SCRIPT.md.
What you get
- Four MCP tools (over the Streamable HTTP transport):
kv_list(read) — list every key/value, optionally filtered byprefix.kv_get(read) — read one key.kv_set(write) — set one key to a string value.kv_delete(destructive) — delete a key. CarriesdestructiveHint: trueso Paperclip's catalog quarantines it on first sight.
slow_with_progress(read) — waitssteps×stepMsand sends MCPnotifications/progressafter each step (withTotal: falseleaves the total out). For the task chat's tool progress; see doc/connections/MCP-PROGRESS.md.- A Values UI at
/— an auto-refreshing HTML table over the same store. - A JSON state route at
/api/state— what the UI polls.
Local startup
From the repo root:
pnpm --filter @paperclipai/kv-demo-mcp-server build
pnpm --filter @paperclipai/kv-demo-mcp-server start
Or run the source directly during development:
cd packages/kv-demo-mcp-server
node --experimental-strip-types src/main.ts # Node 24+
By default it listens on http://127.0.0.1:8848 and prints three URLs to
stderr on startup:
- MCP endpoint —
POST http://127.0.0.1:8848/mcp(Streamable HTTP) - Values UI —
GET http://127.0.0.1:8848/(auto-refreshes every 2s) - JSON state —
GET http://127.0.0.1:8848/api/state
Open the Values UI in a browser tab and keep it visible. Every successful
kv_set / kv_delete lands in that table within ~2 seconds.
Configuration
All configuration is via environment variables:
| Variable | Default | Purpose |
|---|---|---|
PORT (or KV_DEMO_PORT) |
8848 |
Listen port. Use 0 for a random free port. |
KV_DEMO_HOST |
127.0.0.1 |
Bind host. Use 0.0.0.0 to accept connections from another machine on the LAN. |
KV_DEMO_TOKEN |
unset | Optional shared secret. When set, data and MCP routes require it. |
When KV_DEMO_TOKEN is set, present it as Authorization: Bearer <token>.
For the browser UI, open http://127.0.0.1:8848/#token=<token>; the fragment is
not sent to the server and the page removes it from the address bar before
polling /api/state with the bearer header. The token is a convenience guard
for local demos, not a hardened auth scheme; do not expose this server to
untrusted networks.
Connecting from Paperclip
The KV demo is meant for the remote_http connection path. The server speaks
Streamable HTTP at /mcp, runs in a single process so the Values UI and the
MCP tools share state, and listens on a fixed loopback port. Paperclip's
remote-HTTP gateway proxies every call through policy and audit while leaving
process supervision to you (just Ctrl+C the server when you are done).
Via the Connect-an-app wizard (recommended)
- Open the company's Tools UI at
/<prefix>/companies/<companyId>/tools. - Go to Connect an app and pick Connect with a link.
- Paste
http://127.0.0.1:8848/mcpand give it a name (e.g. "KV demo"). - If you launched the server with
KV_DEMO_TOKEN, paste the token in the App key field. The wizard stores it as anAuthorization: Bearer …header secret. - Pick the profile defaults (read/write/destructive) and finish. Paperclip
imports the four tools and quarantines
kv_delete.
The wizard hits this API under the hood:
curl -fsS -X POST \
-H "Authorization: Bearer $BOARD_API_KEY" \
-H "Content-Type: application/json" \
"$PAPERCLIP_URL/api/companies/$COMPANY_ID/tools/apps/connect" \
-d '{
"link": "http://127.0.0.1:8848/mcp",
"name": "KV demo"
}'
If a token is set, add the credentialValues block:
{
"link": "http://127.0.0.1:8848/mcp",
"name": "KV demo",
"credentialValues": {
"credentials.authorization": "my-demo-secret"
}
}
Transport tradeoffs
remote_http(recommended for this demo) — required if you want the Values UI to reflect what the agent just did. The KV demo intentionally holds state in one process and exposes both the MCP endpoint and the UI from that process. Paperclip'sremote_httpgateway forwards every call to the same loopback URL, so the UI always sees the same store the tools mutated.local_stdio(not used here) — runs MCP servers as supervised child processes inside Paperclip's runtime slots. Reserved for trusted local deployments (developer laptop,local_trustedorauthenticated/privatewithPAPERCLIP_TRUSTED_MCP_RUNTIME_HOSTset on a single trusted worker). Each runtime slot has its own process, which would give each slot its own in-memory store — you would lose the shared-state property that makes this demo work. Use the approved stdio templates that ship in the Paperclip build when you need stdio; do not try to shoehorn this server into a local-stdio template.
For the full transport policy across deployment modes, see MCP-ACCESS-GOVERNANCE.md → Local trusted deployment.
What you should see in Paperclip
After the wizard finishes, expect:
- Catalog — four tools imported from this connection.
kv_listandkv_getare taggedread;kv_setis taggedwrite;kv_deleteis taggeddestructiveand starts inquarantinedstatus. - Tools panel on an agent —
kv_list,kv_get, and (with the default ask-first policy)kv_set.kv_deleteis not listed until you take it out of quarantine. - Audit feed — one row per call. Reads show
tool_gateway.call_completedwithdecision: allow. Writes that hit the default ask-first policy showtool_gateway.approval_requestedfollowed bytool_gateway.call_allowedandtool_gateway.call_completedonce you approve. Calls tokv_deleteshowtool_gateway.call_deniedwithreasonCode: quarantined_catalog_entry.
The recorded walkthrough in doc/MCP-DEMO-SCRIPT.md runs all three cases end-to-end against this package and matches the audit rows above.
What lives where
| Concern | Stored in this package | Stored in Paperclip |
|---|---|---|
Key/value entries (kv_* data) |
In-memory Map, lost on restart. |
Not stored. Paperclip never sees the values directly; the gateway only sees the MCP request/response envelope and the redacted-by-policy view the audit log keeps. |
| Connection record (URL, token, transport) | Not stored. | Persisted in tool_connections. The optional token becomes a secret. |
| Profile / policy / binding decisions | Not stored. | Persisted under tool_profiles, tool_policies, and tool_profile_bindings. |
| Approval action requests | Not stored. | Persisted under tool_action_requests, linked to issue-thread interactions. |
| Audit rows for each call | Not stored. | Persisted under tool_call_events. Append-only. |
Cleanup and reset
Resetting the demo state usually means resetting this process; Paperclip's records stay intact unless you also archive the connection.
-
Empty the KV store —
Ctrl+C(orkill) the server and start it again. The new process starts with zero keys and revision0. There is no in-process reset endpoint by design; restart is the single supported reset. -
Free the port — if startup logs
EADDRINUSE, anotherkv-demoprocess is still bound to8848. Find and kill it:lsof -nP -iTCP:8848 -sTCP:LISTEN kill <pid> -
Quiesce the Paperclip side — disable the connection so the gateway stops trying to reach the now-stopped server:
curl -fsS -X PATCH \ -H "Authorization: Bearer $BOARD_API_KEY" \ -H "Content-Type: application/json" \ "$PAPERCLIP_URL/api/tool-connections/$CONNECTION_ID" \ -d '{ "enabled": false, "status": "disabled" }' -
Archive the application when you are fully done. Audit history is retained, but no new calls can land:
curl -fsS -X PATCH \ -H "Authorization: Bearer $BOARD_API_KEY" \ -H "Content-Type: application/json" \ "$PAPERCLIP_URL/api/tool-applications/$APPLICATION_ID" \ -d '{ "status": "archived" }'
The KV demo is a fixture, not a piece of infrastructure. Treat each session as disposable: start it, run the demo, kill it.
MCP Tasks demo server
The same package ships a second server, paperclip-tasks-demo-mcp-server, for
trying MCP Tasks: long tool calls that
return a task, which the client polls until it finishes. It speaks the
stateless MCP revision 2026-07-28 (server/discover, no session) and declares
the io.modelcontextprotocol/tasks extension. It needs no credentials and
calls nothing outside its own process: the "work" is a timer.
| Tool | What it shows |
|---|---|
slow_report |
Returns a task, then a report after seconds (default 20). Polling. |
needs_approval |
Asks a form question (approve or reject); finishes after the answer arrives with tasks/update. |
will_fail |
Fails after seconds (default 5). A failed task. |
cancellable |
Runs for seconds (default 600) and stops on tasks/cancel. |
expires |
Its TTL (ttlSeconds, default 15) passes before it finishes, so the server forgets it. |
quick_echo |
Answers at once, without a task. |
It returns a task only to a request that declares the extension. Without it, the long tools answer with an error that says the client does not support MCP Tasks.
Start it from the repo root:
pnpm --filter @paperclipai/kv-demo-mcp-server build
node packages/kv-demo-mcp-server/dist/tasks/main.js
It listens on http://127.0.0.1:8849:
- MCP endpoint:
POST /mcp - Status page:
GET /, which lists every task, how many times each tool was started, and the latest protocol events. It reloads every 2 seconds. - JSON state:
GET /api/state, the same data for scripts.
Task state is saved to a file (by default ~/.paperclip-tasks-demo/state.json),
so you can stop and start the server mid-task. A task's progress is worked out
from the clock, so a restart neither resets nor repeats it.
| Variable | Default | Purpose |
|---|---|---|
TASKS_DEMO_PORT (or PORT) |
8849 |
Port to listen on. |
TASKS_DEMO_HOST |
127.0.0.1 |
Interface to bind. |
TASKS_DEMO_STATE_FILE |
~/.paperclip-tasks-demo/state.json |
Where task state is saved. Its folder must be yours and not writable by others. memory keeps it in memory only. |
TASKS_DEMO_TOKEN |
unset | When set, /mcp and /api/state require Authorization: Bearer <token>. |
See "Try it yourself" in MCP-TASKS.md for the full walkthrough with Paperclip.