capabilities

41 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Capabilities must be respected and server features must be advertised

MCP requires that both parties respect declared capabilities throughout the interaction. Implemented server features must be advertised in the server's capabilities, and tool invocation requires the server to declare tool capabilities. Each capability unlocks specific protocol features on a per-request basis. Servers must respect security constraints.

Client capabilities travel in _meta.io.modelcontextprotocol/clientCapabilities on every request

In MCP 2026-07-28, clients include their capabilities in the `_meta.io.modelcontextprotocol/clientCapabilities` field on every request, rather than negotiating once at initialize time. Clients also attach the protocol version to every request via `_meta`.

Client capability examples vs server capability examples

In MCP capability negotiation, servers declare capabilities such as tool support, resource subscriptions, and prompt templates, while clients declare capabilities such as sampling support and elicitation handling. Additional capabilities can be negotiated through extensions to the protocol.

Advertising CIMD support via client_id_metadata_document_supported

Authorization servers advertise support for Client ID Metadata Documents by including {"client_id_metadata_document_supported": true} in their OAuth Authorization Server metadata. MCP clients SHOULD check for this capability and MAY fall back to Dynamic Client Registration or pre-registration if it is unavailable.

Server must not rely on undeclared client capabilities (-32021)

A server MUST NOT rely on capabilities the client has not declared. If processing a request requires a capability the client did not include in `io.modelcontextprotocol/clientCapabilities`, the server MUST return a MissingRequiredClientCapabilityError (code -32021) whose `data.requiredCapabilities` lists the missing capabilities; on HTTP the response status MUST be 400 Bad Request.

Server MUST NOT request capabilities the client did not declare

Servers MUST NOT send an `inputRequests` entry of a type the client has not declared support for in its capabilities. For example, if a client does not declare `elicitation` support, the server MUST NOT include any `elicitation/create` requests in `inputRequests`.

Extensions are negotiated via capabilities.extensions map

Optional extensions beyond the core protocol are advertised in the `extensions` field of capabilities, a map of extension identifiers to per-extension settings objects. Extension identifiers MUST follow the `_meta` key naming rules, including a mandatory prefix. Each extension specifies the schema of its settings object; an empty object indicates support with no additional settings.

Example capabilities with MCP Apps and Tasks extensions

Example client capabilities advertising the MCP Apps extension: {"capabilities":{"roots":{},"extensions":{"io.modelcontextprotocol/ui":{"mimeTypes":["text/html;profile=mcp-app"]}}}}. Example advertising the Tasks extension: {"capabilities":{"tools":{},"extensions":{"io.modelcontextprotocol/tasks":{}}}}.

Unsupported extension fallback requirement

If one party supports an extension but the other does not, the supporting party MUST either revert to core protocol behavior or reject the request with an appropriate error. Extensions SHOULD document their expected fallback behavior.

extensions field on ClientCapabilities and ServerCapabilities

An `extensions` field was added to both `ClientCapabilities` and `ServerCapabilities` to support optional extensions beyond the core protocol.

Deprecated features in 2026-07-28: Roots, Sampling, Logging

The Roots, Sampling, and Logging features are deprecated (SEP-2577). They remain fully functional during the deprecation window, but new implementations should not add support. Suggested migrations: pass directories or files via tool parameters, resource URIs, or server configuration instead of Roots; integrate directly with LLM provider APIs instead of Sampling; log to `stderr` (stdio) or use OpenTelemetry instead of Logging.

Elicitation capability declaration in _meta.io.modelcontextprotocol/clientCapabilities

Clients that support elicitation MUST declare the `elicitation` capability in `_meta.io.modelcontextprotocol/clientCapabilities` on each request, e.g. {"_meta": {"io.modelcontextprotocol/clientCapabilities": {"elicitation": {"form": {}, "url": {}}}}}. For backwards compatibility an empty object `"elicitation": {}` is equivalent to `{ "form": {} }` (form mode only). Clients declaring the capability MUST support at least one mode (`form` or `url`).

Servers MUST NOT send unsupported elicitation modes

Servers MUST NOT send elicitation requests with modes that are not supported by the client, as declared in the client's `elicitation` capability object (`form` and/or `url`).

roots client capability declared in _meta per request

Clients that support roots MUST declare the `roots` capability in `_meta.io.modelcontextprotocol/clientCapabilities` on each request, e.g. {"_meta": {"io.modelcontextprotocol/clientCapabilities": {"roots": {}}}}.

sampling capability declared in _meta.io.modelcontextprotocol/clientCapabilities

