MCP · Building servers and clients · all subjects

primitives: prompts

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

prompts/list and prompts/get protocol methods

Prompts use two protocol operations: `prompts/list` discovers available prompts and returns an array of prompt descriptors; `prompts/get` retrieves prompt details and returns the full prompt definition with arguments.

Prompt definition JSON with typed arguments

A prompt is declared with `name`, `title`, `description` and an `arguments` array where each argument has name, type, optional description and a `required` flag. Example: { "name": "plan-vacation", "title": "Plan a vacation", "description": "Guide through vacation planning process", "arguments": [ { "name": "destination", "type": "string", "required": true }, { "name": "duration", "type": "number", "description": "days" }, { "name": "budget", "type": "number", "required": false }, { "name": "interests", "type": "array", "items": { "type": "string" } } ] }.

Prompts require explicit user invocation

Prompts are user-controlled and require explicit invocation rather than automatic triggering. They can be context-aware, referencing available resources and tools to create comprehensive workflows. Applications typically surface them via slash commands (typing "/" to see prompts like /plan-vacation), command palettes, dedicated UI buttons, or context menus.

Elicitation is the surviving client primitive

Elicitation lets servers request additional information from the user, useful for gathering extra input or asking for confirmation of an action. Servers request user input with the `elicitation/create` method, and elicitation requests are delivered through the Multi Round-Trip Requests (MRTR) pattern. A client advertises support by including "elicitation": {} in `io.modelcontextprotocol/clientCapabilities`.

Inspector Prompts tab previews generated messages

The Inspector Prompts tab lists prompt templates with their arguments and renders the generated messages for the arguments supplied — the fastest way to confirm a prompt produces the intended output.

Prompts capability declaration

Servers that support prompts MUST declare the prompts capability in DiscoverResult with a listChanged boolean field. The listChanged field indicates whether the server will emit notifications when the list of available prompts changes.

Prompts are user-controlled interactions

Prompts are designed to be user-controlled, meaning they are exposed from servers to clients with the intention of the user being able to explicitly select them for use. This refers to who decides when the prompt is used, not who authors its content. Prompt content is defined by the server.

prompts/list request and response structure

The prompts/list request supports pagination via an optional cursor parameter in params. The response returns resultType as 'complete', an array of prompt objects, an optional nextCursor for pagination, a ttlMs field for cache time-to-live in milliseconds, and a cacheScope field indicating cache visibility (public or private).

Prompt object fields

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

prompts/get request and response structure

The prompts/get request requires a name parameter and optional arguments object in params. The response returns resultType as 'complete', an optional description, and a messages array containing PromptMessage objects with role ('user' or 'assistant') and content fields.

Prompt message content types

PromptMessage content can be: text (type: 'text', requires text field), image (type: 'image', requires base64-encoded data field and mimeType), audio (type: 'audio', requires base64-encoded data field and mimeType), resource_link (type: 'resource_link', requires uri, optional name, optional description, optional mimeType), or embedded resource (type: 'resource', requires resource object with uri, mimeType, and either text or base64-encoded blob data).

Prompts list consistency rules

Servers that declare the prompts capability MUST respond to prompts/list requests with the set of prompts currently available. The 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, since credentials are per-request input, not connection state.

prompts/get multi-round-trip support

Servers MAY respond to prompts/get with an InputRequiredResult to indicate that additional input is needed before the prompt can be resolved. This follows the multi round-trip requests mechanism. When retrying the request, clients include inputResponses and, if provided by the server, requestState in the request parameters.

List changed notifications

When the list of available prompts changes, servers that declared the listChanged capability SHOULD send a notifications/prompts/list_changed notification to clients that have opened a subscriptions/listen stream with promptsListChanged: true.

Argument completion for prompts

Prompt arguments may be auto-completed through the completion API, allowing clients to request suggestions for argument values.

Prompt message annotations support

All content types in prompt messages support optional annotations for metadata about audience, priority, and modification times.

Completion capability declaration

Servers that support completions MUST declare the `completions` capability in their capabilities object as an empty object: `{"capabilities": {"completions": {}}}`.

completion/complete request structure

Clients send a `completion/complete` request with params containing: (1) `ref` - a PromptReference with `type: "ref/prompt"` and `name`, or ResourceTemplateReference with `type: "ref/resource"` and `uri`; (2) `argument` - an object with `name` (string) and `value` (string); (3) `context` - optional object containing `arguments` (mapping of already-resolved argument names to values).

completion/complete response structure

Server responds with `result` containing `resultType: "complete"` and `completion` object with: `values` (array of suggestions, max 100 items), `total` (optional total number of available matches), `hasMore` (boolean indicating if additional results exist).

Multi-argument completion context

For prompts or URI templates with multiple arguments, clients should include previously resolved arguments in the `context.arguments` object to provide context for subsequent completion requests. This allows servers to refine suggestions based on already-completed arguments.

Completion reference types

MCP supports two types of completion references: (1) `ref/prompt` - references a prompt by name, structured as `{"type": "ref/prompt", "name": "prompt_name"}`; (2) `ref/resource` - references a resource URI or URI template, structured as `{"type": "ref/resource", "uri": "uri_or_template"}`.

Completion results ranking and limits

Servers return completion values ranked by relevance, with a maximum of 100 items per response. The `total` field indicates the total number of available matches, and `hasMore` boolean indicates whether additional results exist beyond the current response.

Server-side completion implementation best practices

Servers SHOULD: return suggestions sorted by relevance, implement fuzzy matching where appropriate, rate limit completion requests, and validate all inputs.

Completion request example for single argument

Example completion request for a single argument: `{"jsonrpc": "2.0", "id": 1, "method": "completion/complete", "params": {"ref": {"type": "ref/prompt", "name": "code_review"}, "argument": {"name": "language", "value": "py"}}}`. Server responds with: `{"jsonrpc": "2.0", "id": 1, "result": {"resultType": "complete", "completion": {"values": ["python", "pytorch", "pyside"], "total": 10, "hasMore": true}}}`.

Completion request example with context arguments

Example completion request for a framework argument with language context: `{"jsonrpc": "2.0", "id": 1, "method": "completion/complete", "params": {"ref": {"type": "ref/prompt", "name": "code_review"}, "argument": {"name": "framework", "value": "fla"}, "context": {"arguments": {"language": "python"}}}}`. Server responds with: `{"jsonrpc": "2.0", "id": 1, "result": {"resultType": "complete", "completion": {"values": ["flask"], "total": 1, "hasMore": false}}}`.

Completion supports both prompts and resource templates

MCP completion feature provides autocompletion suggestions for arguments of prompts (identified by name) and resource templates (identified by URI). The protocol supports completing arguments for either type through the appropriate reference type in the request.

Server-to-client requests may only issue while processing client request

Server-initiated requests may now only be issued while the server is actively processing a client request (SEP-2260 in MCP 2026-07-28). A user is never prompted out of nowhere, and every elicitation traces back to something they or their agent started.

Give your agent this brain