Prompts

Um prompt é um template de mensagem que o usuário escolhe.

Ferramentas são para o modelo. Um prompt é o oposto: o usuário escolhe um em um menu do seu cliente (um comando de barra, um botão), preenche os argumentos, e as mensagens renderizadas entram na conversa como se ele mesmo as tivesse digitado.

Para declarar um, coloque @mcp.prompt() em uma função que retorna o texto.

Seu primeiro prompt

from mcp.server import MCPServer

mcp = MCPServer("Code Helper")


@mcp.prompt()
def review_code(code: str) -> str:
    """Review a piece of code."""
    return f"Please review this code:\n\n{code}"

O SDK lê as mesmas três coisas que lê de uma ferramenta:

• O nome é o nome da função: review_code.
• A descrição que o cliente exibe é a docstring: Review a piece of code.
• Os argumentos vêm dos parâmetros. code não tem valor padrão, então é obrigatório.

É isso que um cliente recebe de volta de prompts/list:

{
  "name": "review_code",
  "description": "Review a piece of code.",
  "arguments": [
    {"name": "code", "required": true}
  ]
}

Não há JSON Schema aqui. Os argumentos de um prompt são uma lista plana de strings nomeadas: um formulário que uma pessoa preenche, não um payload que um modelo constrói.

Renderizando

O cliente renderiza o template com prompts/get, passando os argumentos. Sua função executa e a str que você retorna vira uma mensagem de usuário:

{
  "description": "Review a piece of code.",
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "Please review this code:\n\ndef add(a, b): return a + b"
      }
    }
  ],
  "resultType": "complete"
}

Essa é a vida inteira de um prompt: listado pelo nome, renderizado sob demanda, colocado no chat.

mcp.shared.exceptions.MCPError: Internal server error

Experimente

Execute o servidor com o MCP Inspector:

uv run mcp dev server.py

Abra a aba Prompts e selecione review_code. O Inspector desenha um formulário com um único campo obrigatório, code. Preencha, renderize e você recebe de volta exatamente a mensagem de usuário acima.

Mais de uma mensagem

Uma revisão de código é uma mensagem só. Uma sessão de depuração é uma conversa, e um prompt pode iniciar a coisa toda.

Retorne uma lista de mensagens em vez de uma str:

from mcp.server import MCPServer
from mcp.server.mcpserver.prompts.base import AssistantMessage, Message, UserMessage

mcp = MCPServer("Code Helper")


@mcp.prompt()
def review_code(code: str) -> str:
    """Review a piece of code."""
    return f"Please review this code:\n\n{code}"


@mcp.prompt()
def debug_error(error: str) -> list[Message]:
    """Start a debugging conversation."""
    return [
        UserMessage("I'm seeing this error:"),
        UserMessage(error),
        AssistantMessage("I'll help debug that. What have you tried so far?"),
    ]

• UserMessage e AssistantMessage vêm de mcp.server.mcpserver.prompts.base. Passe uma str para elas e elas a embrulham em TextContent para você. O papel (role) é o nome da classe.
• Message é a base comum delas. Use-a como anotação de retorno.

Renderizar debug_error agora produz três mensagens, nesta ordem:

{
  "description": "Start a debugging conversation.",
  "messages": [
    {"role": "user", "content": {"type": "text", "text": "I'm seeing this error:"}},
    {"role": "user", "content": {"type": "text", "text": "TypeError: 'int' object is not iterable"}},
    {
      "role": "assistant",
      "content": {"type": "text", "text": "I'll help debug that. What have you tried so far?"}
    }
  ],
  "resultType": "complete"
}

Repare na última. Pré-preencher um turno de assistant é como você direciona a próxima resposta do modelo sem fazer o usuário digitar esse direcionamento por conta própria.

Títulos e descrições dos argumentos

review_code é um nome de função, não um rótulo. Dê ao cliente algo melhor para colocar no botão e descreva cada argumento para que o formulário se explique sozinho:

from typing import Annotated

from pydantic import Field

from mcp.server import MCPServer

mcp = MCPServer("Code Helper")


@mcp.prompt(title="Code review")
def review_code(
    code: Annotated[str, Field(description="The code to review.")],
    language: Annotated[str, Field(description="The language the code is written in.")] = "python",
) -> str:
    """Review a piece of code."""
    return f"Please review this {language} code:\n\n{code}"

• title="Code review" é o nome legível por humanos, exatamente como o title de uma ferramenta.
• Annotated[str, Field(description=...)] é o mesmo padrão que Ferramentas usa para descrever os parâmetros de uma ferramenta. Aqui a descrição vai parar no argumento, e não em um schema.
• language tem um valor padrão, então deixa de ser obrigatório.

A entrada em prompts/list agora traz tudo de que um cliente precisa para desenhar um bom formulário:

{
  "name": "review_code",
  "title": "Code review",
  "description": "Review a piece of code.",
  "arguments": [
    {"name": "code", "description": "The code to review.", "required": true},
    {"name": "language", "description": "The language the code is written in.", "required": false}
  ]
}

Recapitulando

• @mcp.prompt() em uma função faz dela um prompt. O nome vem da função, a descrição vem da docstring.
• Prompts são controlados pelo usuário: o cliente os lista, o usuário escolhe um e preenche os argumentos.
• Os argumentos são uma lista plana de strings nomeadas (sem schema). Um parâmetro com valor padrão é opcional.
• Retorne uma str e ela vira uma mensagem de usuário. Retorne uma lista de UserMessage / AssistantMessage para iniciar uma conversa de vários turnos.
• title= e Field(description=...) são o que um cliente coloca na interface dele.
• Um argumento obrigatório ausente faz a requisição inteira falhar. Não existe um resultado de erro por prompt.

O autocomplete do lado do servidor para os argumentos de um prompt (ou de um template de recurso) é assunto de Completions.