tools, resources, prompts method shapes

161 notes in this subject, read out of this brain and free to use. This is page 1 of 3.

Example: tools/call request with traceparent in _meta

A non-normative example request: {"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "get_weather", "arguments": {"location": "New York"}, "_meta": {"traceparent": "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01"}}}. This shows `_meta` living inside `params` for requests.

JSON Schema dialect rules in MCP

When a schema in MCP messages omits a `$schema` field it defaults to JSON Schema 2020-12; schemas MAY include `$schema` to specify a different dialect. Implementations MUST support at least 2020-12 and SHOULD document which additional dialects they support; using 2020-12 is RECOMMENDED. Clients and servers MUST support JSON Schema 2020-12 for schemas without an explicit `$schema`, MUST validate schemas according to their declared or default dialect, and MUST handle unsupported dialects gracefully by returning an appropriate error indicating the dialect is not supported. Schemas MUST be valid according to their declared or default dialect.

Icon object fields and required MIME type support

The `icons` property is an array of `Icon` objects with fields: `src` (required URI, either an HTTP/HTTPS URL to an image or a data URI with base64-encoded image data), `mimeType` (optional, if the server's type is missing or generic), `sizes` (optional array such as ["48x48"], ["any"] for scalable formats like SVG, or ["48x48", "96x96"]), and `theme` (optional, `light` or `dark`). Clients that support rendering icons MUST support at least image/png and image/jpeg (and image/jpg), and SHOULD also support image/svg+xml and image/webp. Icons can be attached to `Implementation`, `Tool`, `Prompt`, and `Resource` objects.

Servers MUST implement server/discover

Servers MUST implement the `server/discover` method. Clients MAY call it before sending any other requests to learn the server's supported versions up front, but are not required to; a client may invoke any RPC inline and handle UnsupportedProtocolVersionError if its preferred version is unsupported.

CacheableResult requires ttlMs and cacheScope

A new `CacheableResult` interface requires `ttlMs` and `cacheScope` fields on results returned by `tools/list`, `prompts/list`, `resources/list`, `resources/read`, and `resources/templates/list`. `ttlMs` is a freshness hint in milliseconds allowing clients to cache responses and reduce polling; `cacheScope` is `"public"` or `"private"` and controls whether shared intermediaries may cache the response. Both fields complement existing `listChanged` notifications (SEP-2549).

schema.json number vs integer fix for minimum/maximum/default

`schema.json` now correctly reflects that the TypeScript definitions of `minimum`, `maximum`, and `default` are `number` and not just integers; the earlier discrepancy was caused by running the generator with `--defaultNumberType integer` (PR #2710).

inputSchema/outputSchema loosened to full JSON Schema 2020-12

`inputSchema` and `outputSchema` were loosened to allow any JSON Schema 2020-12 keywords, and `structuredContent` may be any JSON value. `$ref` resolution requirements and composition-keyword resource bounds were added (SEP-2106).

includeContext values thisServer and allServers deprecated

The sampling `includeContext` values `"thisServer"` and `"allServers"` (soft-deprecated since 2025-11-25) are now Deprecated. Implementations should omit the field or use `"none"`; these values will be removed no later than the Sampling feature itself.

Tasks moved to io.modelcontextprotocol/tasks extension

Experimental tasks were moved out of the core protocol into an official extension named `io.modelcontextprotocol/tasks` (SEP-2663). The redesigned extension replaces the blocking `tasks/result` method with polling via `tasks/get`, adds `tasks/update` for client-to-server input, removes `tasks/list`, and allows servers to return task handles unsolicited without per-request opt-in.

Roots user interaction model not mandated

Roots are typically exposed through workspace or project configuration interfaces such as a workspace/project picker, optionally combined with automatic workspace detection from version control systems or project files, but the protocol does not mandate any specific user interaction model.

Roots feature deprecated in 2026-07-28

The Roots feature is deprecated as of MCP protocol version 2026-07-28 (SEP-2577). Under the feature lifecycle policy it remains in the specification for at least twelve months after that revision's release before becoming eligible for removal. New implementations SHOULD NOT adopt it; existing implementations SHOULD migrate to passing directories or files via tool parameters, resource URIs, or server configuration.

Root object fields: uri MUST be file://

A Root definition includes `uri`, a unique identifier for the root which MUST be a `file://` URI in the current specification, and `name`, an optional human-readable name for display purposes.

Tool use and tool result balance requirement

When using tool use in sampling, every assistant message containing ToolUseContent blocks MUST be followed by a user message consisting entirely of ToolResultContent blocks, with each tool use (id: $id) matched by a corresponding tool result (toolUseId: $id), before any other message. A sequence that omits a result for one of the tool use ids is invalid.

Tool result messages MUST contain only tool results

When a user message contains tool results (content blocks of type "tool_result"), it MUST contain ONLY tool results. Mixing tool results with other content types (text, image, audio) in the same message is not allowed. This ensures compatibility with provider APIs that use dedicated roles for tool results (e.g. OpenAI's "tool" role, Gemini's "function" role).

sampling/createMessage request params shape

A `sampling/createMessage` request has params: `messages` (array of {role, content}), optional `modelPreferences` ({hints: [{name}], costPriority, intelligencePriority, speedPriority}), optional `temperature`, optional `systemPrompt`, optional `includeContext`, required `maxTokens`, optional `stopSequences`, optional `metadata`, and optionally `tools` and `toolChoice`. Example: {"method":"sampling/createMessage","params":{"messages":[{"role":"user","content":{"type":"text","text":"What is the capital of France?"}}],"modelPreferences":{"hints":[{"name":"claude-3-sonnet"}],"costPriority":0.3,"intelligencePriority":0.8,"speedPriority":0.5},"temperature":0.1,"systemPrompt":"You are a helpful assistant.","includeContext":"thisServer","maxTokens":100}}.

Sampling message role and content requirements

Sampling messages MUST contain a `role` field of "user" or "assistant", and a `content` field representing the message data. The list of messages in a sampling request SHOULD NOT be retained between separate requests. Content block types are text ({"type":"text","text":...}), image ({"type":"image","data":"base64...","mimeType":"image/jpeg"}), and audio ({"type":"audio","data":"base64...","mimeType":"audio/wav"}).

Sampling stopReason values

The spec defines the following non-exhaustive stopReason values, and implementations MAY provide their own arbitrary values: "endTurn" (the participant is yielding the conversation to the other party), "stopSequence" (generation encountered one of the requested stopSequences), "maxTokens" (the token limit was reached), and "toolUse" (the model wants to use one or more tools).

CreateMessageResult (sampling result) fields

A sampling result contains: `role` ("user" or "assistant"), `content` (either a single content block object or an array of content blocks), `model` (name of the model that generated the message), and `stopReason`. Example: {"role":"assistant","content":{"type":"text","text":"The capital of France is Paris."},"model":"claude-3-sonnet-20240307","stopReason":"endTurn"}.

Sampling feature deprecated in protocol version 2026-07-28

The Sampling feature is deprecated as of protocol version 2026-07-28 (SEP-2577). Under the feature lifecycle policy it remains in the specification for at least twelve months after that revision's release before becoming eligible for removal. New implementations SHOULD NOT adopt it; existing implementations SHOULD migrate to integrating directly with LLM provider APIs.

Sampling message roles limited to user and assistant

MCP sampling uses two roles: "user" and "assistant". Tool use requests are returned in CreateMessageResult with the "assistant" role, and tool results are sent back in messages with the "user" role. Messages containing tool results cannot contain other kinds of content.

Multi-turn tool loop in sampling

After receiving tool use requests from the LLM, the server typically: 1) executes the requested tool uses, 2) sends a new sampling request with tool results appended, 3) receives the LLM's response (which might contain new tool uses), 4) repeats as needed. A server might cap the maximum number of iterations and e.g. pass toolChoice: {mode: "none"} on the last iteration to force a final result.

