Multi Round-Trip Requests

Documentation Index

Fetch the complete documentation index at: https://modelcontextprotocol.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Multi Round-Trip Requests

1. Client sends an initial request to the server with the parameters needed to perform the operation.
2. Server determines that additional information is required to fulfill the request and responds requesting more information.
3. Client gathers the requested information from the user or other sources, then retries the original request including the additional requested information.
4. Server determines it has sufficient information to complete the operation, and responds with the final result.

​

Core Types

​

InputRequests

{
  "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?"
          }
        }
      ],
      "systemPrompt": "You are a helpful assistant.",
      "maxTokens": 100
    }
  }
}

​

InputResponses

{
  "github_login": {
    "action": "accept",
    "content": {
      "name": "octocat"
    }
  },
  "capital_of_france": {
    "role": "assistant",
    "content": {
      "type": "text",
      "text": "The capital of France is Paris."
    },
    "model": "claude-3-sonnet-20240307",
    "stopReason": "endTurn"
  }
}

​

InputRequiredResult

• inputRequests (optional): An InputRequests map of server-initiated requests that the client must fulfill.
• requestState (optional): An opaque string meaningful only to the server. Clients MUST NOT inspect, parse, modify, or make any assumptions about its contents.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "input_required",
    "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
        }
      }
    },
    "requestState": "AEAD-protected blob"
  }
}

​

Supported Requests

​

Basic Workflow

​

Server Requirements (Basic Workflow)

1. Servers MAY respond to any supported client request with an InputRequiredResult.
2. The InputRequiredResult MAY include an inputRequests field.
   • inputRequests keys are server assigned identifiers and MUST be unique within the scope of the request.
   • inputRequests values are request objects that MUST be one of ElicitRequest, CreateMessageRequest, or ListRootsRequest
3. The InputRequiredResult MAY include a requestState field. If specified, this field is an opaque string meaningful only to the server. Servers are free to encode the state in any format (e.g. base64-encoded JSON, encrypted JWT, serialized binary).
4. If a client request contains a requestState field, servers MUST treat requestState as an attacker-controlld input. If requestState influences authorization, resource acces, or business logic, servers MUST protect its integrigty (e.g. HMAC or AEAD) and MUST reject state that fails verification. Integrity protection MAY be omitted only wen tampering can cause nothing worse than request failure.
5. To prevent replay, servers SHOULD include the following inside the integrity-protected requestState payload and verify each on recepit:
   • the authenticated principal, rejecting state presented by a different principal.
   • a short expiry (TTL), rejecting state presented after it lapses;
   • an identifier for the originating request, e.g. the method name and a digest of its salient parameters,rejecting state presented on a request that does not match.
     Note that these measures bound the replay window and prevent cross-user and corss-request reuse, but do not by themselves guarantee single-use. Servers for which a given requestState must be consumed at most once (e.g., one-time redemtpions) MUST enforce that invariant server-side.
6. Servers MUST include at least one of inputRequests or requestState in every InputRequiredResult response.
7. Servers MUST NOT send an inputRequests that the client has not declared support for in its capabilities. For example, if a client does not declare support for elicitation, the server MUST NOT include any elicitation/create requests in the inputRequests field.
8. Servers MUST NOT assume that clients will fulfill the inputRequests or retry the original request. Servers MAY choose to return an InputRequiredResult on multiple attempts at the same request if they want to repeatedly prompt the user for information until they have what they need to complete the request.

​

Client Requirements (Basic Workflow)

1. If a client receives an InputRequiredResult that contains the inputRequests field, the client MUST construct the requested inputs before retrying the original request. If the InputRequiredResult does not contain the inputRequests field, the client MAY retry the original request immediately.
2. If an InputRequiredResult contains the requestState field, the client 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 InputRequiredResult does not contain a requestState field, the client MUST NOT include one in the retry.
3. The JSON-RPC id MUST be different between the initial request and the retry, as they are independent requests.
4. Both the inputRequests and requestState fields affect only the client’s retry of the original request. They MUST NOT be used for any other request that the client may be sending in parallel.

​

Tasks Workflow

​

Server Requirements (Tasks)

1. Servers MAY respond to tasks/get by indicating that the task is in status input_required.
2. Servers MUST include an inputRequests field in the tasks/result response when the task is in status input_required.
3. inputRequests keys are server assigned identifiers and MUST be unique within the scope of a Task.
4. Servers MAY include a requestState field in the tasks/result response when the task is in status input_required.

​

Client Requirements (Tasks)

1. When tasks/get shows status input_required, clients MUST call tasks/result to get the inputRequests and optional requestState.
2. Clients SHOULD construct the results of those requests and call tasks/input_response with the inputResponses & requestState (if present).
3. Clients MAY choose not to fulfill the input requests, in which case they MAY cancel the task.

​

Error Handling

​

Security Considerations