diff --git a/schema/draft/examples/CreateMessageRequest/sampling-request.json b/schema/draft/examples/CreateMessageRequest/sampling-request.json index 99398b8ea..70a17485f 100644 --- a/schema/draft/examples/CreateMessageRequest/sampling-request.json +++ b/schema/draft/examples/CreateMessageRequest/sampling-request.json @@ -1,6 +1,4 @@ { - "jsonrpc": "2.0", - "id": "sampling-example", "method": "sampling/createMessage", "params": { "messages": [ diff --git a/schema/draft/examples/ElicitRequest/elicitation-request.json b/schema/draft/examples/ElicitRequest/elicitation-request.json index 5b48b7f9c..61e9196ef 100644 --- a/schema/draft/examples/ElicitRequest/elicitation-request.json +++ b/schema/draft/examples/ElicitRequest/elicitation-request.json @@ -1,15 +1,14 @@ { - "jsonrpc": "2.0", - "id": "elicitation-example", "method": "elicitation/create", "params": { - "mode": "form", "message": "Please provide your GitHub username", "requestedSchema": { "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "title": "GitHub Username", + "description": "Your GitHub username" } }, "required": ["name"] diff --git a/schema/draft/examples/ElicitResultResponse/elicitation-result-response.json b/schema/draft/examples/ElicitResultResponse/elicitation-result-response.json deleted file mode 100644 index 762c2fc21..000000000 --- a/schema/draft/examples/ElicitResultResponse/elicitation-result-response.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "jsonrpc": "2.0", - "id": "elicitation-example", - "result": { - "action": "accept", - "content": { - "name": "octocat" - } - } -} diff --git a/schema/draft/examples/GetTaskPayloadRequest/get-task-payload-request.json b/schema/draft/examples/GetTaskPayloadRequest/get-task-payload-request.json new file mode 100644 index 000000000..632846ebd --- /dev/null +++ b/schema/draft/examples/GetTaskPayloadRequest/get-task-payload-request.json @@ -0,0 +1,8 @@ +{ + "jsonrpc": "2.0", + "id": 3, + "method": "tasks/result", + "params": { + "taskId": "echo_dc792e24-01b5-4c0a-abcb-0559848ca3c5" + } +} diff --git a/schema/draft/examples/GetTaskPayloadResultResponse/completed-task-payload-response.json b/schema/draft/examples/GetTaskPayloadResultResponse/completed-task-payload-response.json new file mode 100644 index 000000000..b53b013db --- /dev/null +++ b/schema/draft/examples/GetTaskPayloadResultResponse/completed-task-payload-response.json @@ -0,0 +1,18 @@ +{ + "jsonrpc": "2.0", + "id": 3, + "result": { + "isError": false, + "content": [ + { + "type": "text", + "text": "Echo: Hello World!" + } + ], + "_meta": { + "io.modelcontextprotocol/related-task": { + "taskId": "echo_dc792e24-01b5-4c0a-abcb-0559848ca3c5" + } + } + } +} diff --git a/schema/draft/examples/GetTaskPayloadResultResponse/input-required-task-payload-response.json b/schema/draft/examples/GetTaskPayloadResultResponse/input-required-task-payload-response.json new file mode 100644 index 000000000..3624faa7f --- /dev/null +++ b/schema/draft/examples/GetTaskPayloadResultResponse/input-required-task-payload-response.json @@ -0,0 +1,28 @@ +{ + "jsonrpc": "2.0", + "id": 3, + "result": { + "inputRequests": { + "echo_input": { + "method": "elicitation/create", + "params": { + "message": "Please provide the input string to echo back", + "requestedSchema": { + "type": "object", + "properties": { + "input": { + "type": "string" + } + }, + "required": ["input"] + } + } + } + }, + "_meta": { + "io.modelcontextprotocol/related-task": { + "taskId": "echo_dc792e24-01b5-4c0a-abcb-0559848ca3c5" + } + } + } +} diff --git a/schema/draft/examples/IncompleteResult/incomplete-result-with-elicitation-and-sampling.json b/schema/draft/examples/IncompleteResult/incomplete-result-with-elicitation-and-sampling.json new file mode 100644 index 000000000..5dd7629cb --- /dev/null +++ b/schema/draft/examples/IncompleteResult/incomplete-result-with-elicitation-and-sampling.json @@ -0,0 +1,35 @@ +{ + "inputRequests": { + "github_login": { + "method": "elicitation/create", + "params": { + "message": "Please provide your GitHub username", + "requestedSchema": { + "type": "object", + "properties": { + "name": { + "type": "string" + } + }, + "required": ["name"] + } + } + }, + "capital_of_france": { + "method": "sampling/createMessage", + "params": { + "messages": [ + { + "role": "user", + "content": { + "type": "text", + "text": "What is the capital of France?" + } + } + ], + "maxTokens": 100 + } + } + }, + "requestState": "eyJsb2NhdGlvbiI6Ik5ldyBZb3JrIn0" +} diff --git a/schema/draft/examples/IncompleteResult/incomplete-result-with-input-requests.json b/schema/draft/examples/IncompleteResult/incomplete-result-with-input-requests.json new file mode 100644 index 000000000..49254b9ea --- /dev/null +++ b/schema/draft/examples/IncompleteResult/incomplete-result-with-input-requests.json @@ -0,0 +1,20 @@ +{ + "inputRequests": { + "github_login": { + "method": "elicitation/create", + "params": { + "message": "Please provide your GitHub username", + "requestedSchema": { + "type": "object", + "properties": { + "name": { + "type": "string" + } + }, + "required": ["name"] + } + } + } + }, + "requestState": "eyJsb2NhdGlvbiI6Ik5ldyBZb3JrIn0" +} diff --git a/schema/draft/examples/IncompleteResult/incomplete-result-with-request-state-only.json b/schema/draft/examples/IncompleteResult/incomplete-result-with-request-state-only.json new file mode 100644 index 000000000..7f169a17b --- /dev/null +++ b/schema/draft/examples/IncompleteResult/incomplete-result-with-request-state-only.json @@ -0,0 +1,3 @@ +{ + "requestState": "eyJwcm9ncmVzcyI6IjUwJSIsInN0YXRlIjoicHJvY2Vzc2luZyJ9" +} diff --git a/schema/draft/examples/InputRequest/elicitation-input-request.json b/schema/draft/examples/InputRequest/elicitation-input-request.json new file mode 100644 index 000000000..62cbb8df6 --- /dev/null +++ b/schema/draft/examples/InputRequest/elicitation-input-request.json @@ -0,0 +1,16 @@ +{ + "method": "elicitation/create", + "params": { + "mode": "form", + "message": "Please provide your GitHub username", + "requestedSchema": { + "type": "object", + "properties": { + "name": { + "type": "string" + } + }, + "required": ["name"] + } + } +} diff --git a/schema/draft/examples/InputRequest/sampling-input-request.json b/schema/draft/examples/InputRequest/sampling-input-request.json new file mode 100644 index 000000000..77e74bc18 --- /dev/null +++ b/schema/draft/examples/InputRequest/sampling-input-request.json @@ -0,0 +1,15 @@ +{ + "method": "sampling/createMessage", + "params": { + "messages": [ + { + "role": "user", + "content": { + "type": "text", + "text": "What is the capital of France?" + } + } + ], + "maxTokens": 100 + } +} diff --git a/schema/draft/examples/InputRequests/elicitation-and-sampling-input-requests.json b/schema/draft/examples/InputRequests/elicitation-and-sampling-input-requests.json new file mode 100644 index 000000000..5d1ce974a --- /dev/null +++ b/schema/draft/examples/InputRequests/elicitation-and-sampling-input-requests.json @@ -0,0 +1,33 @@ +{ + "github_login": { + "method": "elicitation/create", + "params": { + "mode": "form", + "message": "Please provide your GitHub username", + "requestedSchema": { + "type": "object", + "properties": { + "name": { + "type": "string" + } + }, + "required": ["name"] + } + } + }, + "capital_of_france": { + "method": "sampling/createMessage", + "params": { + "messages": [ + { + "role": "user", + "content": { + "type": "text", + "text": "What is the capital of France?" + } + } + ], + "maxTokens": 100 + } + } +} diff --git a/schema/draft/examples/InputResponse/elicitation-input-response.json b/schema/draft/examples/InputResponse/elicitation-input-response.json new file mode 100644 index 000000000..4798da663 --- /dev/null +++ b/schema/draft/examples/InputResponse/elicitation-input-response.json @@ -0,0 +1,6 @@ +{ + "action": "accept", + "content": { + "name": "octocat" + } +} diff --git a/schema/draft/examples/InputResponse/sampling-input-response.json b/schema/draft/examples/InputResponse/sampling-input-response.json new file mode 100644 index 000000000..529f683f5 --- /dev/null +++ b/schema/draft/examples/InputResponse/sampling-input-response.json @@ -0,0 +1,9 @@ +{ + "role": "assistant", + "content": { + "type": "text", + "text": "The capital of France is Paris." + }, + "model": "claude-3-sonnet-20240307", + "stopReason": "endTurn" +} diff --git a/schema/draft/examples/CreateMessageResultResponse/sampling-result-response.json b/schema/draft/examples/InputResponses/elicitation-and-sampling-input-responses.json similarity index 61% rename from schema/draft/examples/CreateMessageResultResponse/sampling-result-response.json rename to schema/draft/examples/InputResponses/elicitation-and-sampling-input-responses.json index 1597d566f..1f5cbcf0d 100644 --- a/schema/draft/examples/CreateMessageResultResponse/sampling-result-response.json +++ b/schema/draft/examples/InputResponses/elicitation-and-sampling-input-responses.json @@ -1,7 +1,11 @@ { - "jsonrpc": "2.0", - "id": "sampling-example", - "result": { + "github_login": { + "action": "accept", + "content": { + "name": "octocat" + } + }, + "capital_of_france": { "role": "assistant", "content": { "type": "text", diff --git a/schema/draft/examples/ListRootsResultResponse/list-roots-result-response.json b/schema/draft/examples/ListRootsResultResponse/list-roots-result-response.json deleted file mode 100644 index 1e7e15393..000000000 --- a/schema/draft/examples/ListRootsResultResponse/list-roots-result-response.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "jsonrpc": "2.0", - "id": "list-roots-example", - "result": { - "roots": [ - { - "uri": "file:///home/user/projects/myproject", - "name": "My Project" - } - ] - } -} diff --git a/schema/draft/examples/TaskInputResponseRequest/task-input-response-request.json b/schema/draft/examples/TaskInputResponseRequest/task-input-response-request.json new file mode 100644 index 000000000..f919cbdc5 --- /dev/null +++ b/schema/draft/examples/TaskInputResponseRequest/task-input-response-request.json @@ -0,0 +1,20 @@ +{ + "jsonrpc": "2.0", + "id": 4, + "method": "tasks/input_response", + "params": { + "inputResponses": { + "echo_input": { + "action": "accept", + "content": { + "input": "Hello World!" + } + } + }, + "_meta": { + "io.modelcontextprotocol/related-task": { + "taskId": "echo_dc792e24-01b5-4c0a-abcb-0559848ca3c5" + } + } + } +} diff --git a/schema/draft/examples/TaskInputResponseRequestParams/task-input-response-params.json b/schema/draft/examples/TaskInputResponseRequestParams/task-input-response-params.json new file mode 100644 index 000000000..e95070aab --- /dev/null +++ b/schema/draft/examples/TaskInputResponseRequestParams/task-input-response-params.json @@ -0,0 +1,15 @@ +{ + "inputResponses": { + "echo_input": { + "action": "accept", + "content": { + "input": "Hello World!" + } + } + }, + "_meta": { + "io.modelcontextprotocol/related-task": { + "taskId": "echo_dc792e24-01b5-4c0a-abcb-0559848ca3c5" + } + } +} diff --git a/schema/draft/examples/URLElicitationRequiredError/authorization-required.json b/schema/draft/examples/URLElicitationRequiredError/authorization-required.json deleted file mode 100644 index 83b73dabc..000000000 --- a/schema/draft/examples/URLElicitationRequiredError/authorization-required.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "jsonrpc": "2.0", - "id": 2, - "error": { - "code": -32042, - "message": "This request requires more information.", - "data": { - "elicitations": [ - { - "mode": "url", - "elicitationId": "550e8400-e29b-41d4-a716-446655440000", - "url": "https://mcp.example.com/connect?elicitationId=550e8400-e29b-41d4-a716-446655440000", - "message": "Authorization is required to access your Example Co files." - } - ] - } - } -} diff --git a/schema/draft/schema.json b/schema/draft/schema.json index 6757370cf..e003c557f 100644 --- a/schema/draft/schema.json +++ b/schema/draft/schema.json @@ -156,10 +156,16 @@ "description": "Arguments to use for the tool call.", "type": "object" }, + "inputResponses": { + "$ref": "#/$defs/InputResponses" + }, "name": { "description": "The name of the tool.", "type": "string" }, + "requestState": { + "type": "string" + }, "task": { "$ref": "#/$defs/TaskMetadata", "description": "If specified, the caller is requesting task-augmented execution for this request.\nThe request will return a {@link CreateTaskResult} immediately, and the actual result can be\nretrieved later via {@link GetTaskPayloadRequesttasks/result}.\n\nTask augmentation is subject to capability negotiation - receivers MUST declare support\nfor task augmentation of specific request types in their capabilities." @@ -209,7 +215,14 @@ "type": "string" }, "result": { - "$ref": "#/$defs/CallToolResult" + "anyOf": [ + { + "$ref": "#/$defs/IncompleteResult" + }, + { + "$ref": "#/$defs/CallToolResult" + } + ] } }, "required": [ @@ -425,7 +438,7 @@ "properties": { "createMessage": { "additionalProperties": true, - "description": "Whether the client supports task-augmented `sampling/createMessage` requests.", + "description": "Whether the client supports task-augmented {@link CreateMessageRequestsampling/createMessage} requests.", "properties": {}, "type": "object" } @@ -501,6 +514,9 @@ { "$ref": "#/$defs/GetTaskPayloadRequest" }, + { + "$ref": "#/$defs/TaskInputResponseRequest" + }, { "$ref": "#/$defs/CancelTaskRequest" }, @@ -520,6 +536,9 @@ { "$ref": "#/$defs/Result" }, + { + "$ref": "#/$defs/ListRootsResult" + }, { "$ref": "#/$defs/GetTaskResult", "description": "The result returned for a {@link GetTaskRequesttasks/get} request." @@ -533,15 +552,6 @@ }, { "$ref": "#/$defs/ListTasksResult" - }, - { - "$ref": "#/$defs/CreateMessageResult" - }, - { - "$ref": "#/$defs/ListRootsResult" - }, - { - "$ref": "#/$defs/ElicitResult" } ] }, @@ -608,6 +618,9 @@ }, "type": "object" }, + "inputResponses": { + "$ref": "#/$defs/InputResponses" + }, "ref": { "anyOf": [ { @@ -617,6 +630,9 @@ "$ref": "#/$defs/ResourceTemplateReference" } ] + }, + "requestState": { + "type": "string" } }, "required": [ @@ -703,13 +719,6 @@ "CreateMessageRequest": { "description": "A request from the server to sample an LLM via the client. The client has full discretion over which model to select. The client should also inform the user before beginning sampling, to allow them to inspect the request (human in the loop) and decide whether to approve it.", "properties": { - "id": { - "$ref": "#/$defs/RequestId" - }, - "jsonrpc": { - "const": "2.0", - "type": "string" - }, "method": { "const": "sampling/createMessage", "type": "string" @@ -719,8 +728,6 @@ } }, "required": [ - "id", - "jsonrpc", "method", "params" ], @@ -741,6 +748,9 @@ ], "type": "string" }, + "inputResponses": { + "$ref": "#/$defs/InputResponses" + }, "maxTokens": { "description": "The requested maximum number of tokens to sample (to prevent runaway completions).\n\nThe client MAY choose to sample fewer tokens than the requested maximum.", "type": "integer" @@ -761,6 +771,9 @@ "$ref": "#/$defs/ModelPreferences", "description": "The server's preferences for which model to select. The client MAY ignore these preferences." }, + "requestState": { + "type": "string" + }, "stopSequences": { "items": { "type": "string" @@ -846,27 +859,6 @@ ], "type": "object" }, - "CreateMessageResultResponse": { - "description": "A successful response from the client for a {@link CreateMessageRequestsampling/createMessage} request.", - "properties": { - "id": { - "$ref": "#/$defs/RequestId" - }, - "jsonrpc": { - "const": "2.0", - "type": "string" - }, - "result": { - "$ref": "#/$defs/CreateMessageResult" - } - }, - "required": [ - "id", - "jsonrpc", - "result" - ], - "type": "object" - }, "CreateTaskResult": { "description": "The result returned for a task-augmented request.", "properties": { @@ -910,13 +902,6 @@ "ElicitRequest": { "description": "A request from the server to elicit additional information from the user via the client.", "properties": { - "id": { - "$ref": "#/$defs/RequestId" - }, - "jsonrpc": { - "const": "2.0", - "type": "string" - }, "method": { "const": "elicitation/create", "type": "string" @@ -926,8 +911,6 @@ } }, "required": [ - "id", - "jsonrpc", "method", "params" ], @@ -939,6 +922,9 @@ "_meta": { "$ref": "#/$defs/RequestMetaObject" }, + "inputResponses": { + "$ref": "#/$defs/InputResponses" + }, "message": { "description": "The message to present to the user describing what information is being requested.", "type": "string" @@ -948,6 +934,9 @@ "description": "The elicitation mode.", "type": "string" }, + "requestState": { + "type": "string" + }, "requestedSchema": { "description": "A restricted subset of JSON Schema.\nOnly top-level properties are allowed, without nesting.", "properties": { @@ -991,10 +980,10 @@ "ElicitRequestParams": { "anyOf": [ { - "$ref": "#/$defs/ElicitRequestURLParams" + "$ref": "#/$defs/ElicitRequestFormParams" }, { - "$ref": "#/$defs/ElicitRequestFormParams" + "$ref": "#/$defs/ElicitRequestURLParams" } ], "description": "The parameters for a request to elicit additional information from the user via the client." @@ -1009,6 +998,9 @@ "description": "The ID of the elicitation, which must be unique within the context of the server.\nThe client MUST treat this ID as an opaque value.", "type": "string" }, + "inputResponses": { + "$ref": "#/$defs/InputResponses" + }, "message": { "description": "The message to present to the user explaining why the interaction is needed.", "type": "string" @@ -1018,6 +1010,9 @@ "description": "The elicitation mode.", "type": "string" }, + "requestState": { + "type": "string" + }, "task": { "$ref": "#/$defs/TaskMetadata", "description": "If specified, the caller is requesting task-augmented execution for this request.\nThe request will return a {@link CreateTaskResult} immediately, and the actual result can be\nretrieved later via {@link GetTaskPayloadRequesttasks/result}.\n\nTask augmentation is subject to capability negotiation - receivers MUST declare support\nfor task augmentation of specific request types in their capabilities." @@ -1037,11 +1032,8 @@ "type": "object" }, "ElicitResult": { - "description": "The result returned by the client for an {@link ElicitRequestelicitation/create} request.", + "description": "The result returned by the client for an {@link ElicitationCreateRequest elicitation/create} request.", "properties": { - "_meta": { - "$ref": "#/$defs/MetaObject" - }, "action": { "description": "The user action in response to the elicitation.\n- `\"accept\"`: User submitted the form/confirmed the action\n- `\"decline\"`: User explicitly declined the action\n- `\"cancel\"`: User dismissed without making an explicit choice", "enum": [ @@ -1078,27 +1070,6 @@ ], "type": "object" }, - "ElicitResultResponse": { - "description": "A successful response from the client for a {@link ElicitRequestelicitation/create} request.", - "properties": { - "id": { - "$ref": "#/$defs/RequestId" - }, - "jsonrpc": { - "const": "2.0", - "type": "string" - }, - "result": { - "$ref": "#/$defs/ElicitResult" - } - }, - "required": [ - "id", - "jsonrpc", - "result" - ], - "type": "object" - }, "ElicitationCompleteNotification": { "description": "An optional notification from the server to the client, informing it of a completion of a out-of-band elicitation request.", "properties": { @@ -1243,9 +1214,15 @@ "description": "Arguments to use for templating the prompt.", "type": "object" }, + "inputResponses": { + "$ref": "#/$defs/InputResponses" + }, "name": { "description": "The name of the prompt or prompt template.", "type": "string" + }, + "requestState": { + "type": "string" } }, "required": [ @@ -1286,7 +1263,14 @@ "type": "string" }, "result": { - "$ref": "#/$defs/GetPromptResult" + "anyOf": [ + { + "$ref": "#/$defs/IncompleteResult" + }, + { + "$ref": "#/$defs/GetPromptResult" + } + ] } }, "required": [ @@ -1297,7 +1281,7 @@ "type": "object" }, "GetTaskPayloadRequest": { - "description": "A request to retrieve the result of a completed task.", + "description": "A request to retrieve the result of a completed task, or to discover\nwhat input is needed for a task in `input_required` status.", "properties": { "id": { "$ref": "#/$defs/RequestId" @@ -1333,7 +1317,7 @@ }, "GetTaskPayloadResult": { "additionalProperties": {}, - "description": "The result returned for a {@link GetTaskPayloadRequesttasks/result} request.\nThe structure matches the result type of the original request.\nFor example, a {@link CallToolRequesttools/call} task would return the {@link CallToolResult} structure.", + "description": "The result returned for a {@link GetTaskPayloadRequesttasks/result} request.\nThe structure matches the result type of the original request.\nFor example, a {@link CallToolRequesttools/call} task would return the {@link CallToolResult} structure.\n\nWhen the task is in `input_required` status, the server MUST return an\n{@link IncompleteResult} containing `inputRequests` that the client must\nfulfill via a {@link TaskInputResponseRequesttasks/input_response} request.", "properties": { "_meta": { "$ref": "#/$defs/MetaObject" @@ -1342,7 +1326,7 @@ "type": "object" }, "GetTaskPayloadResultResponse": { - "description": "A successful response for a {@link GetTaskPayloadRequesttasks/result} request.", + "description": "A successful response for a {@link GetTaskPayloadRequesttasks/result} request.\nMay be either a complete result or an {@link IncompleteResult} indicating\nthat additional input is needed via {@link TaskInputResponseRequesttasks/input_response}.", "properties": { "id": { "$ref": "#/$defs/RequestId" @@ -1352,7 +1336,14 @@ "type": "string" }, "result": { - "$ref": "#/$defs/GetTaskPayloadResult" + "anyOf": [ + { + "$ref": "#/$defs/IncompleteResult" + }, + { + "$ref": "#/$defs/GetTaskPayloadResult" + } + ] } }, "required": [ @@ -1544,6 +1535,21 @@ ], "type": "object" }, + "IncompleteResult": { + "description": "An IncompleteResult sent by the server to indicate that additional input is needed\nbefore the request can be completed. \n\nAt least one of `inputRequests` or `requestState` MUST be present.", + "properties": { + "_meta": { + "$ref": "#/$defs/MetaObject" + }, + "inputRequests": { + "$ref": "#/$defs/InputRequests" + }, + "requestState": { + "type": "string" + } + }, + "type": "object" + }, "InitializeRequest": { "description": "This request is sent from the client to the server when it first connects, asking it to begin initialization.", "properties": { @@ -1664,6 +1670,46 @@ ], "type": "object" }, + "InputRequest": { + "anyOf": [ + { + "$ref": "#/$defs/CreateMessageRequest" + }, + { + "$ref": "#/$defs/ListRootsRequest" + }, + { + "$ref": "#/$defs/ElicitRequest" + } + ] + }, + "InputRequests": { + "additionalProperties": { + "$ref": "#/$defs/InputRequest" + }, + "description": "A map of server-initiated requests that the client must fulfill.\nKeys are server-assigned identifiers; values are the request objects.", + "type": "object" + }, + "InputResponse": { + "anyOf": [ + { + "$ref": "#/$defs/CreateMessageResult" + }, + { + "$ref": "#/$defs/ListRootsResult" + }, + { + "$ref": "#/$defs/ElicitResult" + } + ] + }, + "InputResponses": { + "additionalProperties": { + "$ref": "#/$defs/InputResponse" + }, + "description": "A map of client responses to server-initiated requests.\nKeys correspond to the keys in the {@link InputRequests} map;\nvalues are the client's result for each request.", + "type": "object" + }, "InternalError": { "description": "A JSON-RPC error indicating that an internal error occurred on the receiver. This error is returned when the receiver encounters an unexpected condition that prevents it from fulfilling the request.", "properties": { @@ -1939,7 +1985,14 @@ "type": "string" }, "result": { - "$ref": "#/$defs/ListPromptsResult" + "anyOf": [ + { + "$ref": "#/$defs/IncompleteResult" + }, + { + "$ref": "#/$defs/ListPromptsResult" + } + ] } }, "required": [ @@ -2007,7 +2060,14 @@ "type": "string" }, "result": { - "$ref": "#/$defs/ListResourceTemplatesResult" + "anyOf": [ + { + "$ref": "#/$defs/IncompleteResult" + }, + { + "$ref": "#/$defs/ListResourceTemplatesResult" + } + ] } }, "required": [ @@ -2075,7 +2135,14 @@ "type": "string" }, "result": { - "$ref": "#/$defs/ListResourcesResult" + "anyOf": [ + { + "$ref": "#/$defs/IncompleteResult" + }, + { + "$ref": "#/$defs/ListResourcesResult" + } + ] } }, "required": [ @@ -2088,13 +2155,6 @@ "ListRootsRequest": { "description": "Sent from the server to request a list of root URIs from the client. Roots allow\nservers to ask for specific directories or files to operate on. A common example\nfor roots is providing a set of repositories or directories a server should operate\non.\n\nThis request is typically used when the server needs to understand the file system\nstructure or access specific locations that the client has permission to read from.", "properties": { - "id": { - "$ref": "#/$defs/RequestId" - }, - "jsonrpc": { - "const": "2.0", - "type": "string" - }, "method": { "const": "roots/list", "type": "string" @@ -2104,8 +2164,6 @@ } }, "required": [ - "id", - "jsonrpc", "method" ], "type": "object" @@ -2113,9 +2171,6 @@ "ListRootsResult": { "description": "The result returned by the client for a {@link ListRootsRequestroots/list} request.\nThis result contains an array of {@link Root} objects, each representing a root directory\nor file that the server can operate on.", "properties": { - "_meta": { - "$ref": "#/$defs/MetaObject" - }, "roots": { "items": { "$ref": "#/$defs/Root" @@ -2128,27 +2183,6 @@ ], "type": "object" }, - "ListRootsResultResponse": { - "description": "A successful response from the client for a {@link ListRootsRequestroots/list} request.", - "properties": { - "id": { - "$ref": "#/$defs/RequestId" - }, - "jsonrpc": { - "const": "2.0", - "type": "string" - }, - "result": { - "$ref": "#/$defs/ListRootsResult" - } - }, - "required": [ - "id", - "jsonrpc", - "result" - ], - "type": "object" - }, "ListTasksRequest": { "description": "A request to retrieve a list of tasks.", "properties": { @@ -2275,7 +2309,14 @@ "type": "string" }, "result": { - "$ref": "#/$defs/ListToolsResult" + "anyOf": [ + { + "$ref": "#/$defs/IncompleteResult" + }, + { + "$ref": "#/$defs/ListToolsResult" + } + ] } }, "required": [ @@ -2833,6 +2874,12 @@ "_meta": { "$ref": "#/$defs/RequestMetaObject" }, + "inputResponses": { + "$ref": "#/$defs/InputResponses" + }, + "requestState": { + "type": "string" + }, "uri": { "description": "The URI of the resource. The URI can use any protocol; it is up to the server how to interpret it.", "format": "uri", @@ -2880,7 +2927,14 @@ "type": "string" }, "result": { - "$ref": "#/$defs/ReadResourceResult" + "anyOf": [ + { + "$ref": "#/$defs/IncompleteResult" + }, + { + "$ref": "#/$defs/ReadResourceResult" + } + ] } }, "required": [ @@ -3095,6 +3149,12 @@ "_meta": { "$ref": "#/$defs/RequestMetaObject" }, + "inputResponses": { + "$ref": "#/$defs/InputResponses" + }, + "requestState": { + "type": "string" + }, "uri": { "description": "The URI of the resource. The URI can use any protocol; it is up to the server how to interpret it.", "format": "uri", @@ -3219,6 +3279,20 @@ }, "type": "object" }, + "RetryAugmentedRequestParams": { + "properties": { + "_meta": { + "$ref": "#/$defs/RequestMetaObject" + }, + "inputResponses": { + "$ref": "#/$defs/InputResponses" + }, + "requestState": { + "type": "string" + } + }, + "type": "object" + }, "Role": { "description": "The sender or recipient of messages and data in a conversation.", "enum": [ @@ -3468,6 +3542,9 @@ }, "ServerRequest": { "anyOf": [ + { + "$ref": "#/$defs/ListRootsRequest" + }, { "$ref": "#/$defs/PingRequest" }, @@ -3482,15 +3559,6 @@ }, { "$ref": "#/$defs/ListTasksRequest" - }, - { - "$ref": "#/$defs/CreateMessageRequest" - }, - { - "$ref": "#/$defs/ListRootsRequest" - }, - { - "$ref": "#/$defs/ElicitRequest" } ] }, @@ -3499,6 +3567,9 @@ { "$ref": "#/$defs/Result" }, + { + "$ref": "#/$defs/IncompleteResult" + }, { "$ref": "#/$defs/InitializeResult" }, @@ -3686,6 +3757,12 @@ "_meta": { "$ref": "#/$defs/RequestMetaObject" }, + "inputResponses": { + "$ref": "#/$defs/InputResponses" + }, + "requestState": { + "type": "string" + }, "uri": { "description": "The URI of the resource. The URI can use any protocol; it is up to the server how to interpret it.", "format": "uri", @@ -3765,11 +3842,87 @@ "_meta": { "$ref": "#/$defs/RequestMetaObject" }, + "inputResponses": { + "$ref": "#/$defs/InputResponses" + }, + "requestState": { + "type": "string" + }, + "task": { + "$ref": "#/$defs/TaskMetadata", + "description": "If specified, the caller is requesting task-augmented execution for this request.\nThe request will return a {@link CreateTaskResult} immediately, and the actual result can be\nretrieved later via {@link GetTaskPayloadRequesttasks/result}.\n\nTask augmentation is subject to capability negotiation - receivers MUST declare support\nfor task augmentation of specific request types in their capabilities." + } + }, + "type": "object" + }, + "TaskInputResponseRequest": { + "description": "A request from the client to deliver input responses for a task\nthat is in `input_required` status.", + "properties": { + "id": { + "$ref": "#/$defs/RequestId" + }, + "jsonrpc": { + "const": "2.0", + "type": "string" + }, + "method": { + "const": "tasks/input_response", + "type": "string" + }, + "params": { + "$ref": "#/$defs/TaskInputResponseRequestParams" + } + }, + "required": [ + "id", + "jsonrpc", + "method", + "params" + ], + "type": "object" + }, + "TaskInputResponseRequestParams": { + "description": "Parameters for a `tasks/input_response` request.\nUsed to deliver client responses to server-initiated input requests\nfor a task in the persistent multi round-trip workflow.", + "properties": { + "_meta": { + "$ref": "#/$defs/RequestMetaObject" + }, + "inputResponses": { + "$ref": "#/$defs/InputResponses", + "description": "The client's responses to the server's input requests." + }, + "requestState": { + "type": "string" + }, "task": { "$ref": "#/$defs/TaskMetadata", "description": "If specified, the caller is requesting task-augmented execution for this request.\nThe request will return a {@link CreateTaskResult} immediately, and the actual result can be\nretrieved later via {@link GetTaskPayloadRequesttasks/result}.\n\nTask augmentation is subject to capability negotiation - receivers MUST declare support\nfor task augmentation of specific request types in their capabilities." } }, + "required": [ + "inputResponses" + ], + "type": "object" + }, + "TaskInputResponseResultResponse": { + "description": "A successful response for a {@link TaskInputResponseRequesttasks/input_response} request.", + "properties": { + "id": { + "$ref": "#/$defs/RequestId" + }, + "jsonrpc": { + "const": "2.0", + "type": "string" + }, + "result": { + "$ref": "#/$defs/Result" + } + }, + "required": [ + "id", + "jsonrpc", + "result" + ], "type": "object" }, "TaskMetadata": { @@ -4239,58 +4392,6 @@ ], "type": "object" }, - "URLElicitationRequiredError": { - "description": "An error response that indicates that the server requires the client to provide additional information via an elicitation request.", - "properties": { - "error": { - "allOf": [ - { - "$ref": "#/$defs/Error" - }, - { - "properties": { - "code": { - "const": -32042, - "type": "integer" - }, - "data": { - "additionalProperties": {}, - "properties": { - "elicitations": { - "items": { - "$ref": "#/$defs/ElicitRequestURLParams" - }, - "type": "array" - } - }, - "required": [ - "elicitations" - ], - "type": "object" - } - }, - "required": [ - "code", - "data" - ], - "type": "object" - } - ] - }, - "id": { - "$ref": "#/$defs/RequestId" - }, - "jsonrpc": { - "const": "2.0", - "type": "string" - } - }, - "required": [ - "error", - "jsonrpc" - ], - "type": "object" - }, "UnsubscribeRequest": { "description": "Sent from the client to request cancellation of {@link ResourceUpdatedNotificationresources/updated} notifications from the server. This should follow a previous {@link SubscribeRequestresources/subscribe} request.", "properties": { @@ -4323,6 +4424,12 @@ "_meta": { "$ref": "#/$defs/RequestMetaObject" }, + "inputResponses": { + "$ref": "#/$defs/InputResponses" + }, + "requestState": { + "type": "string" + }, "uri": { "description": "The URI of the resource. The URI can use any protocol; it is up to the server how to interpret it.", "format": "uri", diff --git a/schema/draft/schema.mdx b/schema/draft/schema.mdx index a2a4d9336..5ec2a5bda 100644 --- a/schema/draft/schema.mdx +++ b/schema/draft/schema.mdx @@ -104,6 +104,14 @@ title: Schema Reference {/* @category `tasks/cancel` */} +## `tasks/input_response` + +{/* @category `tasks/input_response` */} + +## Multi Round-Trip + +{/* @category Multi Round-Trip */} + ## `prompts/get` {/* @category `prompts/get` */} diff --git a/schema/draft/schema.ts b/schema/draft/schema.ts index f89665acc..012cff21e 100644 --- a/schema/draft/schema.ts +++ b/schema/draft/schema.ts @@ -69,7 +69,7 @@ export type Cursor = string; * * @internal */ -export interface TaskAugmentedRequestParams extends RequestParams { +export interface TaskAugmentedRequestParams extends RetryAugmentedRequestParams { /** * If specified, the caller is requesting task-augmented execution for this request. * The request will return a {@link CreateTaskResult} immediately, and the actual result can be @@ -296,38 +296,96 @@ export interface InternalError extends Error { code: typeof INTERNAL_ERROR; } -// Implementation-specific JSON-RPC error codes [-32000, -32099] +/* Empty result */ +/** + * A result that indicates success but carries no data. + * + * @category Common Types + */ +export type EmptyResult = Result; + /** @internal */ -export const URL_ELICITATION_REQUIRED = -32042; +export type InputRequest = + | CreateMessageRequest + | ListRootsRequest + | ElicitRequest; + +/** @internal */ +export type InputResponse = + | CreateMessageResult + | ListRootsResult + | ElicitResult; /** - * An error response that indicates that the server requires the client to provide additional information via an elicitation request. + * A map of server-initiated requests that the client must fulfill. + * Keys are server-assigned identifiers; values are the request objects. * - * @example Authorization required - * {@includeCode ./examples/URLElicitationRequiredError/authorization-required.json} + * @example Elicitation and sampling input requests + * {@includeCode ./examples/InputRequests/elicitation-and-sampling-input-requests.json} * - * @internal + * @category Multi Round-Trip */ -export interface URLElicitationRequiredError extends Omit< - JSONRPCErrorResponse, - "error" -> { - error: Error & { - code: typeof URL_ELICITATION_REQUIRED; - data: { - elicitations: ElicitRequestURLParams[]; - [key: string]: unknown; - }; - }; +export interface InputRequests { + [key: string]: InputRequest; } -/* Empty result */ /** - * A result that indicates success but carries no data. + * A map of client responses to server-initiated requests. + * Keys correspond to the keys in the {@link InputRequests} map; + * values are the client's result for each request. * - * @category Common Types + * @example Elicitation and sampling input responses + * {@includeCode ./examples/InputResponses/elicitation-and-sampling-input-responses.json} + * + * @category Multi Round-Trip */ -export type EmptyResult = Result; +export interface InputResponses { + [key: string]: InputResponse; +} + +/** + * An IncompleteResult sent by the server to indicate that additional input is needed + * before the request can be completed. + * + * At least one of `inputRequests` or `requestState` MUST be present. + * + * @example Incomplete result with input requests + * {@includeCode ./examples/IncompleteResult/incomplete-result-with-input-requests.json} + * + * @example Incomplete result with elicitation and sampling input requests + * {@includeCode ./examples/IncompleteResult/incomplete-result-with-elicitation-and-sampling.json} + * + * @example Incomplete result with request state only (load shedding) + * {@includeCode ./examples/IncompleteResult/incomplete-result-with-request-state-only.json} + * + * @category Multi Round-Trip + */ +export interface IncompleteResult extends Result { + /* Requests issued by the server that must be complete before the + * client can retry the original request. + */ + inputRequests?: InputRequests; + /* Request state to be passed back to the server when the client + * retries the original request. + * Note: The client must treat this as an opaque blob; it must not + * interpret it in any way. + */ + requestState?: string; +} + +/* New request parameter type that includes fields in a retried request. + * These parameters may be included in any client-initiated request. + */ +export interface RetryAugmentedRequestParams extends RequestParams { + /* New field to carry the responses for the server's requests from the + * IncompleteResult message. For each key in the response's inputRequests + * field, the same key must appear here with the associated response. + */ + inputResponses?: InputResponses; + /* Request state passed back to the server from the client. + */ + requestState?: string; +} /* Cancellation */ /** @@ -540,7 +598,7 @@ export interface ClientCapabilities { */ sampling?: { /** - * Whether the client supports task-augmented `sampling/createMessage` requests. + * Whether the client supports task-augmented {@link CreateMessageRequest | sampling/createMessage} requests. */ createMessage?: object; }; @@ -934,7 +992,7 @@ export interface ListResourcesResult extends PaginatedResult { * @category `resources/list` */ export interface ListResourcesResultResponse extends JSONRPCResultResponse { - result: ListResourcesResult; + result: ListResourcesResult | IncompleteResult; } /** @@ -970,7 +1028,7 @@ export interface ListResourceTemplatesResult extends PaginatedResult { * @category `resources/templates/list` */ export interface ListResourceTemplatesResultResponse extends JSONRPCResultResponse { - result: ListResourceTemplatesResult; + result: ListResourceTemplatesResult | IncompleteResult; } /** @@ -978,7 +1036,7 @@ export interface ListResourceTemplatesResultResponse extends JSONRPCResultRespon * * @internal */ -export interface ResourceRequestParams extends RequestParams { +export interface ResourceRequestParams extends RetryAugmentedRequestParams { /** * The URI of the resource. The URI can use any protocol; it is up to the server how to interpret it. * @@ -1029,7 +1087,7 @@ export interface ReadResourceResult extends Result { * @category `resources/read` */ export interface ReadResourceResultResponse extends JSONRPCResultResponse { - result: ReadResourceResult; + result: ReadResourceResult | IncompleteResult; } /** @@ -1302,7 +1360,7 @@ export interface ListPromptsResult extends PaginatedResult { * @category `prompts/list` */ export interface ListPromptsResultResponse extends JSONRPCResultResponse { - result: ListPromptsResult; + result: ListPromptsResult | IncompleteResult; } /** @@ -1313,7 +1371,7 @@ export interface ListPromptsResultResponse extends JSONRPCResultResponse { * * @category `prompts/get` */ -export interface GetPromptRequestParams extends RequestParams { +export interface GetPromptRequestParams extends RetryAugmentedRequestParams { /** * The name of the prompt or prompt template. */ @@ -1362,7 +1420,7 @@ export interface GetPromptResult extends Result { * @category `prompts/get` */ export interface GetPromptResultResponse extends JSONRPCResultResponse { - result: GetPromptResult; + result: GetPromptResult | IncompleteResult; } /** @@ -1503,7 +1561,7 @@ export interface ListToolsResult extends PaginatedResult { * @category `tools/list` */ export interface ListToolsResultResponse extends JSONRPCResultResponse { - result: ListToolsResult; + result: ListToolsResult | IncompleteResult; } /** @@ -1557,7 +1615,7 @@ export interface CallToolResult extends Result { * @category `tools/call` */ export interface CallToolResultResponse extends JSONRPCResultResponse { - result: CallToolResult; + result: CallToolResult | IncompleteResult; } /** @@ -1884,7 +1942,11 @@ export interface GetTaskResultResponse extends JSONRPCResultResponse { } /** - * A request to retrieve the result of a completed task. + * A request to retrieve the result of a completed task, or to discover + * what input is needed for a task in `input_required` status. + * + * @example Get task payload request + * {@includeCode ./examples/GetTaskPayloadRequest/get-task-payload-request.json} * * @category `tasks/result` */ @@ -1903,6 +1965,16 @@ export interface GetTaskPayloadRequest extends JSONRPCRequest { * The structure matches the result type of the original request. * For example, a {@link CallToolRequest | tools/call} task would return the {@link CallToolResult} structure. * + * When the task is in `input_required` status, the server MUST return an + * {@link IncompleteResult} containing `inputRequests` that the client must + * fulfill via a {@link TaskInputResponseRequest | tasks/input_response} request. + * + * @example Completed task payload + * {@includeCode ./examples/GetTaskPayloadResult/completed-task-payload.json} + * + * @example Input required task payload + * {@includeCode ./examples/GetTaskPayloadResult/input-required-task-payload.json} + * * @category `tasks/result` */ export interface GetTaskPayloadResult extends Result { @@ -1911,11 +1983,42 @@ export interface GetTaskPayloadResult extends Result { /** * A successful response for a {@link GetTaskPayloadRequest | tasks/result} request. + * May be either a complete result or an {@link IncompleteResult} indicating + * that additional input is needed via {@link TaskInputResponseRequest | tasks/input_response}. + * + * @example Completed task payload response + * {@includeCode ./examples/GetTaskPayloadResultResponse/completed-task-payload-response.json} + * + * @example Input required task payload response + * {@includeCode ./examples/GetTaskPayloadResultResponse/input-required-task-payload-response.json} * * @category `tasks/result` */ export interface GetTaskPayloadResultResponse extends JSONRPCResultResponse { - result: GetTaskPayloadResult; + result: GetTaskPayloadResult | IncompleteResult; +} + +/** + * A request from the client to deliver input responses for a task + * that is in `input_required` status. + * + * @example Task input response request + * {@includeCode ./examples/TaskInputResponseRequest/task-input-response-request.json} + * + * @category `tasks/input_response` + */ +export interface TaskInputResponseRequest extends JSONRPCRequest { + method: "tasks/input_response"; + params: TaskAugmentedRequestParams; +} + +/** + * A successful response for a {@link TaskInputResponseRequest | tasks/input_response} request. + * + * @category `tasks/input_response` + */ +export interface TaskInputResponseResultResponse extends JSONRPCResultResponse { + result: Result; } /** @@ -2104,7 +2207,7 @@ export type LoggingLevel = * * @category `sampling/createMessage` */ -export interface CreateMessageRequestParams extends TaskAugmentedRequestParams { +export interface CreateMessageRequestParams { messages: SamplingMessage[]; /** * The server's preferences for which model to select. The client MAY ignore these preferences. @@ -2173,7 +2276,7 @@ export interface ToolChoice { * * @category `sampling/createMessage` */ -export interface CreateMessageRequest extends JSONRPCRequest { +export interface CreateMessageRequest { method: "sampling/createMessage"; params: CreateMessageRequestParams; } @@ -2194,7 +2297,7 @@ export interface CreateMessageRequest extends JSONRPCRequest { * * @category `sampling/createMessage` */ -export interface CreateMessageResult extends Result, SamplingMessage { +export interface CreateMessageResult extends SamplingMessage { /** * The name of the model that generated the message. */ @@ -2214,18 +2317,6 @@ export interface CreateMessageResult extends Result, SamplingMessage { stopReason?: "endTurn" | "stopSequence" | "maxTokens" | "toolUse" | string; } -/** - * A successful response from the client for a {@link CreateMessageRequest | sampling/createMessage} request. - * - * @example Sampling result response - * {@includeCode ./examples/CreateMessageResultResponse/sampling-result-response.json} - * - * @category `sampling/createMessage` - */ -export interface CreateMessageResultResponse extends JSONRPCResultResponse { - result: CreateMessageResult; -} - /** * Describes a message issued to or received from an LLM API. * @@ -2568,7 +2659,7 @@ export interface ModelHint { * @example Prompt argument completion with context * {@includeCode ./examples/CompleteRequestParams/prompt-argument-completion-with-context.json} */ -export interface CompleteRequestParams extends RequestParams { +export interface CompleteRequestParams extends RetryAugmentedRequestParams { ref: PromptReference | ResourceTemplateReference; /** * The argument's information @@ -2687,7 +2778,7 @@ export interface PromptReference extends BaseMetadata { * * @category `roots/list` */ -export interface ListRootsRequest extends JSONRPCRequest { +export interface ListRootsRequest { method: "roots/list"; params?: RequestParams; } @@ -2705,22 +2796,10 @@ export interface ListRootsRequest extends JSONRPCRequest { * * @category `roots/list` */ -export interface ListRootsResult extends Result { +export interface ListRootsResult { roots: Root[]; } -/** - * A successful response from the client for a {@link ListRootsRequest | roots/list} request. - * - * @example List roots result response - * {@includeCode ./examples/ListRootsResultResponse/list-roots-result-response.json} - * - * @category `roots/list` - */ -export interface ListRootsResultResponse extends JSONRPCResultResponse { - result: ListRootsResult; -} - /** * Represents a root directory or file that the server can operate on. * @@ -2774,7 +2853,7 @@ export interface RootsListChangedNotification extends JSONRPCNotification { * * @category `elicitation/create` */ -export interface ElicitRequestFormParams extends TaskAugmentedRequestParams { +export interface ElicitRequestFormParams { /** * The elicitation mode. */ @@ -2807,7 +2886,7 @@ export interface ElicitRequestFormParams extends TaskAugmentedRequestParams { * * @category `elicitation/create` */ -export interface ElicitRequestURLParams extends TaskAugmentedRequestParams { +export interface ElicitRequestURLParams { /** * The elicitation mode. */ @@ -2849,7 +2928,7 @@ export type ElicitRequestParams = * * @category `elicitation/create` */ -export interface ElicitRequest extends JSONRPCRequest { +export interface ElicitRequest { method: "elicitation/create"; params: ElicitRequestParams; } @@ -3112,7 +3191,7 @@ export type EnumSchema = | LegacyTitledEnumSchema; /** - * The result returned by the client for an {@link ElicitRequest | elicitation/create} request. + * The result returned by the client for an {@link ElicitationCreateRequest | elicitation/create} request. * * @example Input single field * {@includeCode ./examples/ElicitResult/input-single-field.json} @@ -3125,7 +3204,7 @@ export type EnumSchema = * * @category `elicitation/create` */ -export interface ElicitResult extends Result { +export interface ElicitResult { /** * The user action in response to the elicitation. * - `"accept"`: User submitted the form/confirmed the action @@ -3142,18 +3221,6 @@ export interface ElicitResult extends Result { content?: { [key: string]: string | number | boolean | string[] }; } -/** - * A successful response from the client for a {@link ElicitRequest | elicitation/create} request. - * - * @example Elicitation result response - * {@includeCode ./examples/ElicitResultResponse/elicitation-result-response.json} - * - * @category `elicitation/create` - */ -export interface ElicitResultResponse extends JSONRPCResultResponse { - result: ElicitResult; -} - /** * An optional notification from the server to the client, informing it of a completion of a out-of-band elicitation request. * @@ -3191,7 +3258,8 @@ export type ClientRequest = | GetTaskRequest | GetTaskPayloadRequest | ListTasksRequest - | CancelTaskRequest; + | CancelTaskRequest + | TaskInputResponseRequest; /** @internal */ export type ClientNotification = @@ -3204,9 +3272,7 @@ export type ClientNotification = /** @internal */ export type ClientResult = | EmptyResult - | CreateMessageResult | ListRootsResult - | ElicitResult | GetTaskResult | GetTaskPayloadResult | ListTasksResult @@ -3216,9 +3282,7 @@ export type ClientResult = /** @internal */ export type ServerRequest = | PingRequest - | CreateMessageRequest | ListRootsRequest - | ElicitRequest | GetTaskRequest | GetTaskPayloadRequest | ListTasksRequest @@ -3252,4 +3316,5 @@ export type ServerResult = | GetTaskResult | GetTaskPayloadResult | ListTasksResult - | CancelTaskResult; + | CancelTaskResult + | IncompleteResult; diff --git a/seps/XXXX-MRTR.md b/seps/XXXX-MRTR.md new file mode 100644 index 000000000..7690eb2e2 --- /dev/null +++ b/seps/XXXX-MRTR.md @@ -0,0 +1,1178 @@ +# SEP-XXXX: Multi Round-Trip Requests + +- **Status**: Draft +- **Type**: Standards Track +- **Created**: 2026-02-03 +- **Author(s)**: Mark D. Roth (@markdroth), Caitie McCaffrey (@CaitieM20), + Gabriel Zimmerman (@gjz22) +- **Sponsor**: Caitie McCaffrey (@CaitieM20) +- **PR**: https://github.com/modelcontextprotocol/specification/pull/{NUMBER} + +## Abstract + +This proposal specifies a simple way to handle server-initiated requests +in the context of a client-initiated request (e.g., an elicitation +request in the context of a tool call) without requiring a shared +storage layer shared across server instances or statefulness in +load balancing, which will significantly reduce the cost of operating +MCP servers at scale in the common case. It also reduces the HTTP +transport's dependence on SSE streams, which cause problems in a lot of +environments that cannot support long-lived connections. + +## Motivation + +Note: This SEP is intended to provide a generic mechanism for handling +any server-initiated request in the context of any client-initiated +request. For clarity, throughout this document, we will specifically +discuss tool calls as a proxy for any client-initiated request, but it +should be read as applying equally to (e.g.) resource or prompt +requests; similarly, we will discuss elicitation requests as a proxy for +any server-initiated request, but it should be read as applying equally +to (e.g.) sampling requests. + +We start with the observation that there are two types of MCP tools: +1. **Ephemeral**: No state is accumulated on the server side. + - If server needs more info to process the tool call, it can start from + scratch when it gets that additional info. + - Examples: weather app, accessing email +2. **Persistent**: State is accumulated on the server side. + - Server may generate a large amount of state before requesting more + info from the client, and it may need to pick up that state to + continue processing after it receives the info from the client. + - Server may need to continue processing in the background while + waiting for more info from the client, in which case server-side + state is needed to track that ongoing processing. + - Examples: accessing an agent, spinning up a VM and needing user + interaction to manipulate the VM + +The vast majority of MCP tools will be ephemeral, and it is extremely +common for tools to be deployed in a horizontally scaled, load balanced +service, so we need to optimize for this case. + +Today, if a tool needs to send an elicitation request in order to make +progress, the workflow works like this: + +1. Client sends tool call request. For this example, let's assume that + the load balancers happen to send this request to server instance A. +2. Server A opens an SSE stream and sends the elicitation response on that + stream. +3. Client sends the elicitation response as a separate request, for which + the load balancers will choose a server instance completely + independently of the one they chose in step 1. In this example, + let's assume that the load balancers happen to send this request to + server instance B. +4. Server A must somehow discover the elicitation result delivered to + server B. +5. Server A then sends the tool call result on the SSE stream opened in + step 2. + +The difficult part here is step 4, which requires some sort of +statefulness on the server side. The main way to solve this problem +today is to have a storage layer shared across all server instances, so +that multiple server instances can match up the elicitation response +on one server instance with the original ongoing tool call on a +different server instance. + +There are two main approaches that can be used to solve this problem today: +- **Persistent Storage Layer Shared Across Server Instances**: Servers can + deploy and manage a persistent storage layer (e.g., PostgreSQL, Redis, + DynamoDB), which allow multiple server instances to match up the + elicitation response on one server instance with the original ongoing + tool call on a different server instance. This approach has a number + of drawbacks: + - The persistent storage layer is **extremely expensive**, especially for + ephemeral tools that may not already have such a layer (e.g., a weather + tool). + - The persistent storage layer imposes significant reliability concerns: + it becomes a critical dependency and therefore a potential single + point of failure. To avoid that, it must provide high availability, + replication, and backup mechanisms. + - The persistent storage layer becomes a bottleneck, limiting horizontal + scalability. Geographic distribution requires either expensive + global replication or sticky routing. + - The persistent storage layer also imposes significant operational + complexity. In horizontally scaled deployments, it requires + distributed locking or consensus protocols. It also requires special + garbage collection logic to determine when shared can be cleaned up, + which requires careful trade-offs: cleaning up state too aggressively + can reduce storage costs but limit how long users have to respond, + whereas cleaning up less aggressively accommodates slow users but + increases storage costs. + - This approach requires special behavior in the tool implementation to + integrate with the persistent storage layer. The MCP SDKs today do + not have any special hooks for this sort of storage layer integration, + which means that it's very hard to write in-line code via the SDKs. +- **Statefulness in Load Balancing**: With the use of cookies, it is + possible for the load balancing layer to ensure that the elicitation + request in step 3 is delivered to the same server instance that the + original request was delivered to in step 1. This approach, while + often cheaper than a persistent storage layer, has the following + drawbacks: + - It requires special configuration and behavior in the load + balancers, which is often difficult to manage. + - It breaks normal load balancing models, resulting in uneven load + distribution, thus increasing the cost of running the service. + - It requires special behavior in clients to propagate the cookies + used for statefulness. + - It requires the tool implementation to match up the elicitation + request with the ongoing tool call. (The MCP SDKs have some code to + handle this, but it's still a very strange pattern in the HTTP + world.) + - It is not fault tolerant. If the server instance goes down, all + state is lost, and the tool call would need to start over from + scratch. (This doesn't necessarily matter for ephemeral tools, + but it is an issue for persistent tools.) + +Also, both of these approaches rely on the use of an SSE stream, which +causes problems in environments that cannot support long-lived +connections. They also require an instance of the tool to stay in memory +in a particular server instance indefinitely. This is particularly +problematic for elicitation requests specifically, since the result may +not come from the user for an unbounded amount of time (e.g., it could +be days or months, or maybe even never). + +The goal of this SEP is to propose a simpler way to handle the pattern +of server-initiated requests within the context of a client-initiated +request. Specifically, we need to make it cheaper to support this pattern +in the common case of an ephemeral tool in a horizontally scaled, load +balanced deployment. This means that we need a solution that does not +depend on an SSE stream and does not require either a persistent storage +layer or stateful load balancing, which in turn means that we need to +avoid dependencies between requests: servers must be able to process +each individual request using no information other than what is present +in that individual request. + +Note that while the goal here is to optimize the common case of ephemeral +tools, we do want to continue to support persistent tools, which generally +already require a persistent storage layer. + +## Specification + +This SEP proposes a new mechanism for handling server requests in the +context of a client request. This new mechanism will have a slightly +different workflow for ephemeral tools and persistent tools, the latter +of which will leverage Tasks. However, both workflows will use the same +data structures. + +First, we introduce the notion of "input requests", which represents +a set of one or more server-initiated request to be sent to the client, +and "input responses", which represents the client's responses to +those requests. Both requests and responses are stored in a map with +string keys. For input requests, the map values are server-initiated +requests (e.g., elicitation or sampling requests), whereas for input +responses, the map values are the responses to those requests. Here's +how that would look in the typescript MCP schema: + +```typescript +export type InputRequest = + | CreateMessageRequest + | ElicitRequest + | ListRootsRequest; + +export interface InputRequests { [key: string]: InputRequest; } + +export type InputResponse = + | CreateMessageResult + | ElicitResult + | ListRootsResult; + +export interface InputResponses { [key: string]: InputResponse; } +``` + +The keys are assigned by the server when issuing the requests. The client +will send the response for each request using the corresponding key. +For example, a server might send the following input requests: + +```json5 +"inputRequests": { + // Elicitation request. + "github_login": { + "method": "elicitation/create", + "params": { + "mode": "form", + "message": "Please provide your GitHub username", + "requestedSchema": { + "type": "object", + "properties": { + "name": { + "type": "string" + } + }, + "required": ["name"] + } + } + }, + // Sampling request. + "capital_of_france" : { + "method": "sampling/createMessage", + "params": { + "messages": [ + { + "role": "user", + "content": { + "type": "text", + "text": "What is the capital of France?" + } + } + ], + "modelPreferences": { + "hints": [ + { + "name": "claude-3-sonnet" + } + ], + "intelligencePriority": 0.8, + "speedPriority": 0.5 + }, + "systemPrompt": "You are a helpful assistant.", + "maxTokens": 100 + } + } +} +``` + +The client would then send the responses in the following form: + +```json5 +"inputResponses": { + // Elicitation response (ElicitResult). + "github_login": { + "action": "accept", + "content": { + "name": "octocat" + } + }, + // Sampling response (CreateMessageResult). + "capital_of_france": { + "role": "assistant", + "content": { + "type": "text", + "text": "The capital of France is Paris." + }, + "model": "claude-3-sonnet-20240307", + "stopReason": "endTurn" + } +} +``` + +These types will be used in two different workflows, one for ephemeral +tools and another for persistent tools. + +### Ephemeral Tool Workflow +For the ephemeral use case, in addition to input requests, we introduce +the concept of request state. In cases where the server needs more +information, the request state is sent to the client which echoes back +the state to the server, allowing the server to remain stateless. + +We will adopt the following workflow for ephemeral tools: + +1. Client sends tool call request. +2. Server sends back a single response indicating that the request is + incomplete. The response may include input requests that the client + must complete. It may also include some request state that the client + must return back to the server. This response terminates the original + request. It will normally be sent as a single response, not on an + SSE stream, although for now (this may change in a future SEP) it is + also legal to send this response on an SSE stream following (e.g.) + progress notifications. If this incomplete response is sent on an + SSE stream, it must be the last message on the SSE stream, just as if + it were a normal response. +3. Client sends a new tool call request, completely independent of the + original one. This new tool call includes responses to the input + requests from step 2. It also includes the request state specified by + the server in step 2. +4. Server sends back a CallToolResponse. + +Note that the requests in steps 1 and 3 are completely independent: the +server that processes the request in step 3 does not need any +information that is not directly present in the request. To support this decoupling the JsonRPC Id MUST be different between the requests sent in step 1 and step 3. + +The schema would look something like this: + +```typescript +// Incomplete response. May be sent in response to any client-initiated +// request. +// At least one of the the inputRequests and requestState fields must be +// present, since the presence of these fields allow the client to +// determine that the result is incomplete. +export interface IncompleteResult extends Result { + // Requests issued by the server that must be complete before the + // client can retry the original request. + inputRequests?: InputRequests; + // Request state to be passed back to the server when the client + // retries the original request. + // Note: The client must treat this as an opaque blob; it must not + // interpret it in any way. + requestState?: string; +} + +// New request parameter type that includes fields in a retried request. +// These parameters may be included in any client-initiated request. +export interface RetryAugmentedRequestParams extends RequestParams { + // New field to carry the responses for the server's requests from the + // IncompleteResult message. For each key in the response's inputRequests + // field, the same key must appear here with the associated response. + inputResponses?: InputResponses; + // Request state passed back to the server from the client. + requestState?: string; +} +``` + +Note that both the "inputRequests" and "requestState" fields affect +only the client's next retry of the original request. They will not +be used for any other request that the client may be sending in parallel +(e.g., a tool list or even another tool call). + +Note that this workflow eliminates the need for the +`URLElicitationRequiredError` error code. That code will be removed +from the spec. + +#### Example Flow for Ephemeral Tools + +Note: This is a contrived example, just to illustrate the flow. + +1. The client sends the initial call tool request: +```json +{ + "jsonrpc": "2.0", + "id": 2, + "method": "tools/call", + "params": { + "name": "get_weather", + "arguments": { + "location": "New York" + } + } +} +``` + +2. The server responds with an incomplete response, indicating that the + client needs to respond to an elicitation request in order for the tool + call to complete, and including request state to be passed back: +```json +{ + "jsonrpc": "2.0", + "id": 2, + "result": { + "inputRequests": { + "github_login": { + "method": "elicitation/create", + "params": { + "mode": "form", + "message": "Please provide your GitHub username", + "requestedSchema": { + "type": "object", + "properties": { + "name": { + "type": "string" + } + }, + "required": ["name"] + } + } + } + }, + "requestState": "foo" + } +} +``` + +3. The client then retries the original tool call, this time including the + responses to the input server request and the request state: +```json +{ + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": { + "name": "get_weather", + "arguments": { + "location": "New York" + }, + "inputResponses": { + "github_login": { + "action": "accept", + "content": { + "name": "octocat" + } + } + }, + "requestState": "foo" + } +} +``` + +4. Finally, the server completes the tool call: +```json +{ + "jsonrpc": "2.0", + "id": 3, + "result": { + "content": [ + { + "type": "text", + "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy" + } + ], + "isError": false + } +} +``` + +#### Real-World Example for Ephemeral Workflow + +This example demonstrates how `requestState` enables a multi-round-trip +elicitation flow driven by [Azure DevOps custom +rules](https://learn.microsoft.com/en-us/azure/devops/organizations/settings/work/custom-rules?view=azure-devops). +The scenario involves an `update_work_item` tool that transitions a Bug +work item to "Resolved." ADO custom rules require specific fields when +certain state transitions occur, and the server uses iterative +elicitation to gather them — accumulating context in `requestState` +across rounds so that the final update can be executed without any +server-side storage. + +**Background — ADO Custom Rules in effect:** +- *Rule 1:* When State changes to "Resolved" → require the "Resolution" + field (e.g., Fixed, Won't Fix, Duplicate, By Design). +- *Rule 2:* When Resolution is "Duplicate" → require the "Duplicate Of" + field (a link to the original work item). + +##### Round 1 — Tool call triggers state change, server elicits Resolution + +1. The client invokes the `update_work_item` tool to resolve Bug #4522: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "tools/call", + "params": { + "name": "update_work_item", + "arguments": { + "workItemId": 4522, + "fields": { "System.State": "Resolved" } + } + } +} +``` + +2. The server recognizes that setting State to "Resolved" triggers + Rule 1, which requires a Resolution value. Rather than failing the + call, the server returns an incomplete response with an elicitation + request. No `requestState` is needed yet, since the original tool + call arguments will be re-sent on retry: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "inputRequests": { + "resolution": { + "method": "elicitation/create", + "params": { + "message": "Resolving Bug #4522 requires a resolution. How was this bug resolved?", + "requestedSchema": { + "type": "object", + "properties": { + "resolution": { + "type": "string", + "enum": ["Fixed", "Won't Fix", "Duplicate", "By Design"], + "description": "Resolution type for this bug" + } + }, + "required": ["resolution"] + } + } + } + } + } +} +``` + +3. The user selects "Duplicate". The client retries the original tool + call with the elicitation response: + +```json +{ + "jsonrpc": "2.0", + "id": 2, + "method": "tools/call", + "params": { + "name": "update_work_item", + "arguments": { + "workItemId": 4522, + "fields": { "System.State": "Resolved" } + }, + "inputResponses": { + "resolution": { + "action": "accept", + "content": { "resolution": "Duplicate" } + } + } + } +} +``` + +##### Round 2 — Resolution triggers another rule, server elicits Duplicate Of + +4. The server merges the user's response and sees that Resolution = + "Duplicate" triggers Rule 2, requiring a "Duplicate Of" link. It + returns another incomplete response, this time encoding the + already-gathered resolution in `requestState` so it is available + regardless of which server instance handles the next retry: + +```json +{ + "jsonrpc": "2.0", + "id": 2, + "result": { + "inputRequests": { + "duplicate_of": { + "method": "elicitation/create", + "params": { + "message": "Since this is a duplicate, which work item is the original?", + "requestedSchema": { + "type": "object", + "properties": { + "duplicateOfId": { + "type": "number", + "description": "Work item ID of the original bug" + } + }, + "required": ["duplicateOfId"] + } + } + } + }, + "requestState": "eyJyZXNvbHV0aW9uIjoiRHVwbGljYXRlIn0..." + } +} +``` + +5. The user provides the original work item ID. The client retries the + tool call, echoing back the `requestState` and including the new + elicitation response: + +```json +{ + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": { + "name": "update_work_item", + "arguments": { + "workItemId": 4522, + "fields": { "System.State": "Resolved" } + }, + "inputResponses": { + "duplicate_of": { + "action": "accept", + "content": { "duplicateOfId": 4301 } + } + }, + "requestState": "eyJyZXNvbHV0aW9uIjoiRHVwbGljYXRlIn0..." + } +} +``` + +##### Final — Server completes the update + +6. The server decodes the `requestState` (which contains the + resolution), reads the `inputResponses` (which contains the + duplicate ID), and now has all required fields. It completes the + tool call: + +```json +{ + "jsonrpc": "2.0", + "id": 3, + "result": { + "content": [ + { + "type": "text", + "text": "Bug #4522 resolved as Duplicate of Bug #4301. State set to Resolved and duplicate link created." + } + ], + "isError": false + } +} +``` + +**Key takeaway:** Across both elicitation rounds, the server held no +in-memory or persisted state. The `requestState` field carried the +accumulated context through the client, and any server instance could +have handled any individual round. + +#### Use Cases for Request State + +The "requestState" mechanism provides a mechanism for doing multiple +round trips on the same logical request. There are two main use-cases +for this. + +##### Use Case 1: Rolling Upgrades + +Let's say that you are doing a rolling upgrade of your horizontally +scaled server instances to deploy a new version of a tool implementation. +The old version had two input requests with keys "github_login" and +"google_login". However, in the new version of the tool implementation, +it still uses the "github_login" input request, but it replaces the +"google_login" input request with a new "microsoft_login" input request. + +If the first request goes to an old version of the server but the second +attempt (that includes the input responses) goes to a new version +of the server, then the server will see the result for "github_login", +which it needs, but it won't see the result for "microsoft_login". +(It will also see the result for "google_login", but it no longer needs +that, so it doesn't matter.) At this point, the server needs to send a +new input request for "microsoft_login", but it also doesn't want +to lose the answer that it's already gotten for "github_login", so it +would use the kind of state proposed in 1685 to retain that information +without having to store the state on the server side. + +The workflow here would look like this: + +1. Client sends tool call request that hits a server instance running + the old version. +2. Server sends back an incomplete response indicating the input + requests for "github_login" and "google_login". +3. Client sends a new tool call request that includes the responses to + the input requests for "github_login" and "google_login". This + time it hits a server instance running the new version. +4. Server sends back another incomplete response indicating the + input request for "microsoft_login", which the client has not + already provided. However, the response also includes request state + containing the already-provided "github_login" response, so that the + client does not need to prompt the user for the same information a + second time. +5. Client sends a third tool call request that includes the response to + the "microsoft_login" input request as well as echoing back the + request state provided by the server in step 4. +6. Server now sees the "github_login" info in the request state and the + "microsoft_login" state in the input responses, so the request + now contains everything the server needs to perform the tool call and + send back a complete response. + +##### Use Case 2: Load Shedding + +Let's say that you have an MCP server instance that is processing a bunch +of tool calls and notices that it's too heavily loaded, so it wants to +move one of the ongoing tool calls to a different server instance. +However, it has already done a significant amount of processing on that +tool call, so it does not want to simply fail the call and have the +client start over from scratch on another server instance; instead, it +wants to preserve the state it has already accumulated, so that +whichever server instance resumes processing can pick up from where the +original server instance left off. This can be accomplished by sending +an incomplete request that contains request state but does not contain +any input requests. + +The workflow here would look like this: + +1. Client sends the original request, which the load balancers route + to server instance A. +2. Server instance A does a bunch of computation before deciding that it + needs to shed load. It sends an incomplete response with its + accumulated state in the `requestState` field but without the + `inputRequests` field. +3. Client retries the request with the `requestState` field attached. + The load balancers route this request to server instance B. +4. Server instance B starts from the state it sees in the `requestState` + field, thus picking up the computation from where server instance A + left off, and eventually returning a complete response. + +#### Protocol Requirements for Ephemeral Workflow + +1. **Server Behavior:** + - Servers MAY respond to any client-initiated request with a + `IncompleteResult`. This message MAY be sent either + as a standalone response or as the final message on an SSE stream, + although implementations are encouraged to prefer the former. + If using an SSE stream, servers MUST NOT send any message on the + stream after the incomplete response message. + - The `Incomplete` message MAY include an + `inputRequests` field. + - The `Incomplete` message MAY include a + `requestState` field. If specified, this field is an opaque + string that is meaningful only to the server. Servers are free to + encode the state in any format (e.g., plain JSON, base64-encoded + JSON, encrypted JWT, serialized binary, etc.). + - If a request contains a `requestState` field, servers MUST always + validate that state, as the client is an untrusted intermediary. + If tampering is a concern, servers SHOULD encrypt the `requestState` + field using an encryption algorithm of their choice (e.g., they can + use AES-GCM or a signed JWT) to ensure both confidentiality and + integrity. Note that there is also a risk of replaying/hijacking + attacks, where an authenticated attacker resends state that was + originally sent to a different user. Therefore, if the request + state contains any data that is specific to the original user, the + server MUST use some mechanism to cryptographically bind the data + to the original user and MUST verify that the `requestState` data + sent by the client is associated with the currently authenticated + user. Servers using plaintext state MUST treat the decoded + values as untrusted input and validate them the same way they would + validate any client-supplied data. + +2. **Client Behavior:** + - If a client receives a `IncompleteResult` message, + if the message contains the `inputRequests` field, then the client + MUST construct the requested input before retrying the original + request. In contrast, if the message does *not* contain the + `inputRequests` field, then the client MAY retry the original + request immediately. + - If a client receives a `IncompleteResult` message + that contains the `requestState` field, it MUST echo back the + exact value of that field when retrying the original request. + Clients MUST NOT inspect, parse, modify, or make any assumptions + about the `requestState` contents. If the incomplete response does + not contain a `requestState` field, the client MUST NOT include one + in the retry. + +### Persistent Tool Workflow + +The persistent tool workflow will leverage Tasks. [`Tasks`](https://modelcontextprotocol.io/specification/draft/basic/utilities/tasks) already provide a mechanism to indicate that more information is needed to complete the request. The `input_required` Task Status allows the server to indicate that additional information is needed to complete processing the task. + +The workflow for `Tasks` is as follows: + +1. Server sets Task Status to `input_required`. The server can pause + processing the request at this point. +2. Client retrieves the Task Status by calling `tasks/get` and sees that more information is needed. +3. Client calls `tasks/result` +4. Server returns the `InputRequests` object. +5. Client calls `tasks/input_response` request that includes an `InputResponses` object along with `Task` metadata field. +6. Server resumes processing sets TaskStatus back to `Working`. + +Since `Tasks` are likely longer running, have state associated with them, and are likely more costly to compute, the request for more information does not end the originally requested operation (e.g., the tool call). Instead, the server can resume processing once the necessary information is provided. + +To align with MRTR semantics, the server will respond to the `tasks/result` request with a `InputRequests` object. Both of these will have the same JsonRPC `id`. When the client responds with a `InputResponses` object this is a new client request wit a new JSONRPC `id` and therefore needs a new method name. We propose `tasks/input_response`. + +The above workflow and below example do not leverage any of the optional Task Status Notifications although this SEP does not preclude their use. + +#### Example Flow for Persistent Tools +The below example walks through the entire Task Message flow for a Echo Tool which can request additional information from the client via Elicitation. + +1. Client Request to invoke EchoTool. +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "tools/call", + "params":{ + "name": "echo", + "task":{ + "ttl": 60000 + } + } +} +``` + +2. Server Response with a `Task` +```json +{ + "id": 1, + "jsonrpc": "2.0", + "result":{ + "task":{ + "taskId": "echo_dc792e24-01b5-4c0a-abcb-0559848ca3c5", + "status": "working", + "statusMessage": "Task has been created for echo tool invocation.", + "createdAt": "2026-01-27T03:32:48.3148180Z", + "lastUpdatedAt": "2026-01-27T03:32:48.3148180Z", + "ttl": 60000, + "pollInterval": 100 + } + } +} +``` + +3. Client Request periodically checks the status of the `Task` using `tasks/get`. +```json +{ + "jsonrpc": "2.0", + "id": 2, + "method": "tasks/get", + "params":{ + "taskId": "echo_dc792e24-01b5-4c0a-abcb-0559848ca3c5" + } +} +``` + +4. Server Response with Task status `input_required` +```json +{ + "id": 2, + "jsonrpc": "2.0", + "result":{ + "taskId": "echo_dc792e24-01b5-4c0a-abcb-0559848ca3c5", + "status": "input_required", + "statusMessage": "Input Required to Proceed call tasks/result", + "createdAt": "2026-01-27T03:38:07.7534643Z", + "lastUpdatedAt": "2026-01-27T03:38:07.7534643Z", + "ttl": 60000, + "pollInterval": 100 + } +} +``` + +5. Client Request sends message `tasks/result` to discover what input is required to proceed. +```json +{ + "jsonrpc": "2.0", + "id": 3, + "method": "tasks/result", + "params":{ + "taskId": "echo_dc792e24-01b5-4c0a-abcb-0559848ca3c5" + } +} +``` + +6. Server Response returns `inputRequests` to request additional input +```json +{ + "id": 3, + "jsonrpc": "2.0", + "result": { + "inputRequests":{ + "echo_input":{ + "method": "elicitation/create", + "params":{ + "mode": "form", + "message": "Please provide the input string to echo back", + "requestedSchema":{ + "type": "object", + "properties":{ + "input": { "type": "string"} + }, + "required": ["input"] + } + } + } + }, + "_meta":{ + "io.modelcontextprotocol/related-task":{ + "taskId": "echo_dc792e24-01b5-4c0a-abcb-0559848ca3c5" + } + } + } +} +``` + +7. Client Request presents the Elicitation to the user and collects the input, then sends message to the server. +```json +{ + "jsonrpc": "2.0", + "id": 4, + "method": "tasks/input_response", + "params": { + "inputResponses":{ + "echo_input":{ + "action": "accept", + "content":{ + "input": "Hello World!" + } + } + }, + "_meta":{ + "io.modelcontextprotocol/related-task":{ + "taskId": "echo_dc792e24-01b5-4c0a-abcb-0559848ca3c5" + } + } + } +} +``` + +8. Server Response Server should acknowledge the receipt of the 'tasks/input_response' message by sending a 'JSONRPCResponse'. If the message was successfully received a `JSONRPCResultResponse` is sent including the `taskId`. If an error occurs, a `JSONRPCErrorResponse` is sent. The server can now proceed to complete the `Task` using the provided input, and the `Task` status changes to `Working`. +```json +{ + "id": 4, + "jsonrpc": "2.0", + "result": { + "_meta":{ + "io.modelcontextprotocol/related-task":{ + "taskId": "echo_dc792e24-01b5-4c0a-abcb-0559848ca3c5" + } + } + } +} +``` + +9. Client Request continues to poll the input status using `tasks/get` until server responds with Task Status of `Completed` +Client Request +```json +{ + "jsonrpc": "2.0", + "id": 5, + "method": "tasks/get", + "params": { + "taskId": "echo_dc792e24-01b5-4c0a-abcb-0559848ca3c5" + } +} +``` +10. Server Response with Task status `completed` +```json +{ + "id": 5, + "jsonrpc": "2.0", + "result":{ + "taskId": "echo_dc792e24-01b5-4c0a-abcb-0559848ca3c5", + "status": "completed", + "statusMessage": "Task has been completed successfully, call tasks/result", + "createdAt": "2026-01-27T03:38:07.7534643Z", + "lastUpdatedAt": "2026-01-27T03:38:08.1234567Z", + "ttl": 60000, + "pollInterval": 100 + } +} +``` + +11. Client Request calls `tasks/result` to get the final result of the `Task` from the server. +Client Message +```json +{ + "id": 6, + "jsonrpc": "2.0", + "method": "tasks/result", + "params":{ + "taskId": "echo_dc792e24-01b5-4c0a-abcb-0559848ca3c5" + } +} +``` +12. Server Response with the final result of the `Task` +```json +{ + "id": 6, + "jsonrpc": "2.0", + "result":{ + "isError": false, + "content":[{ + "type": "text", + "text": "Echo: Hello World!" + }], + "_meta":{ + "io.modelcontextprotocol/related-task":{ + "taskId": "echo_dc792e24-01b5-4c0a-abcb-0559848ca3c5" + } + } + } +} +``` + +#### Protocol Requirements for Persistent Workflow + +1. **Server Behavior:** + - Servers MAY respond to `tasks/get` by indicating that the task + is in state `input_required`. + - Servers MAY include an `inputRequests` field in the + `tasks/result` response. + +2. **Client Behavior:** + - When `tasks/get` shows state `input_required`, clients MUST call + `tasks/result` to get the input requests, construct the results of + those requests, and then call `tasks/input_response` with the input + responses, unless the client is going to cancel the task. + +### Interactions Between Ephemeral and Persistent Workflows + +If a tool implementation needs the client to respond to a set of +input requests before it can even start processing but then later +needs to do persistent processing, it can start using the ephemeral +workflow and then switch to the persistent workflow by creating a task +at that point. This avoids the need for the server to store state until +it actually has the information needed to start processing the request. +This workflow would look like this: + +1. Client sends tool call request with task metadata. +2. Server sends back `inputRequests` response indicating that more information is needed to process the request. This terminates the original request. +3. Client sends a new tool call request, completely independent of the + original one, which includes the `inputResponses` object along with the task metadata. +4. Server sends back a task ID, indicating that it will be processing the + request in the background. All subsequent interaction will be done + via the Tasks API. + +Note that the opposite is not true: Once a tool implementation returns a +task, it has committed to storing state on the server side for the +duration of the task, and there is no way to transition back to the +ephemeral model. All subsequent interactions must be performed via the +Tasks API. + +### Guidance for Error Handling +This section provides implementation guidance for error handling in scenarios where the client provides unexpected or malformed data in the `inputResponses` object. + +As with any received request, the server SHOULD validate the data provided by the client is a valid `inputResponses` object and that the information inside can be correctly parsed. Protocol errors, like malformed JSON, invalid schema, or internal server errors which prevent the processing of the request should return a `JSONRPCErrorResponse` with an appropriate error code and message. + +If additional parameters are provided in the `inputResponses` object The server SHOULD treat these as optional parameters. Therefore it SHOULD ignore any unexpected information in the `inputResponses` object that it does not recognize or need. + +The client may also fail to send all the information requested in previous `inputRequests`. If the missing information requested is necessary for the server to process the request, then it SHOULD respond with a new `IncompleteResult`. + +We discussed having a specific application level error code returned, however the client may not have enough information to recover in all scenarios. Therefore, we decided to rely on the existing mechanics of requesting more input via `IncompleteResult` to ensure a client can always recover by having the server request the necessary information again. + +Malicious clients could intentionally send incorrect information in the `inputResponses` object, and generate load on the server by causing it to repeatedly request the same information. However, this is not a new concern introduced by this workflow, since malicious clients could already generate load by sending malformed requests. Server implementors can use standard techniques like rate limiting and throttling to protect themselves from such attacks. + +In the ephemeral workflow, this would look like the following: +1. The client retries the original tool call, this time including the `inputResponses` object, but the response is missing required information that the server needs to process the request. +```json +{ + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": { + "name": "get_weather", + "arguments": { + "location": "New York" + }, + "inputResponses": { + "not_requested_info": { + "action": "accept", + "content": { + "not_requested_param_name": "Information the server did not request" + } + } + } + } +} +``` + +2. The server responds with an incomplete response, indicating that the client needs to respond to an elicitation request in order for the tool call to complete, and including request state to be passed back: +```json +{ + "jsonrpc": "2.0", + "id": 2, + "result": { + "inputRequests": { + "github_login": { + "method": "elicitation/create", + "params": { + "mode": "form", + "message": "Please provide your GitHub username", + "requestedSchema": { + "type": "object", + "properties": { + "name": { + "type": "string" + } + }, + "required": ["name"] + } + } + } + } + } +} +``` + +2. The Server responds wit an incomplete response, indicating that the client needs to provide missing information for the request to succeed. + + +In the persistent workflow, this would look like the following: +Step 7 from above: Client Request The client mistakenly or maliciously sends unexpected, but well-formed data to the server in response to the input request. +```json +{ + "jsonrpc": "2.0", + "id": 4, + "method": "tasks/input_response", + "params": { + "inputResponses":{ + "echo_input":{ + "action": "accept", + "content":{ + "not_requested_parameter": "Information the server did not request." + } + } + }, + "_meta":{ + "io.modelcontextprotocol/related-task":{ + "taskId": "echo_dc792e24-01b5-4c0a-abcb-0559848ca3c5" + } + } + } +} +``` + +Step 8 from above. Server Response Server acknowledges the receipt of the response by sending a `JSONRPCResultResponse`. However, since the response is missing required information, the server does not proceed with processing the taks and leaves the Task status as `input_required`. The next time the client calls `tasks/result`, the server responds with a new `inputRequest` requesting the necessary information again. +```json +{ + "id": 4, + "jsonrpc": "2.0", + "result": { + "_meta":{ + "io.modelcontextprotocol/related-task":{ + "taskId": "echo_dc792e24-01b5-4c0a-abcb-0559848ca3c5" + } + } + } +} +``` + +## Rationale + +We considered a bidirectional stream approach to replace SSE streams. +However, that approach would have made the wire protocol more +complicated (e.g., it would have required HTTP/2 or HTTP/3). Also, it +would not have eliminated problems for environments that cannot support +long-lived connections, nor would it have addressed fault tolerance +issues. + +There was discussion about whether the input requests should be a +map or just a single object, possibly leveraging some field inside of +the requests (e.g., the elicitation ID) to differentiate between them. +We decided that the map makes sense, since it structurally guarantees +the uniqueness of keys, which will avoid the need for explicit checks in +SDKs and applications to avoid conflicts. + +In the persistent workflow, we considered including the input requests +directly in the `tasks/get` response, rather than requiring the client +to see the `input_required` status and then call `tasks/result` to get +the input requests. We decided to keep those two things separate in +deference to implementations that use separate infrastructure for task +state and for the actual tool implementation; the idea is that the +`tasks/get` call should have a consistent latency profile, regardless of +what the task state actually is. We recognize that this requires an +extra round-trip to the server, but we can optimize this in the future +if becomes a problem. + +## Backward Compatibility + +Today there may be ephemeral tools written in an in-line but async +fashion to wait for the elicitation response before sending the tool +call response on the original SSE stream: + +```python +def my_tool(): + do_mutation1() + await elicit_more_info() + do_mutation2() +``` + +For new tools, we want to instead suggest that they be written like +this: + +```python +def my_tool(request): + github_login = request.inputResponses().get('github_login', None) + if github_login is None: + return IncompleteResponse({'github_login': elicitation_request}) + result = GetResult(github_login) + return Result(result) +``` + +However, we need to consider how to avoid breaking things for existing +tools that are written the old way. Ideally, we will be able to modify +the SDKs to support the old tool implementations via some sort of +backward compatibility layer. + +## Security Implications + +Because `requestState` passes through the client, malicious or +compromised clients could attempt to modify it to alter server behavior, +bypass authorization checks, or corrupt server logic. To mitigate this, +we require servers to validate this state as described in the protocol +requirements above. + +## Reference Implementation + +TBD + +### Acknowledgments + +Thanks to Luca Chang (@LucaButBoring) for his valuable input on how to +integrate input requests into Tasks.