Tools

Available Instance Variables

Response Types

Text Content

def call
  respond_with content: text_content(text: "Result text")
end

Structured Content

When using output_schema, return structured data validated against the schema:

define do
  name "get_weather_data"
  description "Get weather data"

  input_schema do
    { type: "object", properties: { location: { type: "string" } }, required: ["location"] }
  end

  output_schema do
    {
      type: "object",
      properties: {
        temperature: { type: "number" },
        conditions: { type: "string" }
      },
      required: ["temperature", "conditions"]
    }
  end
end

def call
  respond_with structured_content: { temperature: 22.5, conditions: "sunny" }
end

Image Content

def call
  base64_data = Base64.strict_encode64(image_bytes)
  respond_with content: image_content(data: base64_data, mime_type: "image/png")
end

Audio Content

def call
  base64_data = Base64.strict_encode64(audio_bytes)
  respond_with content: audio_content(data: base64_data, mime_type: "audio/mp3")
end

Embedded Resource

def call
  resource_data = SomeResource.call(client_logger, server_logger, context)
  respond_with content: embedded_resource_content(resource: resource_data)
end

Resource Link

def call
  respond_with content: resource_link(name: "config.json", uri: "file:///config.json")
end

Mixed Content

Combine multiple content types in a single response:

def call
  text = text_content(text: "Analysis results:")
  chart = image_content(data: chart_data, mime_type: "image/png")
  link = resource_link(name: "Raw data", uri: "data://results.csv")
  respond_with content: [text, chart, link]
end

Error Response

def call
  respond_with error: "Something went wrong"
end

Tool Annotations

Annotations provide hints about tool behavior to clients:

define do
  name "delete_file"
  description "Deletes a file"

  annotations do
    read_only_hint false
    destructive_hint true
    idempotent_hint true
    open_world_hint false
  end

  input_schema do
    { type: "object", properties: { path: { type: "string" } }, required: ["path"] }
  end
end

Security Schemes

define do
  name "search"
  description "Search data"

  security_schemes do
    [
      { type: "noauth" },
      { type: "oauth2", scopes: ["search.read"] }
    ]
  end
end

Cancellation and Progress

Cancellable Operations

Wrap long-running operations in a cancellable block:

def call
  result = cancellable do
    perform_long_operation
  end
  respond_with content: text_content(text: result)
end

Progress Notifications

Use progressable to send automatic progress updates:

def call
  result = progressable(max_duration: 30, message: "Processing") do
    cancellable do
      perform_long_operation
    end
  end
  respond_with content: text_content(text: result)
end

The order matters: progressable wraps cancellable.

Error Handling

Tools have a dedicated error response type. Use it for validation failures, external service errors, and permission issues:

def call
  return respond_with error: "Missing required argument: id" unless arguments[:id]

  begin
    result = external_api_call
    respond_with content: text_content(text: result)
  rescue Timeout::Error
    respond_with error: "External service timed out"
  end
end

Logging

def call
  # Client-facing messages (sent via MCP protocol)
  client_logger.info("Processing your request...")
  client_logger.warning("Rate limit approaching")

  # Server-side debugging (not sent to clients)
  server_logger.debug("Arguments: #{arguments.inspect}")
  server_logger.error("External API failed: #{error.message}")
end

Input Schema Patterns

Common Property Types

input_schema do
  {
    type: "object",
    properties: {
      name: { type: "string", description: "User name" },
      count: { type: "integer", minimum: 1, maximum: 100 },
      price: { type: "number", minimum: 0 },
      active: { type: "boolean" },
      status: { type: "string", enum: ["pending", "active", "completed"] },
      tags: { type: "array", items: { type: "string" } }
    },
    required: ["name"]
  }
end

No Input Required

input_schema do
  { type: "object", properties: {}, additionalProperties: false }
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_tool helper instead of calling the class directly:

RSpec.describe WeatherTool, type: :mcp do
  describe ".call" do
    subject { call_mcp_tool(described_class, { location: "New York" }, { user_id: "123" }) }

    it { is_expected.to be_valid_mcp_tool_response }

    it "returns weather data" do
      expect(subject).to have_text_content(/Temperature/)
    end
  end
end

Testing Structured Content

subject { call_mcp_tool(described_class, { location: "New York" }) }

it "returns structured weather data" do
  expect(subject).to have_structured_content(temperature: 22.5, conditions: "sunny")
end

Testing Image and Audio Content

it "returns an image" do
  expect(subject).to have_image_content(mime_type: "image/png")
end

it "returns audio" do
  expect(subject).to have_audio_content(mime_type: "audio/mp3")
end

Testing Embedded Resources and Resource Links

it "returns an embedded resource" do
  expect(subject).to have_embedded_resource_content(uri: "file:///config.json")
end

it "returns a resource link" do
  expect(subject).to have_resource_link_content(name: "config.json", uri: "file:///config.json")
end

Testing Error Responses

it "returns an error response" do
  expect(subject).to be_mcp_error_response("timed out")
end

it "matches error with regex" do
  expect(subject).to be_mcp_error_response(/timed out/)
end

Testing Class Validity

it "is a valid MCP tool" do
  expect(WeatherTool).to be_valid_mcp_class(:tool)
end

Available Tool Matchers

Registration

Register tools in the server configuration:

config.registry do
  tools do
    register WeatherTool
    register CalculatorTool
  end
end

Naming Conventions