Module: Anthropic::Helpers::Tools::Mcp

Defined in:
lib/anthropic/helpers/tools/mcp.rb

Overview

Helpers for integrating Model Context Protocol (MCP) servers with the Anthropic SDK.

These helpers convert types returned by the mcp gem into the shapes the Beta Messages API accepts, so you don't have to write glue code yourself.

The mcp gem is an optional dependency; install it separately:

gem install mcp

Examples:

Convert MCP tools and run them through tool_runner

require "mcp"
require "anthropic"

transport  = MCP::Client::HTTP.new(url: "https://example.com/mcp")
mcp_client = MCP::Client.new(transport: transport)
anthropic  = Anthropic::Client.new

runner = anthropic.beta.messages.tool_runner(
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  messages: [{role: "user", content: "Use the available tools"}],
  tools: Anthropic::Mcp.tools(mcp_client.tools, mcp_client)
)
runner.run_until_finished

Defined Under Namespace

Classes: Tool, UnsupportedMCPValueError

Constant Summary collapse

SUPPORTED_IMAGE_TYPES = 
Set.new(%w[image/jpeg image/png image/gif image/webp]).freeze

Class Method Summary collapse

Class Method Details

.content(mcp_content, cache_control: nil) ⇒ Hash

Convert a single MCP content item into a Beta content block.

Handles text, image, and embedded resource content types. Raises UnsupportedMCPValueError for audio or resource_link types.

Parameters:

  • mcp_content (MCP::Content::Text, MCP::Content::Image, MCP::Content::EmbeddedResource, Hash)
  • cache_control (Hash, nil) (defaults to: nil)

Returns:

  • (Hash) 


197
198
199
200
201
202
203
 
# File 'lib/anthropic/helpers/tools/mcp.rb', line 197

def content(mcp_content, cache_control: nil)
  require_mcp!
  h = to_hash!(mcp_content, "MCP content")
  block = convert_content(h)
  block[:cache_control] = cache_control if cache_control
  block
end

.convert_tool_result(response) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Called by Anthropic::Helpers::Tools::Mcp::Tool#call; converts a JSON-RPC tools/call response into the value the tool runner expects.



257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
 
# File 'lib/anthropic/helpers/tools/mcp.rb', line 257

def convert_tool_result(response)
  result = nested_result(response)
  is_error = hkey(result, :isError)
  content_items = hkey(result, :content) || []
  structured = hkey(result, :structuredContent)

  if is_error
    blocks = content_items.map { content(_1) }
    raise Anthropic::Errors::Error, render_error_blocks(blocks)
  end

  return JSON.generate(structured) if content_items.empty? && structured

  content_items.map { content(_1) }
end

.message(mcp_message, cache_control: nil) ⇒ Hash

Convert an MCP prompt message into a Beta message parameter.

Parameters:

  • mcp_message (MCP::Prompt::Message, Hash)
  • cache_control (Hash, nil) (defaults to: nil) —

    Forwarded to the produced content block.

Returns:

  • (Hash) 


177
178
179
180
181
182
183
184
185
186
 
# File 'lib/anthropic/helpers/tools/mcp.rb', line 177

def message(mcp_message, cache_control: nil)
  require_mcp!
  h = to_hash!(mcp_message, "MCP prompt message")
  role = hkey(h, :role)
  role = role.to_sym if role.respond_to?(:to_sym)
  {
    role: role,
    content: [content(hkey(h, :content), cache_control: cache_control)]
  }
end

.resource_to_contents(result, cache_control: nil) ⇒ Array<Hash>

Convert MCP resource read results into Beta content blocks — one per item in contents. Raises UnsupportedMCPValueError on any item whose MIME type is unsupported.

