Prompts in MCP

A prompt in the Model Context Protocol (MCP) is a template of messages for a language model that a server offers and the user explicitly selects. The client discovers prompts with prompts/list, fills in their arguments and receives the finished messages with prompts/get. The host then adds these messages to the conversation with the model.

Prompts are one of the three server primitives, together with tools and resources. They have been part of the specification since its first version, 2024-11-05. The current version of the specification is 2026-07-28; the protocol is developed under the Agentic AI Foundation, part of the Linux Foundation. The basic concepts of MCP (host, client, server, primitives) are described in the article What is MCP.

Overview

The problem prompts solve

The author of a server knows best how its tools and data are meant to be used. The user of an AI application usually does not. Without a standard mechanism, a user writes the instructions for each task by hand, and the knowledge of how to use a server stays in its documentation.

Prompts move these instructions into the server. A server author publishes ready templates for typical tasks of the domain, for example a code review or a summary of meetings. The MCP documentation describes two purposes: parameterized prompts for a domain and a demonstration of how to use the server best.

Because prompts are part of the protocol, the same template works in every host that supports them. The host learns the list of prompts at runtime, shows it to the user and asks for the argument values. The server returns finished messages, so the host does not need to know how the template is built.

History

The table shows how prompts changed between versions of the specification.

How prompts work

Capability

A server that offers prompts declares the prompts capability in the result of server/discover. The optional listChanged flag says that the server sends notifications when its list of prompts changes.

{
  "capabilities": {
    "prompts": {
      "listChanged": true
    }
  }
}

A server that declares the capability must answer prompts/list with the prompts currently available to the requesting client. The list may be empty and may change over time. It must not depend on the connection or on other requests sent earlier. It may depend on the authorization of the request, for example on the scopes of the token, because credentials are part of each request. A client that calls prompts/list on a server without this capability gets the JSON-RPC error -32601 (Method not found).

Listing prompts

The client requests the list of prompts with prompts/list. As in every request of version 2026-07-28, the _meta field carries the protocol version, the identity of the client and its capabilities. The list supports pagination: if the result contains nextCursor, the client passes it as cursor in the next request.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "prompts/list",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": { "name": "example-client", "version": "1.0.0" },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

{
  "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 },
          { "name": "language", "description": "Programming language of the code" }
        ],
        "icons": [
          { "src": "https://example.com/review-icon.svg", "mimeType": "image/svg+xml", "sizes": ["any"] }
        ]
      }
    ],
    "ttlMs": 600000,
    "cacheScope": "public"
  }
}

Each prompt in the list is described by the following fields:

• name: the identifier of the prompt, unique within the server. The client uses it in prompts/get.
• title: an optional display name for the user interface. Without it, the host shows name.
• description: an optional description of what the prompt does.
• icons: optional icons for the user interface, each with a source URI and optional MIME type, sizes and theme.
• arguments: an optional list of arguments.
• _meta: optional metadata.

Arguments

A prompt argument is a named parameter that the user fills in before the server builds the messages. An argument has a name, an optional title, an optional description and an optional required flag. An argument without required: true is optional.

Prompt arguments have no JSON Schema. In prompts/get the client passes them as an arguments object, where every value is a string. Numbers, dates and lists are also passed as strings, and the server interprets them. Tools work differently: their parameters are described by a JSON Schema in inputSchema, as described in the article Tools in MCP.

The server should validate the arguments before it builds the prompt. A missing required argument and an unknown prompt name are returned as the JSON-RPC error -32602 (Invalid params).

Argument completion

Argument completion is a mechanism through which the server suggests values for an argument while the user is typing it. It is defined by a separate utility of the specification and works for prompt arguments and for parameters of resource templates. A server that supports it declares the completions capability.

