Prompts

Define Block Properties

Argument Properties

Available Instance Variables

Message History DSL

Build message histories using message_history with user_message and assistant_message blocks:

def call
  messages = message_history do
    user_message do
      text_content(text: "User message here")
    end

    assistant_message do
      text_content(text: "Assistant response here")
    end
  end

  respond_with messages: messages
end

Content Types in Messages

Each message block returns a single content object:

message_history do
  user_message do
    text_content(text: "Text message")
  end

  user_message do
    image_content(data: base64_data, mime_type: "image/png")
  end

  user_message do
    audio_content(data: base64_data, mime_type: "audio/mp3")
  end

  user_message do
    embedded_resource_content(resource: resource_data)
  end

  user_message do
    resource_link(name: "file.txt", uri: "file:///file.txt")
  end
end

Completions

Completions provide auto-complete suggestions for prompt arguments.

Array Completions

The simplest approach is an array of hint values:

argument do
  name "tone"
  description "The tone"
  required false
  completion ["formal", "casual", "humorous"]
end

Custom Completion Class

For dynamic completions, create a class that inherits from ModelContextProtocol::Server::Completion:

class ToneCompletion < ModelContextProtocol::Server::Completion
  TONES = ["formal", "casual", "humorous", "serious", "enthusiastic"].freeze

  def call
    filtered = TONES.select { |t| t.start_with?(argument_value.downcase) }
    respond_with values: filtered
  end
end

class MyPrompt < ModelContextProtocol::Server::Prompt
  define do
    name "my_prompt"
    description "A prompt with custom completion"

    argument do
      name "tone"
      description "The tone"
      required false
      completion ToneCompletion
    end
  end
end

Completion classes have access to:

Completions should return quickly (they're called during typing) and filter results based on argument_value.

Cancellation

Wrap long-running prompt generation in a cancellable block:

def call
  messages = cancellable do
    build_complex_message_history
  end
  respond_with messages: messages
end

Error Handling

For prompts, raise exceptions for errors. The server handles them appropriately:

def call
  raise ArgumentError, "Invalid tone" unless valid_tone?(arguments[:tone])

  messages = build_messages
  respond_with messages: messages
end

Logging

def call
  client_logger.info("Processing your request...")
  server_logger.debug("Prompt called with arguments: #{arguments}")

  messages = message_history do
    user_message do
      text_content(text: "Process this: #{arguments[:input]}")
    end
  end

  respond_with messages: messages
end

Testing

The gem provides RSpec helpers and matchers via require "model_context_protocol/rspec". See the configuration skill for setup instructions. The examples below assume ModelContextProtocol::RSpec.configure! has been called in your spec helper.

Use the call_mcp_prompt helper instead of calling the class directly:

RSpec.describe BrainstormExcusesPrompt, type: :mcp do
  describe ".call" do
    subject { call_mcp_prompt(described_class, { tone: "whiny", undesirable_activity: "doing chores" }) }

    it { is_expected.to be_valid_mcp_prompt_response }

    it "includes user and assistant messages" do
      expect(subject).to have_message_with_role("user")
      expect(subject).to have_message_with_role("assistant")
    end

    it "has the expected number of messages" do
      expect(subject).to have_message_count(3)
    end

    it "incorporates the activity in the prompt" do
      expect(subject).to have_message_with_role("user").containing("doing chores")
    end
  end
end

Testing Completions

Completions use the call signature: CompletionClass.call(argument_name, argument_value).

RSpec.describe ToneCompletion do
  describe ".call" do
    subject { described_class.call("tone", argument_value) }

    context "with partial value" do
      let(:argument_value) { "for" }

      it "returns filtered options" do
        values = subject[:completion][:values]
        expect(values).to include("formal")
        expect(values).not_to include("casual")
      end
    end
  end
end

Testing Class Validity

it "is a valid MCP prompt" do
  expect(BrainstormExcusesPrompt).to be_valid_mcp_class(:prompt)
end

Available Prompt Matchers

Registration

Register prompts in the server configuration:

config.registry do
  prompts do
    register BrainstormExcusesPrompt
    register CodeReviewPrompt
  end
end

Naming Conventions