systemPrompt may be modified or ignored by the client

The optional `systemPrompt` field allows servers to request a specific system prompt. The client MAY modify or ignore this field without communicating this to the server.

Sampling tools array and tool definition shape

Servers may include a `tools` array in `sampling/createMessage` params; each entry has `name`, `description`, and `inputSchema` (a JSON Schema object with `type`, `properties`, `required`). Tool definitions in this array are scoped to the sampling request and do not need to correspond to registered tools.

Model preferences: priorities and hints

Servers express model needs through three normalized priority values in 0-1: `costPriority` (higher prefers cheaper models), `speedPriority` (higher prefers faster models), and `intelligencePriority` (higher prefers more capable models). `hints` is an ordered array of {name} objects treated as substrings that can match model names flexibly; multiple hints are evaluated in order of preference. Clients MAY map hints to equivalent models from different providers, and hints are advisory since clients make the final model selection.

Client MUST respect maxTokens; MAY ignore temperature, stopSequences, metadata

Sampling parameters are `temperature` (randomness; valid range depends on the model provider), `maxTokens` (maximum tokens to generate; required), `stopSequences` (array of sequences that stop generation), and `metadata` (provider-specific parameters). The client MUST respect the `maxTokens` parameter. The client MAY modify or ignore `temperature`, `stopSequences` and `metadata`.

