D2 · Tool Design & MCP › Cluster 6 · MCP Primitives

6.5 · Roots & Elicitation

Client-provided context & input

CONCEPT Roots: the client tells the server where it may operate

Tools, resources, and prompts flow server → client. Roots and elicitation flow the other way — they are client-side capabilities the server reaches into. A root defines a boundary: the spec says roots "define the boundaries of where servers can operate within the filesystem." The client exposes a set of roots (each a file:// URI with an optional name); the server calls roots/list to learn them and stays inside those boundaries.

AspectRoots
Who providesThe client (workspace/project config)
CapabilityDeclared by the client: "roots": { "listChanged": true }
DiscoveryServer sends roots/list
Change signalnotifications/roots/list_changed
Root fieldsuri (MUST be a file:// URI) + optional name
PurposeScope the server to allowed directories — a security boundary
🔑 Roots are client-provided context: they let a server discover which directories a workspace has opened (e.g. a repo) so it operates only where it's allowed — and re-checks when the client sends notifications/roots/list_changed.

CONCEPT Elicitation: the server asks the user for structured input

Elicitation (newly introduced in the 2025-06-18 spec) lets a server request additional information from the user, through the client, mid-operation. The server sends elicitation/create with a human-readable message and a requestedSchema (a restricted, flat JSON Schema of primitive properties). The client renders a form; the user responds. This enables interactive workflows — an input request nested inside another server feature.

Responses use a three-action model: accept (user submitted — data is in content), decline (explicit "no"), or cancel (dismissed without choosing). Servers handle each differently.

⚠️ Guardrail: servers MUST NOT use elicitation to request sensitive information. The client SHOULD show which server is asking and let the user review, edit, decline, or cancel.

DIAGRAM Client boundaries (roots) vs. server asking (elicitation)

sequenceDiagram participant Server participant Client participant User Note over Server,Client: Roots — client-provided boundaries Server->>Client: roots/list Client-->>Server: [file:///…/myproject] Client--)Server: notifications/roots/list_changed Note over Server,User: Elicitation — server asks the user Server->>Client: elicitation/create {message, requestedSchema} Client->>User: Present form User-->>Client: accept / decline / cancel Client-->>Server: {action, content?} classDef srv fill:#d4edda,stroke:#28a745,color:#155724; classDef cli fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; class Server srv; class Client cli;

CODE A root list and an elicitation request

The client returns its filesystem roots; the server later asks the user for a value it needs, constrained by a flat schema, and reads the chosen action.

// roots/list  → client tells the server its allowed boundaries
{ "result": {
    "roots": [
      { "uri": "file:///home/user/projects/myproject", "name": "My Project" }
    ]
} }

// elicitation/create  → server asks the user for structured input mid-op
{ "method": "elicitation/create",
  "params": {
    "message": "Please provide your GitHub username",
    "requestedSchema": {
      "type": "object",
      "properties": { "name": { "type": "string" } },
      "required": ["name"]
    }
} }

// response  → three-action model: accept | decline | cancel
{ "result": { "action": "accept", "content": { "name": "octocat" } } }

TRADE-OFFS Where roots and elicitation sit

CapabilityDirectionWhat it providesMethod(s)
RootsClient → Server (server reads)Allowed filesystem boundariesroots/list, notifications/roots/list_changed
ElicitationServer → Client → UserStructured user input mid-operationelicitation/create
Sampling (6.4)Server → Client → LLMA completion from the client's modelsampling/createMessage
All three are client-declared capabilities the server leverages — the mirror image of server-declared tools/resources/prompts. Roots bound where; elicitation gathers input; sampling borrows the model.

EXAM TRAPS

Trap: "The server defines its own roots." → No. The client provides roots; the server calls roots/list to learn its boundaries and must respect them.
Trap: "A root can be any URI." → In the current spec a root's uri MUST be a file:// URI.
Trap: "Elicitation is fine for passwords/API keys." → Servers MUST NOT request sensitive information via elicitation.
Trap: Treating decline and cancel as the same. → It's a three-action model: accept (with content), decline (explicit no), cancel (dismissed) — and requestedSchema is limited to flat, primitive properties.

PRACTICE

Q1 · Who provides roots, and what are they for?

The client provides them (from workspace/project config). They define the filesystem boundaries — file:// URIs — where a server may operate. The server learns them via roots/list and re-checks on notifications/roots/list_changed.

Q2 · What are the three elicitation response actions?

accept (user submitted; data in content), decline (explicit refusal), and cancel (dismissed without choosing). Servers should handle each differently.

Q3 · How do roots, elicitation, and sampling relate as a group?

All three are client-declared capabilities the server uses — the mirror of server-side tools/resources/prompts. Roots bound where the server works, elicitation gathers structured user input mid-operation, and sampling borrows the client's LLM.