Elicitation

• Form mode: Servers can request structured data from users with optional JSON schemas to validate responses
• URL mode: Servers can direct users to external URLs for sensitive interactions that must not pass through the MCP client

​

User Interaction Model

​

Capabilities

{
  "capabilities": {
    "elicitation": {
      "form": {},
      "url": {}
    }
  }
}

{
  "capabilities": {
    "elicitation": {}, // Equivalent to { "form": {} }
  },
}

​

Protocol Messages

​

Elicitation Requests

• "form": In-band structured data collection with optional schema validation. Data is exposed to the client.
• "url": Out-of-band interaction via URL navigation. Data (other than the URL itself) is not exposed to the client.

​

Form Mode Elicitation Requests

​

Requested Schema

1. String Schema
   Copy

   {
     "type": "string",
     "title": "Display Name",
     "description": "Description text",
     "minLength": 3,
     "maxLength": 50,
     "pattern": "^[A-Za-z]+$",
     "format": "email",
     "default": "user@example.com"
   }
   

   Supported formats: email, uri, date, date-time
2. Number Schema
   Copy

   {
     "type": "number", // or "integer"
     "title": "Display Name",
     "description": "Description text",
     "minimum": 0,
     "maximum": 100,
     "default": 50
   }
   

3. Boolean Schema
   Copy

   {
     "type": "boolean",
     "title": "Display Name",
     "description": "Description text",
     "default": false
   }
   

4. Enum Schema Single-select enum (without titles):
   Copy

   {
     "type": "string",
     "title": "Color Selection",
     "description": "Choose your favorite color",
     "enum": ["Red", "Green", "Blue"],
     "default": "Red"
   }
   

   Single-select enum (with titles):
   Copy

   {
     "type": "string",
     "title": "Color Selection",
     "description": "Choose your favorite color",
     "oneOf": [
       { "const": "#FF0000", "title": "Red" },
       { "const": "#00FF00", "title": "Green" },
       { "const": "#0000FF", "title": "Blue" }
     ],
     "default": "#FF0000"
   }
   

   Multi-select enum (without titles):
   Copy

   {
     "type": "array",
     "title": "Color Selection",
     "description": "Choose your favorite colors",
     "minItems": 1,
     "maxItems": 2,
     "items": {
       "type": "string",
       "enum": ["Red", "Green", "Blue"]
     },
     "default": ["Red", "Green"]
   }
   

   Multi-select enum (with titles):
   Copy

   {
     "type": "array",
     "title": "Color Selection",
     "description": "Choose your favorite colors",
     "minItems": 1,
     "maxItems": 2,
     "items": {
       "anyOf": [
         { "const": "#FF0000", "title": "Red" },
         { "const": "#00FF00", "title": "Green" },
         { "const": "#0000FF", "title": "Blue" }
       ]
     },
     "default": ["#FF0000", "#00FF00"]
   }
   

1. Generate appropriate input forms
2. Validate user input before sending
3. Provide better guidance to users

​

Example: Simple Text Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "elicitation/create",
  "params": {
    "mode": "form",
    "message": "Please provide your GitHub username",
    "requestedSchema": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      },
      "required": ["name"]
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "action": "accept",
    "content": {
      "name": "octocat"
    }
  }
}

​

Example: Structured Data Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "elicitation/create",
  "params": {
    "mode": "form",
    "message": "Please provide your contact information",
    "requestedSchema": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Your full name"
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Your email address"
        },
        "age": {
          "type": "number",
          "minimum": 18,
          "description": "Your age"
        }
      },
      "required": ["name", "email"]
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "action": "accept",
    "content": {
      "name": "Monalisa Octocat",
      "email": "octocat@github.com",
      "age": 30
    }
  }
}

​

URL Mode Elicitation Requests

​

Example: Request Sensitive Data

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "elicitation/create",
  "params": {
    "mode": "url",
    "elicitationId": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://mcp.example.com/ui/set_api_key",
    "message": "Please provide your API key to continue."
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "action": "accept"
  }
}

​

Completion Notifications for URL Mode Elicitation

• MUST only send the notification to the client that initiated the elicitation request.
• MUST include the elicitationId established in the original elicitation/create request.

• MUST ignore notifications referencing unknown or already-completed IDs.
• MAY wait for this notification to automatically retry requests that received a URLElicitationRequiredError, update the user interface, or otherwise continue an interaction.
• SHOULD still provide manual controls that let the user retry or cancel the original request (or otherwise resume interacting with the client) if the notification never arrives.

​

Example

{
  "jsonrpc": "2.0",
  "method": "notifications/elicitation/complete",
  "params": {
    "elicitationId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

​

URL Elicitation Required Error

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32042, // URL_ELICITATION_REQUIRED
    "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."
        }
      ]
    }
  }
}

​

Message Flow

​

Form Mode Flow

​

URL Mode Flow

​

URL Mode With Elicitation Required Error Flow

​

Response Actions

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "action": "accept", // or "decline" or "cancel"
    "content": {
      "propertyName": "value",
      "anotherProperty": 42
    }
  }
}

1. Accept (action: "accept"): User explicitly approved and submitted with data
   • For form mode: The content field contains the submitted data matching the requested schema
   • For URL mode: The content field is omitted
   • Example: User clicked “Submit”, “OK”, “Confirm”, etc.
2. Decline (action: "decline"): User explicitly declined the request
   • The content field is typically omitted
   • Example: User clicked “Reject”, “Decline”, “No”, etc.