Clients that support sampling MUST declare the `sampling` capability in `_meta.io.modelcontextprotocol/clientCapabilities` on each request. Basic form: {"_meta": {"io.modelcontextprotocol/clientCapabilities": {"sampling": {}}}}. Tool-use support adds a nested `tools` object: {"sampling": {"tools": {}}}. Context inclusion support (deprecated) adds a nested `context` object: {"sampling": {"context": {}}}.

Tool-enabled sampling requires sampling.tools capability

Clients MUST declare support for tool use via the `sampling.tools` capability to receive tool-enabled sampling requests. Servers MUST NOT send tool-enabled sampling requests to clients that have not declared support for tool use via the `sampling.tools` capability.

includeContext values and deprecation

The `includeContext` parameter specifies what context the client is expected to include: "none" (no additional context, the default), "thisServer" (context from the requesting server), and "allServers" (context from all connected MCP servers). "thisServer" and "allServers" are deprecated (SEP-2596) and will be removed no later than the Sampling feature itself; servers SHOULD avoid them and SHOULD NOT use them unless the client declares the `sampling.context` capability. The client MAY modify or ignore includeContext without telling the server.

Base protocol key details: stateless requests and per-request capability negotiation

The MCP 2026-07-28 base protocol is characterised by: the JSON-RPC message format, stateless self-contained requests, and per-request capability negotiation.

Extensions are opt-in and negotiated during initialization

MCP defines optional extensions beyond the core protocol that add modular, specialized or experimental functionality. Extensions are always opt-in and require explicit support from both client and server, negotiated during initialization. Notable extensions are Tasks (asynchronous execution of long-running operations with polling, mid-flight input, and durable handles), Skills over MCP (structured instructions for agent workflows), and MCP Apps (interactive UI elements such as charts, forms, and video players rendered inline in conversations).

prompts/list result set must not vary per connection

