Multi round-trip requests: a tool that asks before it answers
Since 1.0 a tool, or a callable prompt, can stop and ask the client for something: a form for the user to fill in, a URL for the user to visit, a completion from the client's model, or the client's roots. The client answers by making the same call again with the answers attached. MCP 2026-07-28 calls this a multi round-trip request.
There is no session and nothing is kept on the worker between the two calls. That is what lets any pod of the zone take the second call.
The flow
The demo repo's confirm_delete_note asks before it deletes:
from ramen_runtime import InputRequired, elicit, input_responses
def confirm_delete(note: str) -> str:
if note not in NOTES:
return f"Nothing was deleted: there is no note named {note!r}. Notes: {', '.join(NOTES)}."
answer = input_responses().get("confirm")
if answer is None:
raise InputRequired({"confirm": elicit(f'Delete the note "{note}"? This cannot be undone.', CONFIRM)})
confirmed = answer.get("action") == "accept" and (answer.get("content") or {}).get("confirm") is True
if not confirmed:
return f'Nothing was deleted: the note "{note}" is still there.'
remaining = [n for n in NOTES if n != note]
return f'Deleted the note "{note}". Remaining: {", ".join(remaining)}.'
Round one. The client calls the tool and declares that it can show a form:
{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {
"name": "confirm_delete_note", "arguments": {"note": "todo"},
"_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {"elicitation": {}}}}}
The function raises InputRequired, and the worker answers with a result, not an error:
{"jsonrpc": "2.0", "id": 1, "result": {
"resultType": "input_required",
"inputRequests": {"confirm": {"method": "elicitation/create", "params": {
"mode": "form", "message": "Delete the note \"todo\"? This cannot be undone.",
"requestedSchema": {"type": "object", "properties": {"confirm": {"type": "boolean", "title": "Delete it?",
"description": "true deletes the note"}}, "required": ["confirm"]}}}},
"_meta": {"io.modelcontextprotocol/serverInfo": {"name": "ramen-node", "version": "1.0.0"}}}}
Round two. The client shows the form, then sends the same name and arguments with the answer under the
same key:
{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {
"name": "confirm_delete_note", "arguments": {"note": "todo"},
"inputResponses": {"confirm": {"action": "accept", "content": {"confirm": true}}},
"_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {"elicitation": {}}}}}
The function runs again from the top, input_responses() now returns the answers, and the result is an
ordinary one (resultType: "complete", text Deleted the note "todo". Remaining: groceries, ideas.).
A tool may ask for several things at once (several keys), and may ask again on the next round. A key the tool does
not know is the tool's to ignore. inputResponses must be an object whose values are objects; anything else is
-32602.
What a tool can ask for
| Builder | The client receives | The client must have declared |
|---|---|---|
elicit(message, schema) |
elicitation/create, mode: "form" |
elicitation |
elicit_url(message, url) |
elicitation/create, mode: "url" |
elicitation.url |
sample(messages_or_text, max_tokens=100, **params) |
sampling/createMessage |
sampling |
list_roots() |
roots/list |
roots |
Capabilities are read from this request's clientCapabilities. When the tool asks for something the client did
not declare, the call is error -32021 with data.requiredCapabilities naming what is missing (HTTP 400), and
the input request is not sent. A tool can look first with client_capabilities(), or refuse outright:
from ramen_runtime import MissingCapability, client_capabilities, text
def run():
if "sampling" not in client_capabilities():
raise MissingCapability({"sampling": {}})
return text("has sampling")
A form may not ask for a secret. A form's answer passes through the client and the model's context, so the
runtime refuses a form with a field named like a credential, and the call answers a tool error:
input request refused: <key>.<field> looks like a secret; use elicit_url. The exact rule is on
The MCP repo. Send the user to a page of yours with elicit_url instead.
State between the rounds
Because the function runs again from the top, anything it worked out in round one is gone unless it hands it over:
from ramen_runtime import InputRequired, elicit, input_responses, request_state
def run():
state = request_state() # None on the first round
answer = input_responses().get("confirm")
if state is None or answer is None:
raise InputRequired({"confirm": elicit("Please confirm", SCHEMA)}, state={"kind": "request-state"})
...
The worker returns that state to the client as requestState, an opaque string the client sends back unchanged
on the retry. The node verifies it before the function runs, and request_state() returns the original value.
What the string is. base64url(payload) "." base64url(HMAC-SHA256(key, payload)). It is signed, not
encrypted: the client can read the state, so do not put anything in it that the caller should not see. (Values
of the group's secrets that the call resolved are masked in input requests and in the state before they leave the
runtime.)
What it is bound to. The payload carries, next to the tool's state: the caller (the credential that made the
call), the group, the zone, the method, the tool or prompt name, a digest of the call's arguments, and an expiry. A
state presented by another caller, to another tool, with other arguments, in another zone or group, after its
expiry, or altered in any way is refused: -32602 requestState integrity check failed, with reason state_invalid
in the access log. The answer is the same for every one of those cases.
How long it lives. RAMEN_MRTR_TTL_SECS, default 600 seconds. It is read from the worker's own environment
or config file only; the group's deploy file cannot change it. A state is not single-use: within its lifetime the same retry can be
sent again, and the tool runs again.
Which pod can verify it. The key is derived from the zone's RAMEN_SESSION_SECRET, which the console writes
into every zone, so any pod of the zone verifies a state another pod issued. A node started without that secret
generates one per process, and then only the pod that issued a state accepts it.
requestState is present only when the tool gave a state. A tool that keeps nothing between rounds needs none.
Guardrails run on every round
A guardrail on the tool sees each round, not only the first:
preruns before the function on the first call and on every retry. On a retry the rail sees the arguments plus the client's answers under"$inputResponses", so an answer typed by a user (or injected into one) is checked before the tool acts on it.postruns on the final result only. A round that ends in an input request has no result to check.- A blocked round is the usual tool error with
_meta.ramen.guardrail.
What a 2025-06-18 client sees
A client on the older protocol cannot be asked. The same tool, called by such a client, answers a tool error it can read:
For a callable prompt the same text is error -32602. A tool that raises MissingCapability answers
this tool needs a client capability (<names>); it can only run for a client that speaks MCP 2026-07-28. The
function has run up to the point where it asked, so do the asking before any side effect. Say in the tool's
description that it needs a 2026-07-28 client, as the demo tool does.
Golden cases
A golden case can answer the input request, so a tool that asks still gates its deploy. See The MCP repo → Golden cases.
Limits
- Tools and callable prompts can ask. A resource callable cannot.
- A tool with
"task": true, called by a client that declared the tasks extension, starts as a task at once; its input request then arrives through the task (Tasks), not as a first answer. - Works the same over gRPC, where the body carries everything.