Skip to main content

​
Prompts

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: 
import { MCPClient } from 'mcp-use'

async function listPrompts() {
    // Initialize client with server configuration
    const config = {
        mcpServers: {
            // Your server definitions here
        }
    }
    const client = new MCPClient(config)

    // Connect to servers
    await client.createAllSessions()

    // Get a session for a specific server
    const session = client.getSession('my_server')

    // List all available prompts - always returns fresh data
    const prompts = await session.listPrompts()

    for (const prompt of prompts) {
        console.log(`Prompt: ${prompt.name}`)
        console.log(`Description: ${prompt.description}`)
        if (prompt.arguments) {
            console.log('Arguments:')
            for (const arg of prompt.arguments) {
                console.log(`  - ${arg.name}: ${arg.description}`)
            }
        }
        console.log('---')
    }

    await client.closeAllSessions()
}

// Run the example
listPrompts().catch(console.error)

​
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. Important: Always use await session.list_prompts() instead of the deprecated session.prompts property to ensure you get fresh data: 
// ✅ Recommended - always returns fresh data
const prompts = await session.listPrompts()

// ⚠️ Deprecated - may return stale data
// const prompts = session.prompts

​
Getting and Using Prompts

Prompts are retrieved using the get_prompt method: 
import { MCPClient } from 'mcp-use'

async function usePromptExample() {
    const config = {
        mcpServers: {
            // Your server definitions here
        }
    }
    const client = new MCPClient(config)
    await client.createAllSessions()

    const session = client.getSession('planning_server')

    // Get a prompt with arguments
    const result = await session.getPrompt(
        'plan_vacation',
        {
            destination: 'Japan',
            duration: '2 weeks',
            budget: '$5000',
            interests: ['culture', 'food', 'nature']
        }
    )

    // Use the prompt content
    console.log(`Prompt description: ${result.description}`)
    for (const message of result.messages) {
        console.log(`Role: ${message.role}`)
        console.log(`Content: ${message.content.text}`)
    }

    await client.closeAllSessions()
}

usePromptExample().catch(console.error)

​
Prompt Without Arguments

Some prompts don’t require parameters: 
async function simplePromptExample() {
    const config = {
        mcpServers: {
            // Your server definitions here
        }
    }
    const client = new MCPClient(config)
    await client.createAllSessions()

    const session = client.getSession('content_server')

    // Get a prompt without arguments
    const result = await session.getPrompt('writing_tips')

    // Display the prompt content
    for (const message of result.messages) {
        console.log(`${message.role}: ${message.content.text}`)
    }

    await client.closeAllSessions()
}

simplePromptExample().catch(console.error)

​
Prompt Structure

Prompts return structured content with messages: 
// Example of working with prompt results
const result = await session.getPrompt('code_review', { language: 'python' })

for (const message of result.messages) {
    // Messages have roles (e.g., "user", "assistant", "system")
    const role = message.role

    // Content can be text or other formats
    if ('text' in message.content) {
        const textContent = message.content.text
        console.log(`${role}: ${textContent}`)
    }

    // Handle other content types if needed
    if ('image' in message.content) {
        console.log(`${role}: [Image content]`)
    }
}

​
Parameter Completion

Many prompts support parameter completion to help users understand required inputs: 
async function explorePromptParameters() {
    const session = client.getSession('my_server')
    const prompts = await session.listPrompts()

    for (const prompt of prompts) {
        console.log(`Prompt: ${prompt.name}`)
        if (prompt.arguments) {
            console.log('Required parameters:')
            for (const arg of prompt.arguments) {
                const required = arg.required ? 'required' : 'optional'
                console.log(`  - ${arg.name} (${required}): ${arg.description}`)
            }
        }
        console.log()
    }
}

​
Dynamic Prompt Generation

Some prompts can generate different content based on context: 
async function dynamicPromptExample() {
    const config = {
        mcpServers: {
            // Your server definitions here
        }
    }
    const client = new MCPClient(config)
    await client.createAllSessions()

    const session = client.getSession('adaptive_server')

    // Same prompt with different parameters
    const contexts = [
        { domain: 'healthcare', complexity: 'beginner' },
        { domain: 'finance', complexity: 'expert' }
    ]

    for (const context of contexts) {
        const result = await session.getPrompt('domain_analysis', context)
        console.log(`Analysis for ${context.domain}:`)
        for (const message of result.messages) {
            console.log(`  ${message.content.text.substring(0, 100)}...`)
        }
        console.log()
    }

    await client.closeAllSessions()
}

​
Error Handling

Handle potential errors when working with prompts: 
try {
    const result = await session.getPrompt('missing_prompt', { param: 'value' })
    for (const message of result.messages) {
        console.log(message.content.text)
    }
} catch (error) {
    console.error(`Failed to get prompt: ${error}`)
}

// Check if prompt exists before using
const availablePrompts = await session.listPrompts()
const promptNames = availablePrompts.map(p => p.name)

if (promptNames.includes('my_prompt')) {
    const result = await session.getPrompt('my_prompt')
} else {
    console.log('Prompt not available')
}