Servers that declare the `prompts` capability MUST respond to `prompts/list` requests with the set of prompts currently available to the requesting client. This set MAY be empty and MAY change over time, but MUST NOT vary per-connection or as a side effect of other requests on the connection. The set MAY vary by the authorization presented on the request (e.g. returning only prompts the caller's granted scopes permit), since credentials are per-request input, not connection state.

prompts capability declaration in DiscoverResult

Servers that support prompts MUST declare the `prompts` capability in their `DiscoverResult`, e.g. `{"capabilities": {"prompts": {"listChanged": true}}}`. The `listChanged` flag indicates whether the server will emit notifications when the list of available prompts changes.

resources capability declaration MUST

Servers that support resources MUST declare the `resources` capability during initialization. It supports two optional boolean features: `listChanged` (server emits notifications when the resource list changes) and `subscribe` (server supports resource-specific update notifications for resources requested via subscriptions/listen with the resourceSubscriptions filter). Example: {"capabilities":{"resources":{"listChanged":true,"subscribe":true}}}. Servers may advertise either feature independently, together, or neither; servers supporting neither may declare {"capabilities":{"resources":{}}}.

resources/list must not vary per connection

Servers that declare the `resources` capability MUST respond to `resources/list` requests with the set of resources currently available to the requesting client. That set MAY be empty and MAY change over time, but MUST NOT vary per-connection or as a side effect of other requests on the connection. The set MAY vary by the authorization presented on the request (e.g., returning only resources the caller's granted scopes permit), since credentials are per-request input, not connection state.

tools capability declaration with listChanged

Servers that support tools MUST declare the `tools` capability during initialization, e.g. `{"capabilities": {"tools": {"listChanged": true}}}`. The `listChanged` flag indicates whether the server will emit notifications when the list of available tools changes.

completions capability MUST be declared by servers supporting completion

Servers that support argument autocompletion MUST declare the `completions` capability during initialization, e.g. `{"capabilities": {"completions": {}}}`. The capability object is currently empty.

logging server capability declaration

Servers that emit log message notifications MUST declare the `logging` capability during initialization, e.g. {"capabilities": {"logging": {}}} — an empty object as the capability value.

DiscoverResult field semantics

In DiscoverResult: `supportedVersions` lists protocol versions the server supports and the client should choose one of these for subsequent requests; `capabilities` lists capabilities the server supports (tools, resources, prompts, etc.); `_meta['io.modelcontextprotocol/serverInfo']` gives the name and version of the server software and servers **SHOULD** include this field; `instructions` is optional natural-language guidance for LLMs on using the server effectively.

Capabilities are declared per-request, not at initialization

`io.modelcontextprotocol/clientCapabilities` in a request's `_meta` is required and carries the client's capabilities for that specific request. Capabilities are declared per-request rather than once at initialization; an empty object `{}` means the client supports no optional capabilities. Servers MUST NOT infer capabilities from prior requests.

Example -32021 missing elicitation capability response

Example MissingRequiredClientCapabilityError: {"jsonrpc": "2.0", "id": 1, "error": {"code": -32021, "message": "Server requires the elicitation capability for this request", "data": {"requiredCapabilities": {"elicitation": {}}}}}.

sampling tools/toolChoice require ClientCapabilities.sampling.tools

In sampling/createMessage params, the client MUST return an error if `tools` is provided but `ClientCapabilities.sampling.tools` is not declared, and likewise MUST return an error if `toolChoice` is provided without that capability. The default toolChoice is `{ mode: "auto" }`.

includeContext defaults to "none"; thisServer/allServers deprecated

`includeContext` defaults to `"none"`. The values `"thisServer"` and `"allServers"` are deprecated as of protocol version 2025-11-25 (SEP-2596): servers SHOULD omit the field or use `"none"`, and SHOULD only use the deprecated values if the client declares `ClientCapabilities.sampling.context`. They will be removed no later than the Sampling feature itself (SEP-2577).

ClientCapabilities fields (2026-07-28)

ClientCapabilities is an open (non-closed) set with these known fields, all optional: `experimental?: { [key: string]: JSONObject }`, `roots?: {}` (deprecated), `sampling?: { context?: JSONObject; tools?: JSONObject }` (deprecated), `elicitation?: { form?: JSONObject; url?: JSONObject }`, and `extensions?: { [key: string]: JSONObject }`. Any client can define additional capabilities.

roots and sampling client capabilities deprecated in 2026-07-28

The `roots` and `sampling` client capabilities are deprecated as of protocol version 2026-07-28 (SEP-2577). They remain in the specification for at least twelve months; see the deprecated features registry.

sampling capability sub-flags: context and tools

Within ClientCapabilities.sampling, `context` declares whether the client supports context inclusion via the `includeContext` parameter — if not declared, servers SHOULD only use `includeContext: "none"` (or omit it). `tools` declares whether the client supports tool use via the `tools` and `toolChoice` parameters. Baseline support is declared as {"sampling": {}}; tool use as {"sampling": {"tools": {}}}; context inclusion as {"sampling": {"context": {}}}.

elicitation capability form and url modes

ClientCapabilities.elicitation is present if the client supports elicitation from the server, with optional `form` and `url` sub-objects. Declaring both modes: {"elicitation": {"form": {}, "url": {}}}. Declaring an empty object {"elicitation": {}} implicitly means form mode only.

extensions capability keys MUST use prefixed _meta naming

Both ClientCapabilities.extensions and ServerCapabilities.extensions map extension identifiers (e.g., "io.modelcontextprotocol/oauth-client-credentials", "io.modelcontextprotocol/ui", "io.modelcontextprotocol/tasks") to per-extension settings objects; an empty object indicates support with no settings. Keys MUST follow the `_meta` key naming rules, with a mandatory prefix.

Extensions capability examples (UI and Tasks)

Client extension example: {"extensions": {"io.modelcontextprotocol/ui": {"mimeTypes": ["text/html;profile=mcp-app"]}}}. Server extension example: {"extensions": {"io.modelcontextprotocol/tasks": {}}}.

ServerCapabilities fields (2026-07-28)

ServerCapabilities is an open set with these optional known fields: `experimental?: { [key: string]: JSONObject }`, `logging?: JSONObject` (deprecated as of 2026-07-28, SEP-2577), `completions?: JSONObject`, `prompts?: { listChanged?: boolean }`, `resources?: { subscribe?: boolean; listChanged?: boolean }`, `tools?: { listChanged?: boolean }`, and `extensions?: { [key: string]: JSONObject }`.

Server capability declaration examples

Minimum baseline declarations are empty objects: {"logging": {}}, {"completions": {}}, {"prompts": {}}, {"resources": {}}, {"tools": {}}. Notification support is declared as {"prompts": {"listChanged": true}}, {"tools": {"listChanged": true}}, {"resources": {"subscribe": true}}, {"resources": {"listChanged": true}}, or {"resources": {"subscribe": true, "listChanged": true}}.

Meaning of prompts, resources, tools server capabilities

ServerCapabilities.prompts is present if the server offers any prompt templates; `listChanged` indicates support for notifications about prompt list changes. ServerCapabilities.resources is present if the server offers any resources to read; `subscribe` indicates support for subscribing to resource updates and `listChanged` for resource list change notifications. ServerCapabilities.tools is present if the server offers any tools to call; `listChanged` indicates tool list change notifications. `completions` is present if the server supports argument autocompletion suggestions; `logging` is present if the server supports sending log messages to the client.

Icon MIME types clients MUST support

Clients that support rendering icons MUST support at least image/png and image/jpeg (including image/jpg). They SHOULD also support image/svg+xml (scalable but requires security precautions) and image/webp.

Give your agent this brain