プロンプト

プロンプトは、ユーザーが選ぶメッセージテンプレートです。

ツールはモデルのためのものです。プロンプトはその逆です。ユーザーがクライアントのメニュー（スラッシュコマンドやボタン）から 1 つを選んで引数を入力すると、レンダリングされたメッセージが、ユーザー自身が入力したかのように会話に入ります。

プロンプトを宣言するには、テキストを返す関数に @mcp.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}"

SDK が読み取るのは、ツールの場合と同じ 3 つです。

• 名前は関数名、つまり review_code です。
• クライアントが表示する説明は docstring、つまり Review a piece of code. です。
• 引数はパラメーターから決まります。code にはデフォルト値がないので必須です。

クライアントが prompts/list で受け取るのは次のとおりです。

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

ここには JSON Schema がありません。プロンプトの引数は、名前付きの文字列値が並んだフラットなリストです。モデルが組み立てるペイロードではなく、人が記入するフォームです。

レンダリングする

クライアントは prompts/get に引数を渡してテンプレートをレンダリングします。関数が実行され、返した str が 1 つのユーザーメッセージになります。

{
  "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"
}

プロンプトの一生はこれがすべてです。名前で一覧に載り、必要なときにレンダリングされ、チャットに差し込まれます。

mcp.shared.exceptions.MCPError: Internal server error

試してみる

MCP Inspector でサーバーを実行してください。

uv run mcp dev server.py

Prompts タブを開いて review_code を選択してください。Inspector は、必須の code フィールドが 1 つあるフォームを表示します。入力してレンダリングすると、上のユーザーメッセージがそのまま返ってきます。

複数のメッセージ

コードレビューは 1 つのメッセージです。デバッグセッションは会話であり、プロンプトはその会話全体の出発点を用意できます。

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 と AssistantMessage は mcp.server.mcpserver.prompts.base にあります。str を渡すと、TextContent にラップしてくれます。ロールはクラス名で決まります。
• Message は両者に共通の基底クラスです。戻り値のアノテーションにはこれを使ってください。

debug_error をレンダリングすると、3 つのメッセージがこの順番で生成されるようになります。

{
  "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"
}

最後のメッセージに注目してください。assistant のターンをあらかじめ埋めておくのは、誘導の文言をユーザー自身に入力させることなく、モデルの「次の」返答を方向づけるための方法です。

タイトルと引数の説明

review_code は関数名であって、ラベルではありません。ボタンに載せるのにもっとふさわしいものをクライアントに渡し、フォームを見ただけで意味がわかるように各引数に説明を付けます。

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" は人が読むための名前で、ツールの title とまったく同じです。
• Annotated[str, Field(description=...)] は、ツール でツールのパラメーターを説明するのに使うのと同じパターンです。ここでは、説明はスキーマの中ではなく引数に付きます。
• language にはデフォルト値があるので、必須ではなくなります。

これで prompts/list のエントリには、クライアントがよいフォームを描くのに必要なものがすべてそろいます。

{
  "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}
  ]
}

まとめ

• 関数に @mcp.prompt() を付けるとプロンプトになります。名前は関数から、説明は docstring から取られます。
• プロンプトはユーザーが制御するものです。クライアントが一覧を出し、ユーザーが 1 つ選んで引数を入力します。
• 引数は名前付き文字列のフラットなリストです（スキーマなし）。デフォルト値のあるパラメーターは省略可能です。
• str を返すと 1 つのユーザーメッセージになります。UserMessage / AssistantMessage のリストを返すと、複数ターンの会話の出発点を用意できます。
• title= と Field(description=...) は、クライアントが UI に表示するものです。
• 必須の引数が欠けていると、リクエスト全体が失敗します。プロンプト単位のエラー結果はありません。

プロンプト（やリソーステンプレート）の引数をサーバー側でオートコンプリートする機能については、補完 を参照してください。