3. Cancel (action: "cancel"): User dismissed without making an explicit choice
   • The content field is typically omitted
   • Example: User closed the dialog, clicked outside, pressed Escape, browser failed to load, etc.

• Accept: Process the submitted data
• Decline: Handle explicit decline (e.g., offer alternatives)
• Cancel: Handle dismissal (e.g., prompt again later)

​

Implementation Considerations

​

Statefulness

• Whether required information has been collected (e.g., the user’s display name via form mode elicitation)
• Status of resource access (e.g., API keys or a payment flow via URL mode elicitation)

• State MUST NOT be associated with session IDs alone
• State storage MUST be protected against unauthorized access
• For remote MCP servers, user identification MUST be derived from credentials acquired via MCP authorization when possible (e.g. sub claim)

​

URL Mode Elicitation for Sensitive Data

1. The server directs users to a secure web page (served over HTTPS)
2. The page presents a branded form UI on a domain the user trusts
3. Users enter sensitive credentials directly into the secure form
4. The server stores credentials securely, bound to the user’s identity
5. Subsequent MCP requests use these stored credentials for API access

​

URL Mode Elicitation for OAuth Flows

​

Understanding the Distinction

• MCP Authorization: Required OAuth flow between the MCP client and MCP server (covered in the authorization specification)
• External (third-party) Authorization: Optional authorization between the MCP server and a third-party resource server, initiated via URL mode elicitation

• An OAuth resource server (to the MCP client)
• An OAuth client (to the third-party resource server)

• An MCP client connects to an MCP server
• The MCP server integrates with various different third-party services
• When the MCP client calls a tool that requires access to a third-party service, the MCP server needs credentials for that service

1. The third-party credentials MUST NOT transit through the MCP client: The client must never see third-party credentials to protect the security boundary
2. The MCP server MUST NOT use the client’s credentials for the third-party service: That would be token passthrough, which is forbidden
3. The user MUST authorize the MCP server directly: The interaction happens outside the MCP protocol, without involving the MCP client
4. The MCP server is responsible for tokens: The MCP server is responsible for storing and managing the third-party tokens obtained through the URL mode elicitation (in other words, the MCP server must be stateful).

​

Implementation Pattern

1. The MCP server generates an authorization URL, acting as an OAuth client to the third-party service
2. The MCP server stores internal state that associates (binds) the elicitation request with the user’s identity.
3. The MCP server sends a URL mode elicitation request to the client with a URL that can start the authorization flow.
4. The user completes the OAuth flow directly with the third-party authorization server
5. The third-party authorization server redirects back to the MCP server
6. The MCP server securely stores the third-party tokens, bound to the user’s identity
7. Future MCP requests can leverage these stored tokens for API access to the third-party resource server

​

Error Handling

• When a request cannot be processed until an elicitation is completed: -32042 (URLElicitationRequiredError)

• Server sends an elicitation/create request with a mode not declared in client capabilities: -32602 (Invalid params)

​

Security Considerations

1. Servers MUST bind elicitation requests to the client and user identity
2. Clients MUST provide clear indication of which server is requesting information
3. Clients SHOULD implement user approval controls
4. Clients SHOULD allow users to decline elicitation requests at any time
5. Clients SHOULD implement rate limiting
6. Clients SHOULD present elicitation requests in a way that makes it clear what information is being requested and why

​

Safe URL Handling

1. MUST NOT include sensitive information about the end-user, including credentials, personal identifiable information, etc., in the URL sent to the client in a URL elicitation request.
2. MUST NOT provide a URL which is pre-authenticated to access a protected resource, as the URL could be used to impersonate the user by a malicious client.
3. SHOULD NOT include URLs intended to be clickable in any field of a form mode elicitation request.
4. SHOULD use HTTPS URLs for non-development environments.

1. MUST NOT automatically pre-fetch the URL or any of its metadata.
2. MUST NOT open the URL without explicit consent from the user.
3. MUST show the full URL to the user for examination before consent.
4. MUST open the URL provided by the server in a secure manner that does not enable the client or LLM to inspect the content or user inputs. For example, on iOS, SFSafariViewController is good, but WkWebView is not.
5. SHOULD highlight the domain of the URL to mitigate subdomain spoofing.
6. SHOULD have warnings for ambiguous/suspicious URIs (i.e., containing Punycode).
7. SHOULD NOT render URLs as clickable in any field of an elicitation request, except for the url field in a URL elicitation request (with the restrictions detailed above).

​

Identifying the User

• Incorrect: Treat user input like “I am joe@example.com” as authoritative
• Correct: Rely on authorization to identify the user

​

Form Mode Security

1. Servers MUST NOT request sensitive information (passwords, API keys, etc.) via form mode
2. Clients SHOULD validate all responses against the provided schema
3. Servers SHOULD validate received data matches the requested schema

​

Phishing

1. A malicious user (Alice) connected to a benign server triggers an elicitation request
2. The benign server generates an authorization URL, acting as an OAuth client of a third-party authorization server
3. Alice’s client displays the URL and asks for consent
4. Instead of clicking on the link, Alice tricks a victim user (Bob) of the same benign server into clicking it
5. Bob opens the link and completes the authorization, thinking they are authorizing their own connection to the benign server
6. The benign server receives a callback/redirect form the third-party authorization server, and assumes it’s Alice’s request
7. The tokens for the third-party server are bound to Alice’s session and identity, instead of Bob’s, resulting in an account takeover