Files
PaperClipAI/doc/connections/MCP-ELICITATION.md
T
DottaandClaude Opus 5.5 a4c570aede feat(mcp): ask an app's form questions in the task chat and send the answer back (MCP elicitation) (#21466)
## 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>
2026-11-13 19:46:56 -06:00

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:

  1. The question appears in the task chat as a card that names the app.
  2. The agent's call stops with a message telling it to wait.
  3. A person answers the card.
  4. Answering wakes the agent.
  5. 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/call requests 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 answered cancel at 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_elicitations holds 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) and tool_gateway.elicitation_expired. Answers are logged as issue.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 minItems and maxItems on 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_required on resources/read and prompts/get.
  • Answers to the vendor _meta.elicitation result 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.