The client sends completion/complete with a reference to the prompt (ref/prompt and the name of the prompt), the name of the argument and the value typed so far. When a prompt has several arguments, the client can pass the values already chosen in context.arguments, so that the server can narrow the suggestions. The examples below omit _meta for brevity, as the specification does on its own pages.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "completion/complete",
  "params": {
    "ref": { "type": "ref/prompt", "name": "code_review" },
    "argument": { "name": "language", "value": "py" }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resultType": "complete",
    "completion": {
      "values": ["python", "pytorch", "pyside"],
      "total": 10,
      "hasMore": true
    }
  }
}

The server returns at most 100 values, ranked by relevance. The optional total gives the number of all matches, and hasMore tells whether there are more values than the response contains. The specification recommends that servers sort suggestions by relevance and limit the rate of completion requests. Clients are expected to debounce rapid requests and to cache the results where appropriate.

Getting a prompt

When the user has selected a prompt and filled in the arguments, the client sends prompts/get with the name of the prompt and the values:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "prompts/get",
  "params": {
    "name": "code_review",
    "arguments": {
      "code": "def hello():\n    print('world')",
      "language": "python"
    },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": { "name": "example-client", "version": "1.0.0" },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "resultType": "complete",
    "description": "Code review prompt",
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "Please review this Python code:\ndef hello():\n    print('world')"
        }
      }
    ]
  }
}

The result contains an optional description and the messages array. On the Streamable HTTP transport the client also sends the name of the prompt in the Mcp-Name header, so that gateways can route the request without parsing the body. The headers are described in the article MCP transports.

Prompt messages and content types

A prompt message is one element of the messages array: a role and a single content block. The role is user or assistant. A prompt can therefore contain messages on behalf of the model as well as on behalf of the user.

The content of a message uses the same content types as tool results. The table lists them.

An embedded resource places the contents of a server resource directly in the message: documentation, a code sample, a configuration file. A resource link only names the resource by its URI, and the client decides whether to read it with resources/read. All content types support optional annotations, for example the intended audience and priority. A response with two messages, a text instruction and an embedded file, looks like this:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "resultType": "complete",
    "messages": [
      {
        "role": "user",
        "content": { "type": "text", "text": "Review the following file for correctness and style." }
      },
      {
        "role": "user",
        "content": {
          "type": "resource",
          "resource": {
            "uri": "file:///project/src/main.rs",
            "mimeType": "text/x-rust",
            "text": "fn main() {\n    println!(\"Hello\");\n}"
          }
        }
      }
    ]
  }
}

The specification defines the format of the messages. It does not define how exactly the host inserts them into the conversation with the model.

Prompts that need more input

Since 2026-07-28 a server can answer prompts/get with an InputRequiredResult instead of the messages. This is the Multi Round-Trip Requests (MRTR) mechanism: the server lists what it needs in inputRequests, for example a question to the user through elicitation. The client collects the answers and repeats prompts/get with inputResponses and, if the server provided it, the unchanged requestState. The mechanism is the same for tools, resources and prompts and is described in the article Stateless MCP.

Errors

The specification recommends standard JSON-RPC errors for prompts:

Who invokes a prompt

Prompts are user-controlled: the server exposes them so that the user selects them explicitly. The specification states that this describes who decides when the prompt is used, not who writes its content. The content is defined by the server.

The specification names slash commands as a typical example: the user types / and sees the available prompts. The MCP documentation lists other patterns: a command palette with search, dedicated buttons for frequent prompts and context menus. The protocol does not prescribe any particular user interface.

In Visual Studio Code, according to its documentation, a prompt of a server is used by typing /<server>.<prompt> in the chat. The general sequence in a host looks like this:

1. The host requests prompts/list from the connected servers and shows the prompts to the user.
2. The user selects a prompt. The host asks for the values of its arguments and can use completion/complete for suggestions.
3. The host sends prompts/get and receives the messages.
4. The host adds the messages to the conversation, and the model answers them. While answering, the model can call the tools of the same or other servers.

This differs from tools, which the model selects itself, and from resources, which the application attaches to the context.

List changes and caching

Change notifications

