Prompts

Prompts

The ModelContextProtocol::Server::Prompt base class allows subclasses to define a prompt that the MCP client can use.

Define the prompt properties and then implement the call method to build your prompt. Any arguments passed to the prompt from the MCP client will be available in the arguments hash with symbol keys (e.g., arguments[:argument_name]), and any context values provided in the server configuration will be available in the context hash. Use the respond_with instance method to ensure your prompt responds with appropriately formatted response data.

You can also send MCP log messages to clients from within your prompt by calling a valid logger level method on the client_logger and passing a string message. For server-side debugging and monitoring, use the server_logger to write logs that are not sent to clients.

Prompt Definition

Use the define block to set prompt properties and configure arguments.

Property	Description
name	The programmatic name of the prompt
title	Human-readable display name
description	Short description of what the prompt does
argument	Define an argument block with name, description, required flag, and completion

Argument Definition

Define any arguments using argument blocks nested within the define block. You can mark an argument as required, and you can optionally provide a completion class. See Completions for more information.

Property	Description
name	The name of the argument
description	A short description of the argument
required	Whether the argument is required (boolean)
completion	Available hints for completions (array or completion class)

Prompt Methods

Define your prompt properties and arguments, implement the call method using the message_history DSL to build prompt messages and respond_with to serialize them. You can wrap long running operations in a cancellable block to allow clients to cancel the request. Also, you can automatically send progress notifications to clients by wrapping long-running operations in a progressable block.

Method	Context	Description
define	Class definition	Block for defining prompt metadata and arguments
call	Instance method	Main method to implement prompt logic and build response
cancellable	Within call	Wrap long-running operations to allow client cancellation (e.g., cancellable { slow_operation })
progressable	Within call	Wrap long-running operations to send clients progress notifications (e.g., progressable { slow_operation })
message_history	Within call	DSL method to build an array of user and assistant messages
respond_with	Within call	Return properly formatted response data (e.g., respond_with messages:)

Message History DSL

Build a message history using the an intuitive DSL, creating an ordered history of user and assistant messages with flexible content blocks that can include text, image, audio, embedded resources, and resource links.

Method	Context	Description
user_message	Within message_history	Create a message with user role
assistant_message	Within message_history	Create a message with assistant role

Content Blocks

Use content blocks to properly format the content included in messages.

Method	Context	Description
text_content	Within message blocks	Create text content block
image_content	Within message blocks	Create image content block (requires data: and mime_type:)
audio_content	Within message blocks	Create audio content block (requires data: and mime_type:)
embedded_resource_content	Within message blocks	Create embedded resource content block (requires resource:)
resource_link	Within message blocks	Create resource link content block (requires name: and uri:)

Available Instance Variables

The arguments passed from an MCP client are available, as well as the context values passed in at server initialization.

Variable	Context	Description
arguments	Within call	Hash containing client-provided arguments (symbol keys)
context	Within call	Hash containing server configuration context values
client_logger	Within call	Client logger instance for sending MCP log messages (e.g., client_logger.info("message"))
server_logger	Within call	Server logger instance for debugging and monitoring (e.g., server_logger.debug("message"))

Example

This is an example prompt that returns a properly formatted response:

class TestPrompt < ModelContextProtocol::Server::Prompt
  define do
    # The name of the prompt for programmatic use
    name "brainstorm_excuses"
    # The human-readable prompt name for display in UI
    title "Brainstorm Excuses"
    # A short description of what the tool does
    description "A prompt for brainstorming excuses to get out of something"

    # Define arguments to be used with your prompt
    argument do
      # The name of the argument
      name "tone"
      # A short description of the argument
      description "The general tone to be used in the generated excuses"
      # If the argument is required
      required false
      # Available hints for completions
      completion ["whiny", "angry", "callous", "desperate", "nervous", "sneaky"]
    end

    argument do
      name "undesirable_activity"
      description "The thing to get out of"
      required true
    end
  end

  # You can optionally define a custom completion for an argument and pass it to completions.
  # ToneCompletion = ModelContextProtocol::Server::Completion.define do
  #   hints = ["whiny", "angry", "callous", "desperate", "nervous", "sneaky"]
  #   values = hints.grep(/#{argument_value}/)
  #   respond_with values:
  # end
  #   ...
  # define do
  #   argument do
  #     name "tone"
  #     description "The general tone to be used in the generated excuses"
  #     required false
  #     completion ToneCompletion
  #   end
  # end

  # The call method is invoked by the MCP Server to generate a response to resource/read requests
  def call
    # You can use the client_logger
    client_logger.info("Brainstorming excuses...")

    # Server logging for debugging and monitoring (not sent to client)
    server_logger.debug("Prompt called with arguments: #{arguments}")
    server_logger.info("Generating excuse brainstorming prompt")

    # Build an array of user and assistant messages
    messages = message_history do
      # Create a message with the user role
      user_message do
        # Use any type of content block in a message (text, image, audio, embedded_resource, or resource_link)
        text_content(text: "My wife wants me to: #{arguments[:undesirable_activity]}... Can you believe it?")
      end

      # You can also create messages with the assistant role
      assistant_message do
        text_content(text: "Oh, that's just downright awful. How can I help?")
      end

      user_message do
        # Reference any inputs from the client by accessing the appropriate key in the arguments hash
        text_content(text: "Can you generate some excuses for me?" + (arguments[:tone] ? " Make them as #{arguments[:tone]} as possible." : ""))
      end
    end

    # Respond with the messages
    respond_with messages:
  end
end