Parallel tool use allowed in sampling

MCP allows models to make multiple tool use requests in parallel, returning an array of ToolUseContent blocks. Claude and Gemini support this natively; OpenAI supports parallel tool calls and can disable them with parallel_tool_calls: false. Implementations wrapping providers that support disabling parallel tool use MAY expose this as an extension, but it is not part of the core MCP specification.

ToolUseContent and ToolResultContent block shapes

A tool use block is {"type":"tool_use","id":"call_abc123","name":"get_weather","input":{"city":"Paris"}} and appears in an assistant-role message. A tool result block is {"type":"tool_result","toolUseId":"call_abc123","content":[{"type":"text","text":"Weather in Paris: 18°C, partly cloudy"}]} and appears in a user-role message.

toolChoice modes: auto, required, none

`CreateMessageRequest.params.toolChoice` controls the model's tool use ability: {mode: "auto"} means the model decides whether to use tools (default); {mode: "required"} means the model MUST use at least one tool before completing; {mode: "none"} means the model MUST NOT use any tools.

Sampling includeContext 'thisServer' and 'allServers' deprecated

The sampling request field values includeContext: "thisServer" and includeContext: "allServers" were deprecated in revision 2025-11-25 via SEP-2596. Migration path: omit the includeContext field entirely or use the value "none". Their removal follows the removal of Sampling itself (SEP-2577).

Logging utility deprecated in 2026-07-28

The Logging server utility (server/utilities/logging) was deprecated in revision 2026-07-28 via SEP-2577. Migration path: log to stderr for stdio transports, and use OpenTelemetry for observability. Earliest removal: the first revision released on or after 2027-07-28.

Sampling deprecated in 2026-07-28

The Sampling feature (client/sampling) was deprecated in revision 2026-07-28 via SEP-2577. Migration path: integrate directly with LLM provider APIs. Earliest removal: the first revision released on or after 2027-07-28.

Roots deprecated in 2026-07-28

The Roots feature (client/roots) was deprecated in revision 2026-07-28 via SEP-2577. Migration path: pass directories or files via tool parameters, resource URIs, or server configuration. Earliest removal: the first revision released on or after 2027-07-28.

Server features: resources, prompts, tools

Servers offer any of the following features to clients: Resources (context and data for the user or the AI model to use), Prompts (templated messages and workflows for users), and Tools (functions for the AI model to execute).

Control hierarchy of MCP primitives (user/application/model controlled)

MCP defines a control hierarchy for server primitives: Prompts are user-controlled (interactive templates invoked by user choice, e.g. slash commands or menu options); Resources are application-controlled (contextual data attached and managed by the client, e.g. file contents, git history); Tools are model-controlled (functions exposed to the LLM to take actions, e.g. API POST requests, file writing).

Three server primitives: prompts, resources, tools

The MCP server specification defines three primitives that servers provide: Prompts (pre-defined templates or instructions that guide language model interactions), Resources (structured data or content providing additional context to the model), and Tools (executable functions that allow models to perform actions or retrieve information).

Image and audio content MUST be base64 with MIME type

In prompt messages, image data MUST be base64-encoded and include a valid MIME type; audio data MUST likewise be base64-encoded and include a valid MIME type.

Embedded resource required fields

Embedded resources in prompt messages can contain either text or binary (blob) data and MUST include a valid resource URI, the appropriate MIME type, and either text content or base64-encoded blob data.

PromptMessage role and content types

