Files
PaperClipAI/packages/kv-demo-mcp-server
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
..

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 by prefix.
    • kv_get (read) — read one key.
    • kv_set (write) — set one key to a string value.
    • kv_delete (destructive) — delete a key. Carries destructiveHint: true so Paperclip's catalog quarantines it on first sight.
  • slow_with_progress (read) — waits steps × stepMs and sends MCP notifications/progress after each step (withTotal: false leaves 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).

  1. Open the company's Tools UI at /<prefix>/companies/<companyId>/tools.
  2. Go to Connect an app and pick Connect with a link.
  3. Paste http://127.0.0.1:8848/mcp and give it a name (e.g. "KV demo").
  4. If you launched the server with KV_DEMO_TOKEN, paste the token in the App key field. The wizard stores it as an Authorization: Bearer … header secret.
  5. 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's remote_http gateway 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_trusted or authenticated/private with PAPERCLIP_TRUSTED_MCP_RUNTIME_HOST set 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_list and kv_get are tagged read; kv_set is tagged write; kv_delete is tagged destructive and starts in quarantined status.
  • Tools panel on an agent — kv_list, kv_get, and (with the default ask-first policy) kv_set. kv_delete is not listed until you take it out of quarantine.
  • Audit feed — one row per call. Reads show tool_gateway.call_completed with decision: allow. Writes that hit the default ask-first policy show tool_gateway.approval_requested followed by tool_gateway.call_allowed and tool_gateway.call_completed once you approve. Calls to kv_delete show tool_gateway.call_denied with reasonCode: 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 (or kill) the server and start it again. The new process starts with zero keys and revision 0. There is no in-process reset endpoint by design; restart is the single supported reset.

  • Free the port — if startup logs EADDRINUSE, another kv-demo process is still bound to 8848. 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.