Parameters:

  • result (Hash, Array, #contents) —

    The result from mcp_client.read_resource(uri: ...). The mcp gem returns just the contents array — both that and a {contents: [...]} hash are accepted.

  • cache_control (Hash, nil) (defaults to: nil) —

    Forwarded to each produced block.

Returns:

  • (Array<Hash>) 


215
216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/anthropic/helpers/tools/mcp.rb', line 215

def resource_to_contents(result, cache_control: nil)
  require_mcp!
  contents = extract_resource_contents(result)
  if contents.empty?
    raise UnsupportedMCPValueError,
          "Resource contents array must contain at least one item"
  end

  contents.map do |item|
    block = resource_contents_to_block(to_hash!(item, "resource"))
    block[:cache_control] = cache_control if cache_control
    block
  end
end

.resource_to_files(result) ⇒ Array<Anthropic::FilePart>

Convert MCP resource read results into FilePart instances suitable for client.beta.files.upload(file: ...). No MIME filtering — every item in contents becomes a file.

Parameters:

  • result (Hash, Array, #contents)

Returns:



236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/anthropic/helpers/tools/mcp.rb', line 236

def resource_to_files(result)
  require_mcp!
  contents = extract_resource_contents(result)
  if contents.empty?
    raise UnsupportedMCPValueError,
          "Resource contents array must contain at least one item"
  end

  contents.map do |item|
    resource = to_hash!(item, "resource")
    Anthropic::FilePart.new(
      StringIO.new(resource_bytes(resource)),
      filename: filename_from_uri(hkey(resource, :uri)),
      content_type: hkey(resource, :mimeType)
    )
  end
end

.tool(mcp_tool, mcp_client, cache_control: nil, defer_loading: nil, allowed_callers: nil, eager_input_streaming: nil, input_examples: nil, strict: nil) ⇒ Anthropic::Helpers::Tools::Mcp::Tool

Convert an MCP tool definition into a runnable tool for tool_runner.

Parameters:

  • mcp_tool (MCP::Client::Tool, Hash) —

    An MCP tool, typically from mcp_client.list_tools / mcp_client.tools. May be a typed MCP::Client::Tool or a hash with :name, :description, :input_schema (or :inputSchema).

  • mcp_client (#call_tool) —

    The MCP client used to invoke the tool.

  • cache_control (Hash, nil) (defaults to: nil) —

    Prompt-caching control passed through to the tool definition.

  • defer_loading (Boolean, nil) (defaults to: nil) —

    If true, the tool is excluded from the initial system prompt.

  • allowed_callers (Array<Symbol, String>, nil) (defaults to: nil) —

    Restricts which callers may invoke the tool.

  • eager_input_streaming (Boolean, nil) (defaults to: nil) —

    Enables eager input streaming for the tool.

  • input_examples (Array<Hash>, nil) (defaults to: nil) —

    Example inputs for the tool.

  • strict (Boolean, nil) (defaults to: nil) —

    When true, guarantees schema validation on tool names and inputs.

Returns:



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/anthropic/helpers/tools/mcp.rb', line 140

def tool(
  mcp_tool,
  mcp_client,
  cache_control: nil,
  defer_loading: nil,
  allowed_callers: nil,
  eager_input_streaming: nil,
  input_examples: nil,
  strict: nil
)
  require_mcp!
  Tool.build(
    mcp_tool: mcp_tool,
    mcp_client: mcp_client,
    cache_control: cache_control,
    defer_loading: defer_loading,
    allowed_callers: allowed_callers,
    eager_input_streaming: eager_input_streaming,
    input_examples: input_examples,
    strict: strict
  )
end

.tools(mcp_tools, mcp_client, **opts) ⇒ Array<Anthropic::Helpers::Tools::Mcp::Tool>

Convert a list of MCP tools into runnable tools.

Parameters:

  • mcp_tools (Array<MCP::Client::Tool, Hash>)
  • mcp_client (#call_tool)

Returns:



168
169
170
 
# File 'lib/anthropic/helpers/tools/mcp.rb', line 168

def tools(mcp_tools, mcp_client, **opts)
  mcp_tools.map { tool(_1, mcp_client, **opts) }
end