## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agents use connected MCP apps through the tool gateway. > - An MCP app can ask the person a question in the middle of a tool call (MCP elicitation). There are two kinds: a form, or a link to open. > - Today a form question is a dead end: > - A 2026-07-28 server's form `input_required` stops with "needs information Paperclip can't collect yet". > - An older server's `elicitation/create` makes a card, but the answer is never sent back, and the server waits on an open stream. > - Paperclip does not declare form support, so compliant servers never ask. > - This pull request shows the question as a card in the task chat. The card names the app, and only a person can answer it. When the person answers, the agent wakes. The agent's repeated call sends the answer to the app exactly once, for both protocol eras. > - The benefit: apps that need a choice or a detail from the person now finish their work. Restarts lose nothing, and no call is left waiting. ## Linked Issues or Issue Description Refs #21140 (stateless MCP client; this PR closes its "form elicitation" follow-up). Refs #21263 (MCP Tasks; this PR shares its card code). Refs #21389 (MCP Tasks follow-ups: the card answer validation item). **Is your feature request related to a problem?** When a connected MCP app asks the person a form question during a tool call, the call stops and cannot continue. A 2026-07-28 server gets a "needs input" error. An older server gets a card whose answer never reaches it. **Describe the solution you'd like** Show the question in the task chat. Let a person answer, skip, or leave it. Wake the agent when the question is resolved. Send the answer on the agent's repeated call, once, with the server's exact state. **Describe alternatives you've considered** Holding the tool call open until the person answers. We rejected this: it holds a stream and a run slot, and it does not survive deploys or restarts. The plan (`doc/plans/2026-11-13-mcp-elicitation.md`) records nine design decisions with their alternatives. ## What Changed - **Plan:** `doc/plans/2026-11-13-mcp-elicitation.md` covers the spec, the inventory, the decisions, the journey, tests, and risks. - **New module `server/src/services/mcp-elicitation.ts`.** It is the single mapping for direct calls and MCP Tasks: - It turns each spec form field into a real card field: text with defaults, number, yes/no, single choice (`enum` and `oneOf`), and multiple choice (`items.enum` and `items.anyOf`). - It turns card answers back into typed `content`. - Answered sends `accept`. Skip sends `decline`. Withdrawn, closed, or expired sends `cancel`. - It refuses forms that ask for passwords, keys, tokens, card numbers, or one-time codes. - It keeps app text plain, so links in it are not clickable. - It seals `requestState` with AES-256-GCM, bound to the company and connection. - **New table `tool_mcp_elicitations`** (migration 0479). It is company-scoped, with one row per question round. It holds a keyed call identity, the sealed state, the questions and their cards, a claim time, and a 24-hour expiry. - **Gateway, stateless servers:** - Paperclip declares `elicitation: {form, url}` on task tool calls. - A form-only `input_required` saves the round, makes the cards, and stops with a wait message. - A repeated call before the person answers stops again without contacting the app. - After the answer, the repeated call claims the round and sends `inputResponses` and the exact `requestState`, once. - A failed send releases the claim. A crash mid-send lets the claim lapse. - **Gateway, older servers:** - Paperclip declares form support at `initialize`. - The first question gets `cancel` at once, so the server never waits. - When the same question (same words and schema) arrives on the repeated call, Paperclip answers it from the card. - **Gateway, mixed rounds and retries:** - A form beside a URL step shows the link first. - A repeated call that stopped for a question runs again in the same run. It is no longer replayed by the per-run idempotency key. - **Cards:** the title is "*App* needs your input". The resolver policy is `human_only`. "Send to *App*" sends the answer. A user comment does not supersede the card. - **Activity log:** new events `tool_gateway.elicitation_sent`, `tool_gateway.elicitation_refused`, and `tool_gateway.elicitation_expired`. They record the action only, never the values. - **MCP Tasks:** task cards use the same mapping and gain the app name, real fields, and `human_only`. A secret or an unsupported form stays unsupported. - **Storybook:** `Tasks and conversations/Questions and approvals/MCP App Questions` has five states: Asking, Answered, Skipped, Expired, and TwoQuestions. The fixtures are generated from the server mapper's output. - **Docs:** `doc/connections/MCP-ELICITATION.md` (linked from the README) is new. `MCP-PROTOCOL-VERSIONS.md` and `MCP-TASKS.md` are updated. ## Verification - `server/src/__tests__/mcp-elicitation.test.ts` has 16 tests. They pass on the branch. - **Red/green:** 9 of the 9 gateway tests fail with master's `tool-gateway.ts` and `mcp-http.ts`. The 7 pure unit tests cover the new module. - The tests use a fake 2026-07-28 server and a fake 2025-06-18 server that asks over the open stream and waits for the reply. - Covered: answer, skip (`decline`), withdraw (`cancel`), two questions at once, a restart while waiting, a crash mid-send, another company with the same app and arguments, expiry, a refused password field, an agent that tries to answer (rejected), and capabilities. - Existing suites: `mcp-tasks`, `mcp-protocol-versions`, `tool-gateway-service`, `tool-gateway`, and `remote-mcp-connectors`. See the results comment below. - Storybook: the five stories render in headless Chromium, and the play tests pass. The only console errors are the 404s from the backend-less API calls that every story makes. - `tsc --noEmit` is clean for `server` and `ui`. `node scripts/storybook-catalog.mjs` passes. ## Risks - **Older servers may start asking questions.** Declaring form support at `initialize` can make older servers ask where they did not before. Mitigation: the first question always gets `cancel` at once, so no call hangs, and the agent gets a clear next step. - **Per-call cost.** Each 2026-07-28 HTTP tool call in a task makes one indexed lookup for a waiting round. Nothing is added before the first token or to agent boot. - **Migration.** One additive table with no backfill, so it is safe to apply online. - **Changed Tasks behavior.** A task card that is withdrawn or closed now sends `cancel` instead of `decline`, as the spec defines. A skipped card still sends `decline`. - **Stale cards.** Expiry is checked only when the agent calls again. A card can sit past 24 hours until the next call. Then it is withdrawn and the app asks again. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code with tool use (shell, file edits, headless browser), with extended reasoning. ## 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 - [x] 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>
8.9 KiB
MCP elicitation: an app's question, answered in the task chat
When a connected MCP app needs to ask the person something in the middle of a tool call, Paperclip handles it in five steps:
- The question appears in the task chat as a card that names the app.
- The agent's call stops with a message telling it to wait.
- A person answers the card.
- Answering wakes the agent.
- The agent repeats the call with the same arguments, and Paperclip sends the answer to the app exactly once.
Nothing blocks while the person thinks, and nothing is held only in memory. A deploy or restart while a question waits loses nothing.
The design and its alternatives are in doc/plans/2026-11-13-mcp-elicitation.md.
What is supported
| App asks | Paperclip does |
|---|---|
A form question, from a stateless (2026-07-28) server (input_required) |
Shows a question card. The repeated call sends inputResponses together with the server's exact requestState |
A form question, from an older (2025-06-18 / 2025-11-25) server (elicitation/create on the open stream) |
Answers cancel at once, so the server never waits, and shows the card. When the same question arrives on the repeated call, Paperclip answers it from the card |
| A URL step (any version) | Shows the provider link, as before. Paperclip never claims the person's consent (MCP-PROTOCOL-VERSIONS.md) |
| A form beside a URL step | The link goes first. On the next call the app asks for the form again |
| A form question inside a background MCP Task | Shows the same card. The answer goes back with tasks/update (MCP-TASKS.md) |
| A password, key, token, card number or one-time code in a form | Refused. No card is shown, and the agent is told the app must use a secure link |
| A schema outside the spec, or a form with no task | Shows no card. The agent gets a clear reason |
Capability
Paperclip declares elicitation: { form: {}, url: {} } in two places:
- 2026-07-28: per request, only on HTTP
tools/callrequests that belong to a task, because that is where a person can answer. - Older HTTP sessions: at
initialize, only on the session that tool calls use, because that is the path that answers questions. Sessions that only read (resources, prompts, listing) declare none, so they are never asked a question they would leave waiting. A 2025-06-18 session gets{}, which means form only. Questions that arrive outside a task are answeredcancelat once.
Stdio apps keep URL only.
How the card works
- Shows which app is asking. The card's title is "App needs your input", using the connection's name. The app's message is shown as plain text: links are not clickable, and secrets are redacted.
- Only people can answer (
resolverPolicy: "human_only"). An agent answering its own tool's question would be consent given on nobody's behalf. - Lets the person review before sending. The form is the standard question form: fields can be edited, and nothing is sent until Send to App. Skip declines.
- Is checked on submit. Required fields, lengths, number ranges and the date format are validated before the card is resolved. Email and web address show a hint and are checked by the app, because the form only checks fixed-width patterns.
- Wakes the agent either way. Answering wakes the agent through the question-response outbox. Skip on an app's question also wakes it (ordinary questions do not), because the decline only reaches the app on the agent's next call.
Each form field maps to one card field:
| Schema | Card field |
|---|---|
string (minLength, maxLength, default) |
Text. The default is filled in |
string with format email / date / date-time / uri |
Text with a hint. date is validated |
number, integer (minimum, maximum, default) |
Number field |
boolean (default) |
Yes / No. The default is marked as recommended |
enum, or oneOf with const + title |
Single choice. Titles are the labels |
array with items.enum or items.anyOf (minItems, maxItems, default) |
Multiple choice |
| No properties | One Continue choice |
Paperclip refuses the following shapes rather than showing part of the form:
- Nested objects.
- Arrays of anything but choices.
- Unknown formats.
- More than 10 fields.
- More than 100 choices.
- More than 4 form questions in one round.
What goes back to the app
| The card | Sent |
|---|---|
| Answered | { action: "accept", content }, with values typed to the schema (choices are sent as their const) |
| Skipped | { action: "decline" } |
| Withdrawn, task closed, expired, or deleted | { action: "cancel" } |
What the agent sees
| Moment | Result |
|---|---|
| The app asks | elicitation_required: "App asked a question, and it is waiting for a person in the task chat. Paperclip wakes you when it is answered; then call this tool again with the same arguments to continue." |
| Repeated before every card is resolved | The same message. The app is not contacted |
| Repeated after | The app's own result for the answer, decline or cancel |
| A secret was asked for | elicitation_sensitive_refused |
| An unsupported form | elicitation_unsupported |
| 10 questions already waiting on the task | elicitation_limit_reached |
The agent never receives the person's answers from Paperclip, only the app's result. Within one run, a repeated side-effecting call normally replays the earlier result. A call that stopped for a question runs again instead.
Storage and recovery
- Table.
tool_mcp_elicitationsholds one row per question round. It is company-scoped and records:- The task, agent, run, connection and grant.
- A keyed call identity, covering endpoint, tool, arguments, grant, agent and any forwarded routing headers (such as a tenant). One tenant's answers never go out with another tenant's headers.
- The server's
requestState, sealed with AES-256-GCM and bound to the company and connection. - Each question's key, words, schema and card.
- Answers. Answers live only on the cards.
- Saving. The round is saved before its cards, and each card has a fixed key. If the process stops between the two, the next call makes the missing card under the same key, so no question is lost or shown twice.
- Who can collect a round. Only the identical call can collect it: same company, task, connection, grant, agent and call identity.
- Older apps that ask several questions. An answer is spent only when the app finishes the whole call. An app that asks Q1 and then Q2 gets Q1's answer again on the next call, without a second card. An app that refuses the reply (an HTTP error) keeps the answer for the next call.
- Keyed retries. A call with an unsent round runs again (instead of replaying its last result, even a failed send) only if it has the same tool and arguments as the saved round.
- One round per call. At most one waiting round exists per call (per question, for older servers), enforced by a unique index. Two matching calls at once share its cards.
- Ask-first actions. An approved action that stops for a question keeps its approval. The repeated call continues the same approved action and sends the answer, with no second approval.
- Claims. A repeated call claims the round before sending. If the process dies mid-send, the claim lapses after the tool timeout plus a minute, and the next call sends again. A failed send releases the claim at once.
- Expiry. Rounds expire after 24 hours, checked when the call is next made; no background poller is involved. Expired cards are withdrawn, so nobody answers a dead question, and the call starts over.
- Activity log. The log records
tool_gateway.elicitation_requested,tool_gateway.elicitation_sent(the actions only, never values),tool_gateway.elicitation_refused(field names only) andtool_gateway.elicitation_expired. Answers are logged asissue.thread_interaction_answered.
MCP Apps
A tool call made from an MCP App view runs in the task's session. Its questions appear in the same chat.
Not supported yet
- Enforcing
minItemsandmaxItemson the card. Today they show as help text, and the app checks them when the answer arrives. - Sampling and roots requests.
- Form questions from stdio apps.
- Forms rendered inside an MCP App view.
input_requiredonresources/readandprompts/get.- Answers to the vendor
_meta.elicitationresult shape, which has no channel for them.
Tests
server/src/__tests__/mcp-elicitation.test.ts covers the following:
- The schema mapping and answer typing.
- The sensitive-field refusal.
- Capabilities.
- A fake stateless server: answer, skip, two questions at once, restart while waiting, a crash mid-send, a second company, expiry, and an agent trying to answer.
- A fake 2025-06-18 server that asks over the open stream.
Stories: Tasks and conversations/Questions and approvals/MCP App Questions.