Roots and Elicitation — Scoping and Mid-Flight User Input

A notes MCP server hits two concrete failures in production.

Broken path assumption. The server is written against ~/notes. A user on another machine keeps notes in ~/Documents/Notes, and the tool call either fails silently (no file found) or writes to the wrong place.

Missing argument the user would know. The user asks "delete the old TPS report note". The model calls notes_delete(title: "TPS report"), but three notes match, from 2023, 2024, and 2025. The tool cannot guess. Failing with "ambiguous" is annoying, and running on all three is worse.

Roots fix the first. The client declares at initialize the set of URIs the server may touch. Elicitation fixes the second: the server pauses the tool call and sends elicitation/create so the user picks which note to delete.

Roots

The client declares a root list at initialize:

{
  "capabilities": {"roots": {"listChanged": true}}
}

Server can then call roots/list:

{"roots": [{"uri": "file:///Users/alice/Documents/Notes", "name": "Notes"}]}

Servers must treat roots as the boundary, and a file read or write outside the root set gets rejected. The client does not enforce this (the server is still code the user chose to trust), so it only holds when the server honors it, which spec-compliant servers do.

When the user adds or removes a root, the client sends notifications/roots/list_changed. The server re-calls roots/list and updates its boundary.

Why roots are a client primitive

The client declares roots because they encode the user's consent. The user told Claude Desktop "give this notes server access to these two directories", and the server has no way to widen that scope.

Elicitation: the form-mode default

elicitation/create takes a form schema plus a natural-language prompt:

{
  "method": "elicitation/create",
  "params": {
    "message": "Delete 'TPS report'? Multiple notes match; pick one.",
    "requestedSchema": {
      "type": "object",
      "properties": {
        "note_id": {
          "type": "string",
          "enum": ["note-3", "note-7", "note-14"]
        },
        "confirm": {"type": "boolean"}
      },
      "required": ["note_id", "confirm"]
    }
  }
}

Client renders a form, collects the user's answer, returns:

{
  "action": "accept",
  "content": {"note_id": "note-14", "confirm": true}
}

Three possible actions: accept (user filled it), decline (user closed it), cancel (user aborted the whole tool call).

Form schemas are flat. Nested objects are not supported in v1, and SDKs typically reject anything deeper than a single layer.

Elicitation: URL mode (SEP-1036, experimental)

New in 2025-11-25. Instead of a schema, the server sends a URL:

{
  "method": "elicitation/create",
  "params": {
    "message": "Sign in to GitHub",
    "url": "https://github.com/login/oauth/authorize?client_id=..."
  }
}

The client opens the URL in a browser, waits for completion, and returns when the user comes back. This suits OAuth flows, payment authorization, and document signing, where a form is not enough.

The SEP-1036 response shape is still settling. Some SDKs return the callback URL and others return a completion token, so read your SDK's release notes before using URL mode in production.

When elicitation is the right tool

• User confirmation before destructive actions (destructive hint + elicitation).
• Disambiguation (pick one of N matches).
• First-run setup (API keys, directories, preferences).
• OAuth-style flows (URL mode).

When elicitation is wrong

• Filling a tool's required arguments that the model could have asked for in prose. Use a normal re-prompt, not an elicitation dialog.
• High-frequency calls. Elicitation interrupts the conversation; do not fire it inside a loop.
• Anything the server could validate after the fact. Validate, return an error, let the model ask the user in text.

Human-in-the-loop bridge

Elicitation and sampling together give MCP its human-in-the-loop model. A server's agent loop can pause for user input (elicitation) or for model reasoning (sampling). Phase 13 · 11 covered sampling and this lesson covers elicitation. Combine them and the server controls the loop from the inside.

code/main.py extends the notes server with:

• roots/list response that the server re-queries after root-list-changed notifications.
• A notes_delete tool that uses elicitation/create to disambiguate when multiple notes match.
• A notes_setup tool that uses URL-mode elicitation to open a first-run config page (simulated).
• A boundary check that refuses operations on URIs outside the declared roots.

The demo runs four scenarios: happy path (one match), disambiguation (three matches, elicitation fires), out-of-root-write (rejected), and URL-mode setup (simulated).

This step produces outputs/skill-elicitation-form-designer.md. Given a tool that might need user confirmation or disambiguation, the skill designs the elicitation form schema and the message template.

1. Run code/main.py. Trigger the disambiguation path; confirm the simulated user answer gets routed back to the tool.

2. Add a new tool notes_archive that requires elicitation confirmation every time (destructive hint). Check the UX: how does this compare to the model re-asking in text?

3. Implement URL-mode elicitation for a first-run OAuth flow. Note the drift risk and add an SDK-version guard.

4. Extend roots/list handling: when a notification arrives, the server should atomically re-read and rescan open file handles that might now be out of scope.

5. Read the SEP-1036 issue discussion thread on GitHub. Identify one open question that affects how servers should handle URL-mode callbacks.

• MCP: Client roots spec: canonical roots reference
• MCP: Client elicitation spec: canonical elicitation reference
• Cisco: What's new in MCP elicitation, structured content, OAuth enhancements: 2025-11-25 additions walk-through
• MCP: GitHub SEP-1036: URL-mode elicitation proposal (experimental, drift-risk)
• The New Stack: How elicitation brings human-in-the-loop to AI tools: UX walkthrough