A PromptMessage has `role` which is either "user" or "assistant", and `content` which is one of: text ({"type":"text","text":...}), image ({"type":"image","data":base64,"mimeType":"image/png"}), audio ({"type":"audio","data":base64,"mimeType":"audio/wav"}), resource_link ({"type":"resource_link","uri":...,"name":...,"description":...,"mimeType":...}), or embedded resource ({"type":"resource","resource":{"uri":...,"mimeType":...,"text":...}}). All content types support optional annotations for audience, priority, and modification times.

Prompt definition fields

A prompt definition includes: `name` (unique identifier), `title` (optional human-readable display name), `description` (optional human-readable description), `icons` (optional array of icons for UI display), and `arguments` (optional list of arguments for customization, each with name, description, required).

prompts/get request and response shape

A `prompts/get` request has params `name` (prompt name) and `arguments` (object of argument name to value), e.g. {"jsonrpc":"2.0","id":2,"method":"prompts/get","params":{"name":"code_review","arguments":{"code":"def hello():\n print('world')"}}}. The response result contains `resultType: "complete"`, an optional `description`, and a `messages` array of PromptMessage objects each with `role` and `content`.

prompts/list response shape (2026-07-28)

A `prompts/list` result contains `resultType: "complete"`, a `prompts` array, and optional `nextCursor`, `ttlMs` and `cacheScope` fields. Example: {"jsonrpc":"2.0","id":1,"result":{"resultType":"complete","prompts":[{"name":"code_review","title":"Request Code Review","description":"Asks the LLM to analyze code quality and suggest improvements","arguments":[{"name":"code","description":"The code to review","required":true}],"icons":[{"src":"https://example.com/review-icon.svg","mimeType":"image/svg+xml","sizes":["any"]}]}],"nextCursor":"next-page-cursor","ttlMs":600000,"cacheScope":"public"}}.

prompts/list request shape

A `prompts/list` request is JSON-RPC 2.0 with an id and optional pagination cursor: {"jsonrpc":"2.0","id":1,"method":"prompts/list","params":{"cursor":"optional-cursor-value"}}. The operation supports pagination and caching.

Resource annotations: audience, priority, lastModified

Resources, resource templates and content blocks support optional `annotations`: `audience` (array of "user" and/or "assistant"), `priority` (number 0.0–1.0 where 1 means most important/effectively required and 0 means least important/entirely optional), and `lastModified` (ISO 8601 timestamp, e.g. "2025-01-12T15:00:58Z"). Example: {"annotations":{"audience":["user"],"priority":0.8,"lastModified":"2025-01-12T15:00:58Z"}}.

Resource contents: text vs binary

Resource contents are either text — {"uri":"file:///example.txt","mimeType":"text/plain","text":"Resource content"} — or binary — {"uri":"file:///example.png","mimeType":"image/png","blob":"base64-encoded-data"}. Binary data MUST be properly (base64) encoded.

Resource definition fields

A resource definition includes: `uri` (unique identifier, required), `name` (name of the resource), `title` (optional human-readable display name), `description` (optional), `icons` (optional array of icons for UI display), `mimeType` (optional), and `size` (optional size in bytes).

notifications/resources/list_changed

When the list of available resources changes, servers that declared the `listChanged` capability SHOULD send the notification {"jsonrpc":"2.0","method":"notifications/resources/list_changed"} (no params required).

resources/templates/list request and response shape

Request: {"jsonrpc":"2.0","id":3,"method":"resources/templates/list","params":{"cursor":"optional-cursor-value"}}. Response result contains `resultType`, a `resourceTemplates` array whose entries have `uriTemplate` (RFC 6570 URI template, e.g. "file:///{path}"), `name`, `title`, `description`, `mimeType`, optional `icons`, plus `nextCursor`, `ttlMs`, and `cacheScope`. Template arguments may be auto-completed via the completion API; the operation supports pagination and caching.

resources/read request and response shape

Request: {"jsonrpc":"2.0","id":2,"method":"resources/read","params":{"uri":"file:///project/src/main.rs"}}. Response result contains `resultType` ("complete"), a `contents` array of resource contents objects (each with `uri`, `mimeType`, and either `text` or base64 `blob`), and optional `ttlMs` (e.g. 60000) and `cacheScope` (e.g. "private"). Servers MAY return multiple resource contents in a single response, for example all files in a directory resource.

resources/list request and response shape

Request: {"jsonrpc":"2.0","id":1,"method":"resources/list","params":{"cursor":"optional-cursor-value"}}. Response result contains `resultType` (e.g. "complete"), a `resources` array whose entries have `uri`, `name`, `title`, `description`, `mimeType`, and optional `icons` (each icon has `src`, `mimeType`, `sizes` array like ["48x48"]), plus optional `nextCursor`, `ttlMs` (e.g. 300000) and `cacheScope` (e.g. "public"). The operation supports pagination and caching.

Common resource URI schemes: https, file, git, custom

The protocol defines standard URI schemes but the list is not exhaustive. `https://` represents a web resource and servers SHOULD use it only when the client can fetch and load the resource directly from the web without going through the MCP server; otherwise servers SHOULD prefer another or custom scheme. `file://` identifies resources that behave like a filesystem (need not map to a real filesystem); servers MAY use an XDG MIME type such as `inode/directory` for non-regular files. `git://` is for Git version control integration. Custom URI schemes MUST comply with RFC 3986.

tools/list request and response shape

Request: {"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"cursor":"optional-cursor-value"}}. Response result contains "resultType":"complete", a "tools" array, and optional "nextCursor", "ttlMs" (e.g. 300000) and "cacheScope" (e.g. "public"). Each tool entry can include name, title, description, inputSchema, and icons (array of objects with src, mimeType, sizes such as ["48x48"]). The operation supports pagination and caching.

Deterministic ordering of tools/list

Servers SHOULD return tools in a deterministic order (the same ordering across requests when the underlying set of tools has not changed), which enables clients to cache the tool list and improves LLM prompt cache hit rates.

tools/list result set must not vary per connection

Servers that declare the `tools` capability MUST respond to `tools/list` requests with the set of tools 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 tools the caller's granted scopes permit), since credentials are per-request input, not connection state.

Tool name collisions across aggregated servers

Tool name uniqueness is scoped to a single server. Clients or proxies that aggregate tools from multiple servers MAY encounter naming collisions (e.g. two servers each exposing a `search` tool) and SHOULD implement a disambiguation strategy such as prefixing tool names with a server identifier. The server `name` from `serverInfo` is not guaranteed unique across servers and SHOULD NOT be relied on for disambiguation.

Tool definition fields

A tool definition includes: `name` (unique identifier), optional `title` (human-readable display name), `description`, optional `icons` array, `inputSchema` (JSON Schema of expected parameters), optional `outputSchema` (JSON Schema of output structure), and optional `annotations` describing tool behavior.

Tool result content block types

Unstructured tool results go in the `content` array and may mix types: text ({"type":"text","text":...}), image ({"type":"image","data":base64,"mimeType":"image/png"}), audio ({"type":"audio","data":base64,"mimeType":"audio/wav"}), resource_link ({"type":"resource_link","uri":...,"name":...,"description":...,"mimeType":...}), and embedded resource ({"type":"resource","resource":{uri, mimeType, text, annotations}}). All content types support optional annotations with audience, priority, and lastModified.

tools/call request and response shape

Request: {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_weather","arguments":{"location":"New York"}}}. Successful response: {"jsonrpc":"2.0","id":2,"result":{"resultType":"complete","content":[{"type":"text","text":"..."}],"isError":false}}.

inputSchema MUST be a valid JSON Schema object

A tool's `inputSchema` MUST be a valid JSON Schema object (not `null`). It follows the JSON Schema usage guidelines and defaults to draft 2020-12 if no `$schema` field is present. For tools with no parameters, the recommended form is `{"type":"object","additionalProperties":false}` (accepts only empty objects); `{"type":"object"}` is also valid but accepts any object. `outputSchema` also defaults to 2020-12 when `$schema` is absent.

Tool name constraints

Tool names SHOULD be between 1 and 128 characters inclusive, SHOULD be considered case-sensitive, SHOULD only use uppercase and lowercase ASCII letters (A-Z, a-z), digits (0-9), underscore (_), hyphen (-) and dot (.), SHOULD NOT contain spaces, commas or other special characters, and SHOULD be unique within a server. Valid examples: `getUser`, `DATA_EXPORT_v2`, `admin.tools.list`.

Embedded resources and resources capability

Tools MAY return links to resources (`resource_link`) or embed resources (`type":"resource"`) using a suitable URI scheme. Servers that use embedded resources SHOULD implement the `resources` capability. Resource links returned by tools are not guaranteed to appear in the results of a `resources/list` request.

Give your agent this brain