mcp-use__mcp-use/docs/python/client/prompts.mdx

---
title: "Prompts"
description: "How to use prompts from the client"
icon: "volume-2"
---

Prompts in MCP are reusable templates for structured interactions between AI models and servers. They provide predefined interaction patterns with parameters, enabling consistent and efficient communication for common use cases.

## What are Prompts?

Prompts are interaction templates with:
- **User-controlled invocation** requiring explicit activation
- **Parameter definitions** for customizable inputs
- **Structured formats** for consistent interactions
- **Context-aware content** that can adapt to different scenarios

Common examples include:
- Task planning templates ("Plan a vacation")
- Code review workflows ("Review this pull request")
- Content generation patterns ("Write a blog post about...")
- Analysis frameworks ("Analyze market trends for...")
- Decision support templates ("Compare options for...")

## Characteristics of Prompts

### User Control
Prompts are never invoked automatically - they require explicit user activation, ensuring transparency and control over AI interactions.

### Parameter Support
Prompts can accept parameters to customize their behavior and adapt to specific contexts.

### Reusability
Well-designed prompts can be reused across different contexts and conversations.

## Listing Available Prompts

To see what prompts are available from a connected MCP server:

<CodeGroup>
```python Python
import asyncio
from mcp_use import MCPClient

async def list_prompts():
    # Initialize client with server configuration
    config = {
        "mcpServers": {
            # Your server definitions here
        }
    }
    client = MCPClient(config)

    # Connect to servers
    await client.create_all_sessions()

    # Get a session for a specific server
    session = client.get_session("my_server")

    # List all available prompts - always returns fresh data
    prompts = await session.list_prompts()

    for prompt in prompts:
        print(f"Prompt: {prompt.name}")
        print(f"Description: {prompt.description}")
        if prompt.arguments:
            print("Arguments:")
            for arg in prompt.arguments:
                print(f"  - {arg.name}: {arg.description}")
        print("---")

# Run the example
asyncio.run(list_prompts())
```
</CodeGroup>

### Automatic Prompt List Update

When servers send `PromptListChangedNotification`, it signals that the prompt list has changed. The `list_prompts()` method always fetches fresh data from the server, ensuring you get up-to-date information.

```mermaid
sequenceDiagram
    participant Client
    participant Server

    Note over Server: Server Changes State
    Server->>Server: disable(prompt)
    Server->>Client: PromptListChangedNotification
    Client->>Client: Log notification

    Note over Client: User Calls list_prompts()
    Client->>Server: list_prompts()
    Server-->>Client: [updated prompts]
    Client->>Client: Return fresh data
```

**Important:** Always use `await session.list_prompts()` instead of the deprecated `session.prompts` property to ensure you get fresh data:

<CodeGroup>
```python Python
# ✅ Recommended - always returns fresh data
prompts = await session.list_prompts()

# ⚠️ Deprecated - may return stale data
# prompts = session.prompts
```
</CodeGroup>

## Getting and Using Prompts

Prompts are retrieved using the `get_prompt` method:

<CodeGroup>
```python Python
import asyncio
from mcp_use import MCPClient

async def use_prompt_example():
    config = {
        "mcpServers": {
            # Your server definitions here
        }
    }
    client = MCPClient(config)
    await client.create_all_sessions()

    session = client.get_session("planning_server")

    # Get a prompt with arguments
    result = await session.get_prompt(
        name="plan_vacation",
        arguments={
            "destination": "Japan",
            "duration": "2 weeks",
            "budget": "$5000",
            "interests": ["culture", "food", "nature"]
        }
    )

    # Use the prompt content
    print(f"Prompt description: {result.description}")
    for message in result.messages:
        print(f"Role: {message.role}")
        print(f"Content: {message.content.text}")

asyncio.run(use_prompt_example())
```
</CodeGroup>

## Prompt Without Arguments

Some prompts don't require parameters:

<CodeGroup>
```python Python
async def simple_prompt_example():
    config = {
        "mcpServers": {
            # Your server definitions here
        }
    }
    client = MCPClient(config)
    await client.create_all_sessions()

    session = client.get_session("content_server")

    # Get a prompt without arguments
    result = await session.get_prompt(name="writing_tips")

    # Display the prompt content
    for message in result.messages:
        print(f"{message.role}: {message.content.text}")

asyncio.run(simple_prompt_example())
```
</CodeGroup>

## Prompt Structure

Prompts return structured content with messages:

<CodeGroup>
```python Python
# Example of working with prompt results
result = await session.get_prompt("code_review", {"language": "python"})

for message in result.messages:
    # Messages have roles (e.g., "user", "assistant", "system")
    role = message.role

    # Content can be text or other formats
    if hasattr(message.content, 'text'):
        text_content = message.content.text
        print(f"{role}: {text_content}")

    # Handle other content types if needed
    if hasattr(message.content, 'image'):
        print(f"{role}: [Image content]")
```
</CodeGroup>

## Parameter Completion

Many prompts support parameter completion to help users understand required inputs:

<CodeGroup>
```python Python
async def explore_prompt_parameters():
    session = client.get_session("my_server")
    prompts = await session.list_prompts()

    for prompt in prompts:
        print(f"Prompt: {prompt.name}")
        if prompt.arguments:
            print("Required parameters:")
            for arg in prompt.arguments:
                required = "required" if arg.required else "optional"
                print(f"  - {arg.name} ({required}): {arg.description}")
        print()
```
</CodeGroup>

## Dynamic Prompt Generation

Some prompts can generate different content based on context:

<CodeGroup>
```python Python
async def dynamic_prompt_example():
    config = {
        "mcpServers": {
            # Your server definitions here
        }
    }
    client = MCPClient(config)
    await client.create_all_sessions()

    session = client.get_session("adaptive_server")

    # Same prompt with different parameters
    contexts = [
        {"domain": "healthcare", "complexity": "beginner"},
        {"domain": "finance", "complexity": "expert"}
    ]

    for context in contexts:
        result = await session.get_prompt("domain_analysis", context)
        print(f"Analysis for {context['domain']}:")
        for message in result.messages:
            print(f"  {message.content.text[:100]}...")
        print()
```
</CodeGroup>

## Error Handling

Handle potential errors when working with prompts:

<CodeGroup>
```python Python
try:
    result = await session.get_prompt("missing_prompt", {"param": "value"})
    for message in result.messages:
        print(message.content.text)
except Exception as e:
    print(f"Failed to get prompt: {e}")

# Check if prompt exists before using
available_prompts = await session.list_prompts()
prompt_names = [p.name for p in available_prompts]

if "my_prompt" in prompt_names:
    result = await session.get_prompt("my_prompt")
else:
    print("Prompt not available")
```
</CodeGroup>