[DOCS] MCP elicitation documentation missing print and Agent SDK handling

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/mcp

Section/Topic

Respond to MCP elicitation requests, plus the corresponding print (claude -p) and Agent SDK guidance for handling elicitation outside the interactive TUI.

Current Documentation

The MCP page currently says:

MCP servers can request structured input from you mid-task using elicitation. When a server needs information it can't get on its own, Claude Code displays an interactive dialog and passes your response back to the server. No configuration is required on your side: elicitation dialogs appear automatically when a server requests them.

The headless page currently says:

This page covers using the Agent SDK via the CLI (claude -p). For the Python and TypeScript SDK packages with structured outputs, tool approval callbacks, and native message objects, see the full Agent SDK documentation.

The Agent SDK user-input page currently says:

Claude requests user input in two situations: when it needs permission to use a tool (like deleting files or running commands), and when it has clarifying questions (via the AskUserQuestion tool). Both trigger your canUseTool callback, which pauses execution until you return a response.

What's Wrong or Missing?

The current docs only describe MCP elicitation as an interactive dialog flow in Claude Code's TUI.

Claude Code v2.1.117 included a fix for MCP elicitation/create requests auto-cancelling in print/SDK mode when the server finishes connecting mid-turn. That implies MCP elicitation is expected to work in claude -p and Agent SDK sessions, but the current docs do not explain:

A. Whether print mode supports MCP elicitation

The headless docs do not say what happens if an MCP server requests form-mode or URL-mode elicitation during a claude -p run.

B. How Agent SDK applications should surface and complete MCP elicitation

The Agent SDK user-input docs only cover tool approvals and AskUserQuestion. They do not document MCP elicitation as another mid-turn input path, nor explain which SDK surface developers should use to present the request and return the result.

C. How the MCP docs map elicitation behavior across interactive vs programmatic surfaces

/docs/en/mcp currently reads as if elicitation always becomes an automatic interactive dialog, which is incomplete for programmatic clients.

Suggested Improvement

Add a short cross-surface section for MCP elicitation that covers interactive CLI, print mode, and Agent SDK behavior consistently.

At minimum, document:

1. Whether claude -p can encounter MCP elicitation requests and what output/control flow the caller should expect.
2. Which Agent SDK event, callback, hook, or message surface carries MCP elicitation requests.
3. How SDK apps should handle form-mode versus URL-mode elicitation and return success/cancel responses.
4. Cross-links between mcp, headless, and Agent SDK user-input/mcp pages so developers can find the complete flow from either starting point.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/mcp | Primary elicitation docs only describe interactive dialogs |
| https://code.claude.com/docs/en/headless | Print-mode docs omit MCP elicitation behavior |
| https://code.claude.com/docs/en/agent-sdk/mcp | Agent SDK MCP docs omit elicitation handling |
| https://code.claude.com/docs/en/agent-sdk/user-input | Agent SDK user-input docs only cover approvals and AskUserQuestion |
| https://code.claude.com/docs/en/agent-sdk/hooks | Mentions elicitation_dialog notifications but not how to complete an elicitation |
| https://platform.claude.com/docs/en/agent-sdk/mcp | Agent SDK cross-reference also omits MCP elicitation handling |
| https://platform.claude.com/docs/en/agent-sdk/user-input | Platform user-input docs only describe approvals and AskUserQuestion |

Total scope: 7 pages affected

Source: Changelog v2.1.117

Exact changelog entry: Fixed MCP \elicitation/create\ requests auto-cancelling in print/SDK mode when the server finishes connecting mid-turn