A server that declared listChanged: true should notify clients when its list of prompts changes. Since 2026-07-28 notifications come only to clients that asked for them. The client opens a long-lived stream with subscriptions/listen and sets promptsListChanged: true in the filter:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "subscriptions/listen",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": { "name": "example-client", "version": "1.0.0" },
      "io.modelcontextprotocol/clientCapabilities": {}
    },
    "notifications": { "promptsListChanged": true }
  }
}

The server first confirms the subscription with notifications/subscriptions/acknowledged. After that, each change of the list arrives as a notification with the identifier of the subscription, which equals the id of the subscriptions/listen request:

{
  "jsonrpc": "2.0",
  "method": "notifications/prompts/list_changed",
  "params": {
    "_meta": { "io.modelcontextprotocol/subscriptionId": 5 }
  }
}

The notification carries no data about the change. The client requests prompts/list again.

Caching hints

Since 2026-07-28 the result of prompts/list must contain two caching hints:

• ttlMs: how many milliseconds the client may consider the result fresh. The value is a hint, not a guarantee that the list stays the same.
• cacheScope: who may reuse the result. public means the result has no user-specific data, and shared gateways and proxies may serve it to any user. private means it may be reused only within the same authorization context.

The specification names public as the appropriate value for a list of prompts that is the same for all users. A list filtered by the permissions of the user is private. A change notification invalidates a cached list even if its ttlMs has not expired. Each page of a paginated list is cached separately, and all pages of one list must have the same cacheScope.

Typical scenarios

The specification and the MCP documentation give the following kinds of prompts:

• Task templates for a domain. Examples from the documentation are a code review, planning a vacation, a summary of meetings and a draft of an email.
• Demonstration of the server. A prompt shows how the server is meant to be used, so the user does not need to learn its tools first.
• Prompts with context. A prompt embeds a resource or links to it, for example the file to review or the documentation of an API.
• Workflows. A prompt instructs the model to combine resources and tools. In the documentation, after the "Plan a vacation" prompt the model reads the calendar and travel history that the user attached and then calls tools to search flights and book a hotel.

Security

The specification requires implementations to validate all prompt inputs and outputs to prevent injection attacks and unauthorized access to resources. The text of a prompt comes from the server and goes into the context of the model, usually as messages with the role user. A prompt from an untrusted server is therefore a channel for prompt injection: instructions that the user did not write and may not see. The attack and its testing are described in the article Prompt injection.

Argument completion has its own requirements. Implementations must validate completion inputs, limit the rate of requests and control access to sensitive suggestions, so that completion does not disclose data. The general risks of MCP are described in the article MCP security.

Prompts, tools and resources

The three server primitives differ in who decides to use them and what they return. The table compares them.

A prompt does not perform an action and does not supply data on its own. It prepares the conversation: it gives the model instructions, embeds resources and can direct the model to the tools it should use. Tools are the means to act, and resources are the means to read data. They are described in the articles Tools in MCP and Resources and resource templates.

The three primitives are used together. In the example of the MCP documentation, the user invokes a prompt, attaches resources and the model then calls tools of several servers. The prompt sets the task, the resources give the context and the tools perform the actions.

Agent skills are also instructions for a model, but in MCP they are not built on prompts. The official Skills extension (io.modelcontextprotocol/skills) serves skills through the resources primitive and adds the skills/list and skills/get methods. Unlike a prompt, a skill can be selected by the model or by the user. Extensions are described in the article MCP extensions.

Terms

Sources

• Prompts, specification 2026-07-28(opens in a new tab)
• Completion, specification 2026-07-28(opens in a new tab)
• Caching, specification 2026-07-28(opens in a new tab)
• Subscriptions, specification 2026-07-28(opens in a new tab)
• Server features overview, specification 2026-07-28(opens in a new tab)
• Key changes in 2026-07-28(opens in a new tab)
• MCP schema 2026-07-28 (schema.ts)(opens in a new tab)
• Understanding MCP servers, MCP documentation(opens in a new tab)
• Skills extension overview(opens in a new tab)
• Add MCP servers in VS Code, Visual Studio Code documentation(opens in a new tab)