Working with Prompts

Power of Prompts

Prompts let you create reusable templates for AI interactions, making your MCP server more consistent and powerful!

What are Prompts?

Prompts are reusable templates that:

Define conversation flows
Provide structured context
Use dynamic data
Ensure consistent AI responses

Here's a simple example:

import { MCPPrompt } from "mcp-framework";
import { z } from "zod";

interface GreetingPromptInput {
  userName: string;
  timeOfDay: string;
}

class GreetingPrompt extends MCPPrompt<GreetingPromptInput> {
  name = "greeting";
  description = "Generates a personalized greeting";

  schema = {
    userName: {
      type: z.string(),
      description: "User's name",
      required: true,
    },
    timeOfDay: {
      type: z.enum(["morning", "afternoon", "evening"]),
      description: "Time of day",
      required: true,
    },
  };

  async generateMessages({ userName, timeOfDay }) {
    return [
      {
        role: "user",
        content: {
          type: "text",
          text: `Good ${timeOfDay} ${userName}! How can I assist you today?`,
        },
      },
    ];
  }
}

Title and Icons

Prompts now support display metadata per MCP spec 2025-11-25, allowing clients to render richer UIs such as prompt pickers and menus.

import { MCPPrompt } from "mcp-framework";
import { z } from "zod";

class ReportPrompt extends MCPPrompt<{ topic: string }> {
  name = "generate_report";
  title = "Report Generator";  // Human-readable display name
  description = "Generate a report on a given topic";
  icons = [{ src: "https://example.com/report-icon.png", mimeType: "image/png" }];

  schema = {
    topic: {
      type: z.string(),
      description: "Topic to generate a report about",
      required: true,
    },
  };

  async generateMessages(args: { topic: string }) {
    return [{
      role: "user",
      content: { type: "text", text: `Generate a detailed report about: ${args.topic}` }
    }];
  }
}

Field Reference

title — Optional human-readable name for display in client UIs (e.g., prompt picker dialogs). Falls back to name if not set.
icons — Optional array of icon objects for client UI rendering. Each object has src (URL or data URI), optional mimeType, and optional sizes.

Display Only

Both title and icons are purely for display purposes. They do not affect prompt behavior or message generation.

Creating Prompts

Using the CLI

mcp add prompt my-prompt

This creates a new prompt in src/prompts/MyPrompt.ts.

Prompt Structure

Every prompt has:

Metadata

name = "data-analysis";
description = "Analyzes data with specific parameters";

Input Schema

schema = {
  dataset: {
    type: z.string(),
    description: "Dataset to analyze",
    required: true,
  },
  metrics: {
    type: z.array(z.string()),
    description: "Metrics to calculate",
    required: true,
  },
};

Message Generation

async generateMessages(input) {
  return [{
    role: "user",
    content: {
      type: "text",
      text: `Analyze ${input.dataset} for ${input.metrics.join(", ")}`
    }
  }];
}

Advanced Features

Using Resources in Prompts

class DataAnalysisPrompt extends MCPPrompt {
  async generateMessages({ datasetId }) {
    const dataResource = new DatasetResource(datasetId);
    const [data] = await dataResource.read();

    return [
      {
        role: "user",
        content: {
          type: "text",
          text: "Please analyze this dataset:",
          resource: {
            uri: data.uri,
            text: data.text,
            mimeType: data.mimeType,
          },
        },
      },
    ];
  }
}

Multi-step Prompts

class ReportPrompt extends MCPPrompt {
  async generateMessages({ reportType }) {
    return [
      {
        role: "system",
        content: {
          type: "text",
          text: "You are a professional report writer.",
        },
      },
      {
        role: "user",
        content: {
          type: "text",
          text: `Create a ${reportType} report using the following data:`,
        },
      },
    ];
  }
}

Best Practices

Pro Tips

Follow these practices for better prompt design!

Clear Naming

name = "financial-analysis"; // Good
name = "fa"; // Bad

Detailed Descriptions

description =
  "Analyzes financial data and provides insights with specific metrics";

Input Validation

schema = {
  email: {
    type: z.string().email(),
    description: "Valid email address",
    required: true,
  },
};

Structured Messages

async generateMessages(input) {
  return [
    {
      role: "system",
      content: {
        type: "text",
        text: "Context setting message"
      }
    },
    {
      role: "user",
      content: {
        type: "text",
        text: "Main instruction"
      }
    }
  ];
}

Examples

Report Generator

class ReportGeneratorPrompt extends MCPPrompt {
  name = "report-generator";
  description = "Generates formatted reports from data";

  schema = {
    data: {
      type: z.object({
        title: z.string(),
        sections: z.array(z.string()),
      }),
      description: "Report data structure",
    },
    format: {
      type: z.enum(["short", "detailed"]),
      description: "Report format",
    },
  };

  async generateMessages({ data, format }) {
    return [
      {
        role: "user",
        content: {
          type: "text",
          text: `Generate a ${format} report titled "${
            data.title
          }" with the following sections: ${data.sections.join(", ")}`,
        },
      },
    ];
  }
}

Next Steps

Learn about Tools
Learn about Resources
Get Started

Prompts Overview