What are MCP Prompts?

MCP Prompts are reusable, structured message templates exposed by MCP servers to guide interactions with agents. Unlike tools (which execute logic) or resources (which provide read-only data), prompts return a predefined list of messages meant to initiate consistent model behavior.

Prompts are declarative, composable, and designed for user-initiated workflows, such as:

• Slash commands or quick actions triggered via UI
• Task-specific interactions, like summarization or code explanation

You can use prompts when you want to define how users engage with the model but not to perform logic or to serve contextual data.

Prompt structure

A prompt is a named, parameterized template. It defines:

• A name (a unique identifier)
• An optional description
• An optional list of structured arguments

{
  "name": "summarize-errors",
  "description": "Summarize recent error logs",
  "arguments": [
    {
      "name": "logUri",
      "description": "URI of the log resource",
      "required": true
    }
  ]
}

The server exposes prompts via prompts/list and provides message content on prompts/get.

Discovering prompts

Clients use prompts/list to fetch available prompt definitions:

{
  "method": "prompts/list"
}

The response includes a list of prompts:

{
  "prompts": [
    {
      "name": "explain-code",
      "description": "Explain how a function works",
      "arguments": [
        { "name": "code", "required": true }
      ]
    }
  ]
}

Using prompts

To use a prompt, clients call prompts/get with a prompt name and arguments:

{
  "method": "prompts/get",
  "params": {
    "name": "explain-code",
    "arguments": {
      "code": "def hello(): print('hi')"
    }
  }
}

The server responds with a messages[] array, ready to send to the model:

{
  "description": "Explain how a function works",
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "Explain this Python code:\n\ndef hello(): print('hi')"
      }
    }
  ]
}

Defining and serving prompts in Python

The following example defines a simple MCP prompt called git-commit that helps users generate commit messages from change descriptions.

from mcp.server import Server, stdio
import mcp.types as types

import asyncio

app = Server("git-prompts-server")

@app.list_prompts()
async def list_prompts() -> list[types.Prompt]:
    return [
        types.Prompt(
            name="git-commit",
            description="Generate a Git commit message from a code diff or change summary",
            arguments=[
                types.PromptArgument(
                    name="changes",
                    description="Code diff or explanation of the changes made",
                    required=True
                )
            ]
        )
    ]

@app.get_prompt()
async def get_prompt(name: str, arguments: dict[str, str]) -> types.GetPromptResult:
    if name != "git-commit":
        raise ValueError("Unknown prompt")

    changes = arguments.get("changes", "")

    return types.GetPromptResult(
        messages=[
            types.PromptMessage(
                role="user",
                content=types.TextContent(
                    type="text",
                    text=(
                        "Generate a Git commit message summarizing these changes:\n\n"
                        f"{changes}"
                    )
                )
            )
        ]
    )

In this example, we:

• Register a static prompt named git-commit with a human-readable description and a required changes argument.
• Expose metadata via @list_prompts so UIs and clients can discover the prompt.
• Implement prompt generation via @get_prompt, which creates a single message that asks the agent to produce a commit message based on input.
• Avoid side effects, as the server does not evaluate or format the response but it does structure a message.

Best practices and pitfalls to avoid

Here are some best practices for implementing MCP Prompts:

• Use clear, actionable names (for example, summarize-errors, not get-summarized-error-log-output).
• Validate all required arguments up front.
• Keep prompts deterministic and stateless (using the same input should produce the same output).
• Embed resources directly, if needed, for model context.
• Provide concise descriptions to improve UI discoverability.

When implementing MCP Prompts, avoid the following common mistakes:

• Allowing missing or malformed arguments
• Using vague or overly long prompt names
• Passing oversized inputs (such as full files or large diffs)
• Failing to sanitize non-UTF-8 or injection-prone strings

Prompts vs Tools vs Resources

The table below compares the three core primitives in MCP: