RubyLLM MCP

https://www.rubyllm-mcp.com/
Admin
RubyLLM MCP is a Ruby library that connects RubyLLM chats to Model Context Protocol servers,...
Tokens:55,530
Snippets:520
Trust Score:5.3
Update:6 months ago
Show doc for...
Tokens:
Raw
### Rails OAuth Quick Example with RubyLLM::MCP

Source: https://www.rubyllm-mcp.com/

A concise example demonstrating the OAuth flow setup for Rails applications using RubyLLM::MCP. It initializes an OAuth client, performs browser-based authentication, starts the client, interacts with a chat model using the client's tools, and then stops the client.

```ruby
client = RubyLLM::MCP.client(
  name: "oauth-server",
  transport_type: :streamable,
  start: false,
  config: {
    url: ENV.fetch("MCP_SERVER_URL"),
    oauth: { scope: "mcp:read mcp:write" }
  }
)

client.oauth(type: :browser).authenticate
client.start

chat = RubyLLM.chat(model: "gpt-4.1-mini")
chat.with_tools(*client.tools)
puts chat.ask("What should I prioritize today?")

client.stop

```

--------------------------------

### Basic RubyLLM::MCP Client Setup and Chat Interaction

Source: https://www.rubyllm-mcp.com/

Demonstrates the basic setup of a RubyLLM::MCP client using stdio transport to connect to a filesystem server. It then configures an OpenAI chat model, attaches the client's tools, and sends a query to find test files with pending TODOs.

```ruby
require "ruby_llm/mcp"

RubyLLM.configure do |config|
  config.openai_api_key = ENV.fetch("OPENAI_API_KEY")
end

client = RubyLLM::MCP.client(
  name: "filesystem",
  transport_type: :stdio,
  config: {
    command: "bunx",
    args: ["@modelcontextprotocol/server-filesystem", Dir.pwd]
  }
)

chat = RubyLLM.chat(model: "gpt-4.1-mini")
chat.with_tools(*client.tools)
puts chat.ask("Find test files with pending TODOs")

```

--------------------------------

### OAuth Setup for Rails and CLI with RubyLLM::MCP

Source: https://www.rubyllm-mcp.com/

Provides examples for setting up OAuth 2.1 authentication with RubyLLM::MCP. It covers per-user OAuth clients for Rails applications and a browser-based OAuth flow for command-line interface tools, including authentication and client startup/shutdown.

```ruby
# OAuth setup (Rails and CLI)
# Rails: per-user OAuth client (after running rails generate ruby_llm:mcp:oauth:install User)
client = current_user.mcp_client
chat = RubyLLM.chat(model: "gpt-4.1-mini")
chat.with_tools(*client.tools)
puts chat.ask("What changed in my connected repos this week?")

# CLI: browser-based OAuth flow
cli_client = RubyLLM::MCP.client(
  name: "oauth-server",
  transport_type: :streamable,
  start: false,
  config: {
    url: ENV.fetch("MCP_SERVER_URL"),
    oauth: { scope: "mcp:read mcp:write" }
  }
)

cli_client.oauth(type: :browser).authenticate
cli_client.start
puts RubyLLM.chat(model: "gpt-4.1-mini").with_tools(*cli_client.tools).ask("List my open tasks.")
cli_client.stop

```

--------------------------------

### Combining Tools, Resources, and Prompts

Source: https://www.rubyllm-mcp.com/getting-started/getting-started.html

Shows a comprehensive setup including tools for capabilities, resources for context, and prompts for guidance. This approach allows for highly specialized and context-aware AI interactions.

```ruby
chat = RubyLLM.chat(model: "gpt-4")

# Add tools for capabilities
chat.with_tools(*client.tools)

# Add resources for context
chat.with_resource(client.resource("project_overview"))

# Add prompts for guidance
chat.with_prompt(
  client.prompt("analysis_template"),
  arguments: { focus: "performance" }
)

response = chat.ask("Analyze the project")
puts response
```

--------------------------------

### Manage MCP Connection Lifecycle

Source: https://www.rubyllm-mcp.com/getting-started/getting-started.html

Provides examples for manually starting, stopping, restarting, and performing health checks on an MCP client connection.

```ruby
client = RubyLLM::MCP.client(name: "my-server", transport_type: :stdio, start: false, config: { command: "node", args: ["server.js"] })
client.start
client.restart!
client.stop

if client.ping
  puts "Server is responsive"
end
```

--------------------------------

### Implement Shared Redis Storage

Source: https://www.rubyllm-mcp.com/guides/oauth.html

Provides a simple example of a shared Redis storage implementation for non-user-specific scenarios and shows how to initialize the client with it.

```ruby
class RedisOAuthStorage
  def initialize(redis_url = ENV["REDIS_URL"])
    @redis = Redis.new(url: redis_url)
  end

  def get_token(server_url)
    data = @redis.get("oauth:token:#{server_url}")
    data ? RubyLLM::MCP::Auth::Token.from_h(JSON.parse(data, symbolize_names: true)) : nil
  end

  def set_token(server_url, token)
    @redis.set("oauth:token:#{server_url}", token.to_h.to_json)
    @redis.expire("oauth:token:#{server_url}", 86400)
  end
end

client = RubyLLM::MCP.client(config: { oauth: { storage: RedisOAuthStorage.new } })
```

--------------------------------

### URL Normalization Example

Source: https://www.rubyllm-mcp.com/guides/oauth.html

Demonstrates how server URLs are normalized to ensure consistency and prevent token confusion. It shows the conversion of URLs with different cases and ports to a standard format.

```text
https://MCP.EXAMPLE.COM:443/api/  → https://mcp.example.com/api
http://example.com:80             → http://example.com
```

--------------------------------

### Manage Connection Lifecycle

Source: https://www.rubyllm-mcp.com/configuration.html

Demonstrates manual control over client connection states, including starting, checking status, restarting, and stopping the client.

```ruby
client = RubyLLM::MCP.client(
  name: "manual-server",
  transport_type: :stdio,
  start: false,
  config: { command: "mcp-server" }
)

client.start
puts client.alive?
client.restart!
client.stop
```

--------------------------------

### Handling MCP Progress and Logging Notifications

Source: https://www.rubyllm-mcp.com/

Demonstrates how to set up handlers for MCP progress and logging events. This allows real-time feedback during long-running operations and captures diagnostic information. The example also shows a chat interaction that triggers these handlers.

```ruby
# Handlers (response + notifications)
client.on_progress do |progress|
  puts "Progress: #{progress.progress}% - #{progress.message}"
end

client.on_logging do |logging|
  puts "[#{logging.level}] #{logging.message}"
end

chat = RubyLLM.chat(model: "gpt-4.1-mini")
chat.with_tools(*client.tools)

chat.ask("Run a repository scan and summarize risks.") do |chunk|
  print chunk.content
end

```

--------------------------------

### Using MCP Resources with RubyLLM Chat

Source: https://www.rubyllm-mcp.com/

Shows how to fetch a specific resource (e.g., 'release_notes') from an MCP client and use it within a RubyLLM chat session. The example demonstrates attaching the resource to the chat and asking for a summary.

```ruby
# Resources (simple)
resource = client.resource("release_notes")
chat = RubyLLM.chat(model: "gpt-4.1-mini")
chat.with_resource(resource)

# More complex: use client.resource_template(...) with chat.with_resource_template(...)
puts chat.ask("Summarize release notes for the team in 5 bullet points.")

```

--------------------------------

### Installing RubyLLM::MCP Gem

Source: https://www.rubyllm-mcp.com/

Instructions for adding the RubyLLM::MCP gem to a Ruby project using Bundler. It includes the command for direct addition and the syntax for the Gemfile, along with optional installation of the 'mcp' SDK adapter.

```ruby
bundle add ruby_llm-mcp

# or in Gemfile:
gem "ruby_llm-mcp"

# Optional official SDK adapter:
gem "mcp", "~> 0.7"

```

--------------------------------

### Initialize RubyLLM MCP Client and Chat

Source: https://www.rubyllm-mcp.com/getting-started/overview.html

Demonstrates how to initialize an MCP client using the stdio transport and integrate its tools into a RubyLLM chat session. This setup allows the LLM to access external filesystem capabilities.

```ruby
require "ruby_llm/mcp"

client = RubyLLM::MCP.client(
  name: "filesystem",
  transport_type: :stdio,
  config: {
    command: "npx",
    args: ["@modelcontextprotocol/server-filesystem", "."]
  }
)

chat = RubyLLM.chat(model: "gpt-4.1")
chat.with_tools(*client.tools)
puts chat.ask("List the top-level files and summarize this project")
```

--------------------------------

### Basic OAuth Client Initialization

Source: https://www.rubyllm-mcp.com/guides/oauth.html

Initializes an MCP client with OAuth configuration and performs authentication using the browser flow. It then starts the client and retrieves available tools.

```ruby
require "ruby_llm/mcp"

client = RubyLLM::MCP.client(
  name: "oauth-server",
  transport_type: :sse,  # or :streamable
  start: false,
  config: {
    url: "https://mcp.example.com/api",
    oauth: { scope: "mcp:read mcp:write" }
  }
)

client.oauth(type: :browser).authenticate

client.start
tools = client.tools
puts "Available tools: #{tools.map(&:name).join(', ')}"
```

--------------------------------

### Manual Authorization Flow

Source: https://www.rubyllm-mcp.com/guides/oauth.html

This example shows how to manually initiate and complete the OAuth authorization flow, suitable for headless environments. It retrieves an authorization URL, prompts the user for input, and then completes the flow.

```ruby
require "ruby_llm/mcp"

client = RubyLLM::MCP.client(
  name: "manual-auth",
  transport_type: :sse,
  start: false,
  config: {
    url: "https://mcp.example.com/api",
    oauth: { scope: "mcp:read" }
  }
)

# Get authorization URL
oauth = client.oauth(type: :standard)
auth_url = oauth.start_authorization_flow

puts "Visit: #{auth_url}"
puts "Enter authorization code:"
code = gets.chomp

puts "Enter state parameter:"
state = gets.chomp

# Complete authorization
oauth.complete_authorization_flow(code, state)

# Use client
client.start
tools = client.tools
```

--------------------------------

### Execute MCP Tools Directly

Source: https://www.rubyllm-mcp.com/server/tools.html

Provides examples of executing tools directly via the client and handling structured output validation.

```ruby
result = client.execute_tool(
  name: "read_file",
  parameters: { path: "README.md" }
)

weather_tool = client.tool("get_weather")
result = weather_tool.execute(location: "San Francisco")

if result.is_a?(Hash) && result[:error]
  puts "Tool validation failed: #{result[:error]}"
else
  puts "Temperature: #{result.temperature}"
end
```

--------------------------------

### Configure STDIO Transport Client in Ruby

Source: https://www.rubyllm-mcp.com/guides/adapters.html

This example demonstrates how to configure a client to use the STDIO transport for communicating with a local MCP server. It specifies the command to run the server, its arguments, and environment variables.

```ruby
client = RubyLLM::MCP.client(
  name: "local-server",
  transport_type: :stdio,
  config: {
    command: "python",
    args: ["-m", "my_mcp_server"],
    env: { "DEBUG" => "1" }
  }
)
```

--------------------------------

### STDIO Transport Configuration

Source: https://www.rubyllm-mcp.com/guides/adapters.html

Example of configuring the STDIO transport for a local MCP server using the RubyLLM::MCP client.

```APIDOC
## STDIO Transport Configuration

### Description
This example demonstrates how to configure and use the STDIO transport for connecting to a local MCP server. The STDIO transport is ideal for scenarios where the MCP server runs as a subprocess and communicates via standard input/output.

### Method
`RubyLLM::MCP.client`

### Endpoint
N/A (Client-side configuration)

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```ruby
client = RubyLLM::MCP.client(
  name: "local-server",
  transport_type: :stdio,
  config: {
    command: "python",
    args: ["-m", "my_mcp_server"],
    env: { "DEBUG" => "1" }
  }
)
```

### Response
#### Success Response (200)
N/A (Client-side configuration, no direct server response)

#### Response Example
N/A
```

--------------------------------

### RubyLLM MCP Custom OAuth Provider Setup

Source: https://www.rubyllm-mcp.com/guides/oauth.html

Demonstrates how to set up a custom OAuth provider in RubyLLM MCP. This includes configuring the server URL, redirect URI, scope, logger, and custom storage, along with manual flow control for authorization.

```ruby
require "ruby_llm/mcp/auth/oauth_provider"

provider = RubyLLM::MCP::Auth::OAuthProvider.new(
  server_url: "https://mcp.example.com",
  redirect_uri: "http://localhost:8080/callback",
  scope: "custom:scope",
  logger: Logger.new($stdout, level: Logger::DEBUG),
  storage: CustomStorage.new
)

# Manual flow control
auth_url = provider.start_authorization_flow
# ... user authorization ...
token = provider.complete_authorization_flow(code, state)
```

--------------------------------

### Initialize Chat with System Prompts

Source: https://www.rubyllm-mcp.com/server/prompts.html

Demonstrates how to set system behavior using a predefined prompt template and perform a follow-up query within that context.

```ruby
chat.with_prompt(
  client.prompt("system_instructions"),
  arguments: {
    role: "code_reviewer",
    standards: "ruby_style_guide"
  }
)

response = chat.ask("Review this Ruby code: #{code}")
puts response
```

--------------------------------

### Discover and Inspect MCP Tools

Source: https://www.rubyllm-mcp.com/server/tools.html

Demonstrates how to initialize an MCP client, list available tools with their input schemas, and retrieve specific tool details.

```ruby
client = RubyLLM::MCP.client(
  name: "filesystem",
  transport_type: :stdio,
  config: {
    command: "npx",
    args: ["@modelcontextprotocol/server-filesystem", "/path/to/directory"]
  }
)

tools = client.tools
tools.each do |tool|
  puts "- #{tool.name}: #{tool.description}"
  tool.input_schema["properties"]&.each do |param, schema|
    required = tool.input_schema["required"]&.include?(param) ? " (required)" : ""
    puts "  - #{param}: #{schema['description']}#{required}"
  end
end

file_tool = client.tool("read_file")
puts "Tool: #{file_tool.name}"
```

--------------------------------

### Handle Connection Errors in RubyLLM MCP

Source: https://www.rubyllm-mcp.com/configuration.html

Demonstrates how to catch `RubyLLM::MCP::Errors::TransportError` which occurs if the MCP client fails to establish a connection or start the server process, for example, if the specified command is not found.

```ruby
begin
  client = RubyLLM::MCP.client(
    name: "failing-server",
    transport_type: :stdio,
    config: { command: "nonexistent-command" }
  )
rescue RubyLLM::MCP::Errors::TransportError => e
  puts "Failed to start server: #{e.message}"
end
```

--------------------------------

### Discovering and Listing MCP Resources

Source: https://www.rubyllm-mcp.com/server/resources.html

Demonstrates how to initialize an MCP client and retrieve a list of available static resources, including their metadata like URI and MIME type.

```ruby
client = RubyLLM::MCP.client(
  name: "content-server",
  transport_type: :stdio,
  config: {
    command: "npx",
    args: ["@modelcontextprotocol/server-filesystem", "/path/to/docs"]
  }
)

# Get all available resources
resources = client.resources
puts "Available resources:"
resources.each do |resource|
  puts "- #{resource.name}: #{resource.description}"
  puts "  URI: #{resource.uri}"
  puts "  Type: #{resource.mime_type}"
end
```

--------------------------------

### Get Task Status in RubyLLM::MCP

Source: https://www.rubyllm-mcp.com/server/tasks.html

This snippet illustrates how to retrieve the status of a specific task using its ID with `client.task_get` in RubyLLM::MCP. It also shows how to refresh an existing task object to get its latest status.

```ruby
task = client.task_get("task-123")
puts task.status
puts task.status_message
puts task.poll_interval

task = task.refresh

```

--------------------------------

### Discovering and Using Resource Templates

Source: https://www.rubyllm-mcp.com/server/resources.html

Explains how to list available resource templates, inspect their required arguments, and generate dynamic content based on those arguments.

```ruby
# Get all resource templates
templates = client.resource_templates
puts "Available templates:"
templates.each do |template|
  puts "- #{template.name}: #{template.description}"
  puts "  URI template: #{template.uri_template}"

  # Show required arguments
  template.arguments.each do |arg|
    required = arg.required ? " (required)" : ""
    puts "  - #{arg.name}: #{arg.description}#{required}"
  end
end

# Use template with arguments in a chat
log_template = client.resource_template("application_logs")
chat = RubyLLM.chat(model: "gpt-4")
chat.with_resource_template(log_template, arguments: {
  date: "2024-01-15",
  level: "error",
  service: "api"
})

response = chat.ask("What errors occurred in the API service?")
puts response
```

--------------------------------

### Initialize RubyLLM MCP Client

Source: https://www.rubyllm-mcp.com/configuration.html

Demonstrates the basic instantiation of an MCP client with required parameters like name, transport type, and configuration object.

```ruby
client = RubyLLM::MCP.client(
  name: "unique-client-name",
  transport_type: :stdio,
  adapter: :ruby_llm,
  start: true,
  request_timeout: 8000,
  config: {}
)
```

--------------------------------

### Control Connection Lifecycle

Source: https://www.rubyllm-mcp.com/guides/getting-started.html

Manually starting, stopping, and restarting an MCP client connection.

```ruby
client = RubyLLM::MCP.client(
  name: "my-server",
  transport_type: :stdio,
  start: false,
  config: { command: "node", args: ["server.js"] }
)

client.start
client.restart!
client.stop
```

--------------------------------

### Initialize MCP Client and List Prompts

Source: https://www.rubyllm-mcp.com/server/prompts.html

Initializes the RubyLLM::MCP client with specified transport and configuration, then retrieves and displays all available prompts along with their descriptions and arguments.

```ruby
client = RubyLLM::MCP.client(
  name: "prompt-server",
  transport_type: :stdio,
  config: {
    command: "bunx",
    args: ["@modelcontextprotocol/server-prompts", "/path/to/prompts"]
  }
)

# Get all available prompts
prompts = client.prompts
puts "Available prompts:"
prompts.each do |prompt|
  puts "- #{prompt.name}: #{prompt.description}"

  # Show arguments
  prompt.arguments.each do |arg|
    required = arg.required ? " (required)" : ""
    puts "  - #{arg.name}: #{arg.description}#{required}"
  end
end
```

--------------------------------

### Install RubyLLM MCP Configuration

Source: https://www.rubyllm-mcp.com/guides/rails-integration.html

Generates the necessary configuration files for RubyLLM MCP within a Rails project.

```bash
rails generate ruby_llm:mcp:install
```

--------------------------------

### Install RubyLLM MCP Gem

Source: https://www.rubyllm-mcp.com/getting-started/getting-started.html

Instructions for adding the RubyLLM MCP gem to a Ruby project using Bundler.

```bash
bundle add ruby_llm-mcp
bundle install
```

```ruby
gem 'ruby_llm-mcp'
```

--------------------------------

### Using Optional Prompt Arguments

Source: https://www.rubyllm-mcp.com/server/prompts.html

Demonstrates how to use a prompt that includes optional arguments, showing that not all arguments need to be provided.

```ruby
prompt = client.prompt("search_query")

# Use with optional arguments
chat = RubyLLM.chat(model: "gpt-4")
response = chat.ask_prompt(prompt, arguments: {
  query: "ruby programming",
  limit: 10,           # optional
  sort_by: "relevance" # optional
})
```

--------------------------------

### Configure RubyLLM Provider

Source: https://www.rubyllm-mcp.com/guides/getting-started.html

Basic configuration setup for the RubyLLM library, requiring an API key for the chosen LLM provider.

```ruby
require 'ruby_llm/mcp'

RubyLLM.configure do |config|
  config.openai_api_key = "your-openai-key"
end
```

--------------------------------

### Manage Global and Per-Client Adapters

Source: https://www.rubyllm-mcp.com/guides/adapters.html

Demonstrates how to set a global default adapter for all clients or override the adapter on a per-client basis for specific transport requirements.

```ruby
RubyLLM::MCP.configure do |config|
  config.default_adapter = :ruby_llm
end

client = RubyLLM::MCP.client(
  name: "filesystem",
  adapter: :ruby_llm,
  transport_type: :stdio,
  config: {
    command: "npx",
    args: ["@modelcontextprotocol/server-filesystem", "/path"]
  }
)
```

--------------------------------

### Handle Prompt and Argument Errors

Source: https://www.rubyllm-mcp.com/server/prompts.html

Examples of rescuing common errors such as PromptNotFound, PromptError for missing arguments, and CompletionError during prompt execution.

```ruby
# Handle missing prompt
begin
  prompt = client.prompt("nonexistent_prompt")
rescue RubyLLM::MCP::Errors::PromptNotFound => e
  puts "Prompt not found: #{e.message}"
end

# Handle missing arguments
begin
  chat = RubyLLM.chat(model: "gpt-4")
  response = chat.ask_prompt(prompt, arguments: { user_id: "12345" })
rescue RubyLLM::MCP::Errors::PromptError => e
  puts "Prompt error: #{e.message}"
end

# Handle completion errors
begin
  suggestions = prompt.complete("invalid_argument", "value")
rescue RubyLLM::MCP::Errors::CompletionError => e
  puts "Completion failed: #{e.message}"
end
```

--------------------------------

### Implement Basic Logging Notification Handler

Source: https://www.rubyllm-mcp.com/server/notifications.html

Demonstrates how to initialize an MCP client and register a callback to capture and output log messages generated by server operations.

```ruby
client = RubyLLM::MCP.client(
  name: "filesystem",
  transport_type: :stdio,
  config: {
    command: "bunx",
    args: ["@modelcontextprotocol/server-filesystem", "/path/to/directory"]
  }
)

client.on_logging do |logging|
  puts "#{logging.level.upcase}: #{logging.message}"
end

tool = client.tool("long_running_operation")
result = tool.execute(operation: "data_processing")
```

--------------------------------

### Track Progress Notifications

Source: https://www.rubyllm-mcp.com/server/notifications.html

Provides examples for handling progress updates, including simple console output and advanced UI integration with progress bars.

```ruby
client.on_progress do |progress|
  puts "Progress: #{progress.progress}% - #{progress.message}"
end

client.on_progress do |progress|
  update_progress_bar(progress.progress)
  update_status_message(progress.message)
end

def update_progress_bar(percentage)
  bar_width = (percentage / 100.0 * 50).to_i
  bar = "#" * bar_width + "-" * (50 - bar_width)
  print "\r[#{bar}] #{percentage}%"
end
```

--------------------------------

### Configure OAuth Authentication for MCP

Source: https://www.rubyllm-mcp.com/guides/rails-integration.html

Outlines the installation and usage patterns for enabling OAuth in multi-user Rails applications. This allows each user to maintain their own authenticated MCP connection.

```bash
rails generate ruby_llm:mcp:oauth:install
rails db:migrate
```

```ruby
class User < ApplicationRecord
  include UserMcpOauth
end

class AiResearchJob < ApplicationJob
  def perform(user_id, query)
    user = User.find(user_id)
    client = user.mcp_client
    tools = client.tools
    chat = RubyLLM.chat(provider: "anthropic/claude-sonnet-4").with_tools(*tools)
    response = chat.ask(query)
  end
end
```

--------------------------------

### Integrate Official MCP SDK Adapter

Source: https://www.rubyllm-mcp.com/guides/adapters.html

Shows how to configure the client to use the official MCP SDK adapter, enabling standard tool execution and SSE support.

```ruby
client = RubyLLM::MCP.client(
  name: "my_server",
  adapter: :mcp_sdk,
  transport_type: :stdio,
  config: {
    command: "python",
    args: ["-m", "my_mcp_server"]
  }
)

tool = client.tool("calculator")
result = tool.execute(operation: "add", a: 5, b: 3)
```

--------------------------------

### Client Initialization

Source: https://www.rubyllm-mcp.com/configuration.html

Create and configure a specific MCP client instance with transport-specific parameters.

```APIDOC
## RubyLLM::MCP.client

### Description
Initializes a new MCP client instance with a specific transport type and configuration.

### Method
POST /client/initialize

### Parameters
#### Request Body
- **name** (String) - Required - Unique identifier for the client.
- **transport_type** (Symbol) - Required - Connection type: :stdio, :sse, or :streamable.
- **adapter** (Symbol) - Optional - SDK adapter: :ruby_llm or :mcp_sdk.
- **config** (Hash) - Required - Transport-specific settings (e.g., command, args for STDIO).

### Request Example
client = RubyLLM::MCP.client(
  name: "local-server",
  transport_type: :stdio,
  config: {
    command: "python",
    args: ["-m", "my_mcp_server"]
  }
)
```

--------------------------------

### Execute Sampling Requests

Source: https://www.rubyllm-mcp.com/client/sampling.html

Demonstrates how a client executes a tool that triggers a sampling request, allowing the server to utilize the client's LLM configuration.

```ruby
tool = client.tool("analyze_data")
result = tool.execute(data: "some data to analyze")
puts result
```

--------------------------------

### Run Database Migrations for MCP OAuth

Source: https://www.rubyllm-mcp.com/guides/rails-oauth.html

Applies the database migrations generated by the RubyLLM::MCP OAuth installer. These migrations create the necessary tables to store OAuth credentials and state information.

```ruby
rails db:migrate
```

--------------------------------

### Execute Tool-Resource Workflows

Source: https://www.rubyllm-mcp.com/server/resources.html

Demonstrates chaining tools where the output of one tool (a resource) is used as an input for another tool.

```ruby
analysis_tool = client.tool("analyze_data")
analysis_result = analysis_tool.execute(dataset: "user_behavior")
if analysis_result.is_a?(RubyLLM::MCP::Content)
  chat = RubyLLM.chat(model: "gpt-4")
  chat.with_resource(analysis_result)
  recommendation_tool = client.tool("generate_recommendations")
  recommendations = recommendation_tool.execute(analysis_resource: analysis_result.uri)
end
```

--------------------------------

### Implement a Custom Transport Interface

Source: https://www.rubyllm-mcp.com/guides/adapters.html

Defines the required interface for implementing custom transport protocols in the :ruby_llm adapter. Classes must implement request, alive?, start, close, and set_protocol_version methods.

```ruby
class CustomTransport
  def initialize(coordinator:, **config)
    @coordinator = coordinator
    @config = config
  end

  def request(body, add_id: true, wait_for_response: true)
  end

  def alive?
  end

  def start
  end

  def close
  end

  def set_protocol_version(version)
    @protocol_version = version
  end
end
```

--------------------------------

### Configure Multiple MCP Adapters

Source: https://www.rubyllm-mcp.com/guides/adapters.html

Demonstrates how to configure different adapters for various MCP servers within the same application. This allows combining the feature-rich :ruby_llm adapter with the official :mcp_sdk adapter.

```ruby
RubyLLM::MCP.configure do |config|
  config.default_adapter = :ruby_llm

  config.mcp_configuration = [
    {
      name: "filesystem",
      adapter: :ruby_llm,
      transport_type: :stdio,
      config: {
        command: "npx",
        args: ["@modelcontextprotocol/server-filesystem", Rails.root]
      }
    },
    {
      name: "weather",
      adapter: :mcp_sdk,
      transport_type: :http,
      config: {
        url: "https://weather-api.example.com/mcp"
      }
    }
  ]
end

RubyLLM::MCP.establish_connection do |clients|
  fs_client = clients["filesystem"]
  weather_client = clients["weather"]
  all_tools = RubyLLM::MCP.tools
end
```

--------------------------------

### Configure and Access Roots

Source: https://www.rubyllm-mcp.com/client/roots.html

Methods for setting up initial root directories during client configuration and querying existing root paths.

```APIDOC
## Configuration and Access

### Description
Configure the base directories for the MCP client and verify if specific paths fall within the allowed root scope.

### Method
Ruby Configuration / Instance Method

### Parameters
#### Request Body
- **roots** (Array<String|Pathname>) - Required - List of directory paths to grant the server access to.

### Request Example
RubyLLM::MCP.configure do |config|
  config.roots = ["/path/to/project", Rails.root]
end

### Response
#### Success Response (200)
- **paths** (Array) - Returns the list of currently configured root paths.
- **includes?** (Boolean) - Returns true if the provided path is within the configured roots.
```

--------------------------------

### Initialize MCP Client

Source: https://www.rubyllm-mcp.com/guides/getting-started.html

Creating a connection to an MCP server using stdio transport and verifying the connection status.

```ruby
client = RubyLLM::MCP.client(
  name: "my-first-server",
  transport_type: :stdio,
  config: {
    command: "npx",
    args: ["@modelcontextprotocol/server-filesystem", "/path/to/directory"]
  }
)

puts client.alive?
```

--------------------------------

### Registering Multiple Tools in RubyLLM

Source: https://www.rubyllm-mcp.com/getting-started/getting-started.html

Demonstrates how to initialize a chat session and register multiple tool sets from different clients. This allows the model to access a broader range of functions during the conversation.

```ruby
chat = RubyLLM.chat(model: "gpt-4")
chat.with_tools(*file_client.tools, *api_client.tools)

response = chat.ask("Read the config file and make an API call")
puts response
```

--------------------------------

### RubyLLM MCP Redirect URI Validation

Source: https://www.rubyllm-mcp.com/guides/oauth.html

Illustrates correct and incorrect examples of redirect URIs for OAuth authentication in RubyLLM MCP. It emphasizes the need for an exact match, including the protocol and absence of trailing slashes.

```ruby
# ✅ Correct
"http://localhost:8080/callback"

# ❌ Wrong
"http://localhost:8080/callback/"  # Trailing slash
"http://127.0.0.1:8080/callback"   # Different host
```

--------------------------------

### Use MCP Client in Rails Application

Source: https://www.rubyllm-mcp.com/guides/rails-oauth.html

Demonstrates how to initiate the MCP OAuth connection flow from the user's browser and how to use the `McpClient` within a background job to interact with MCP services using user-specific permissions.

```ruby
# User connects (browser-based)
# Visit: /mcp_connections/connect

# Background job (no browser)
class AiResearchJob < ApplicationJob
  def perform(user_id, query)
    user = User.find(user_id)
    client = McpClient.for(user)

    tools = client.tools
    chat = RubyLLM.chat(provider: "anthropic/claude-sonnet-4")
      .with_tools(*tools)

    response = chat.ask(query)
    # ... save results ...
  ensure
    client&.stop
  end
end
```

--------------------------------

### Configure Global Extensions in RubyLLM MCP

Source: https://www.rubyllm-mcp.com/configuration.html

Configures extensions globally for RubyLLM MCP. This example registers a UI extension with specific MIME types. It also shows a convenience helper to enable MCP Apps.

```ruby
RubyLLM::MCP.configure do |config|
  config.extensions.register(
    "io.modelcontextprotocol/ui",
    "mimeTypes" => ["text/html;profile=mcp-app"]
  )
end
```

```ruby
RubyLLM::MCP.configure do |config|
  config.extensions.enable_apps(
    "mimeTypes" => ["text/html;profile=mcp-app"]
  )
end
```

--------------------------------

### Implement Context-Aware Guards with Handler Options in Ruby

Source: https://www.rubyllm-mcp.com/client/sampling.html

This example shows a 'TenantSamplingHandler' that uses handler options for context-aware guards. It checks if the 'tenant_id' is present in the 'allowed_tenants' list before processing the request, rejecting unauthorized tenants.

```ruby
class TenantSamplingHandler < RubyLLM::MCP::Handlers::SamplingHandler
  option :allowed_tenants, default: []
  option :tenant_id, required: true

  def execute
    return reject("Tenant not authorized") unless allowed_tenant?

    response = default_chat_completion("gpt-4")
    accept(response)
  end

  private

  def allowed_tenant?
    options[:allowed_tenants].include?(options[:tenant_id])
  end
end

client.on_sampling(
  TenantSamplingHandler,
  tenant_id: current_tenant.id,
  allowed_tenants: ["tenant_a", "tenant_b"]
)

```

--------------------------------

### Update RubyLLM and RubyLLM-MCP Dependencies

Source: https://www.rubyllm-mcp.com/guides/upgrading-0.6-to-0.7.html

This code snippet shows how to update the RubyLLM and RubyLLM-MCP gems in your Gemfile to their required versions for RubyLLM::MCP 0.7.x. After updating the Gemfile, run `bundle update` to install the new versions.

```ruby
# Gemfile
gem 'ruby_llm', '~> 1.9'
gem 'ruby_llm-mcp', '~> 0.7'
```

```bash
bundle update ruby_llm ruby_llm-mcp
```

--------------------------------

### Subscribe to Resources

Source: https://www.rubyllm-mcp.com/server/resources.html

Demonstrates how to use the SmartResourceSubscriber to manage resource subscriptions within an MCP client.

```ruby
subscriber = SmartResourceSubscriber.new(client)
resource = subscriber.use_resource_with_subscription("live_metrics")
```

--------------------------------

### Initiate AI Research via MCP Controller

Source: https://www.rubyllm-mcp.com/guides/rails-integration.html

This Ruby on Rails controller action checks if the current user has an active MCP connection. If connected, it enqueues an AiResearchJob; otherwise, it redirects the user to the connection setup page.

```ruby
class ResearchController < ApplicationController
  def create
    if current_user.mcp_connected?
      AiResearchJob.perform_later(current_user.id, params[:query])
      redirect_to research_path, notice: "Research started!"
    else
      redirect_to connect_mcp_connections_path,
                  alert: "Please connect MCP server first"
    end
  end
end
```

--------------------------------

### Utilize MCP Tools and Resources in Chat

Source: https://www.rubyllm-mcp.com/getting-started/getting-started.html

Demonstrates how to fetch available tools and resources from an MCP client and integrate them into a RubyLLM chat session.

```ruby
# Using Tools
chat = RubyLLM.chat(model: "gpt-4")
chat.with_tools(*client.tools)
response = chat.ask("List the files in the current directory")

# Using Resources
chat.with_resource(client.resource("project_structure"))
response = chat.ask("What is the structure of this project?")
```

--------------------------------

### Rails Generator for RubyLLM::MCP Integration

Source: https://www.rubyllm-mcp.com/

Details the Rails generators provided by the RubyLLM::MCP gem for setting up the integration. This includes a general installation command and a specific generator for per-user OAuth flows, requiring a User model.

```ruby
rails generate ruby_llm:mcp:install

# For per-user OAuth flows:
rails generate ruby_llm:mcp:oauth:install User

```

--------------------------------

### RubyLLM MCP Argument Completion

Source: https://www.rubyllm-mcp.com/server/resources.html

Shows how to retrieve resource templates and get suggestions for completing partial argument values. This feature aids in dynamic user input or programmatic construction of resource queries by providing relevant options.

```ruby
# Get completion suggestions for template arguments
template = client.resource_template("user_logs")

# Complete a partial argument value
suggestions = template.complete("user_id", "123")
puts "Suggestions: #{suggestions.values}"
puts "Total matches: #{suggestions.total}"
puts "Has more: #{suggestions.has_more}"

# Use suggestions in your application
if suggestions.values.any?
  puts "Did you mean:"
  suggestions.values.each_with_index do |suggestion, index|
    puts "#{index + 1}. #{suggestion}"
  end
end
```

--------------------------------

### RubyLLM MCP Resource Subscription Best Practices

Source: https://www.rubyllm-mcp.com/server/resources.html

Provides guidance on efficient resource subscription management, including subscribing only to actively used resources and cleaning up unused subscriptions. This helps optimize performance and resource utilization.

```ruby
# Only subscribe to resources you actively use
class SmartResourceSubscriber
  def initialize(client)
    @client = client
    @active_resources = Set.new
  end

  def use_resource_with_subscription(resource_name)
    # Subscribe on first use
    unless @active_resources.include?(resource_name)
      resource = @client.resource(resource_name)

      if resource.subscribable?
        @client.subscribe_to_resource(resource_name)
        @active_resources.add(resource_name)
        puts "Auto-subscribed to #{resource_name}"
      end
    end

    @client.resource(resource_name)
  end

  def cleanup_unused_subscriptions
    # Unsubscribe from resources not used recently
    @client.subscribed_resources.each do |resource_name|
      unless @active_resources.include?(resource_name)
        @client.unsubscribe_from_resource(resource_name)
        puts "Auto-unsubscribed from unused resource: #{resource_name}"
      end
    end
  end
end
```

--------------------------------

### Get Task Results in RubyLLM::MCP

Source: https://www.rubyllm-mcp.com/server/tasks.html

This code demonstrates how to fetch the results of a completed task in RubyLLM::MCP. It first checks if the task is completed and then retrieves the payload using either `client.task_result` or the task object's `result` method.

```ruby
task = client.task_get("task-123")

if task.completed?
  payload = client.task_result(task.task_id)
  puts payload.dig("content", 0, "text")
end

payload = task.result

```

--------------------------------

### Basic Prompt Usage in a Chat Conversation

Source: https://www.rubyllm-mcp.com/server/prompts.html

Shows how to retrieve a prompt and use it with specific arguments to initiate a chat conversation, then ask a follow-up question.

```ruby
# Get a prompt
greeting_prompt = client.prompt("daily_greeting")

# Use prompt in a chat
chat = RubyLLM.chat(model: "gpt-4")
chat.with_prompt(greeting_prompt, arguments: {
  name: "Alice",
  time: "morning"
})

response = chat.ask("Continue with the greeting")
puts response
```

--------------------------------

### Direct Prompt Query

Source: https://www.rubyllm-mcp.com/server/prompts.html

Illustrates how to directly query an LLM using a prompt and its arguments without explicitly setting up a chat object first.

```ruby
# Ask using a prompt directly
chat = RubyLLM.chat(model: "gpt-4")
response = chat.ask_prompt(
  client.prompt("code_review"),
  arguments: {
    language: "ruby",
    focus: "security"
  }
)

puts response
```

--------------------------------

### JSON Schema Example for User Preferences

Source: https://www.rubyllm-mcp.com/client/elicitation.html

This JSON snippet defines a schema for capturing simple user preferences, including an enum for choices and a confidence score. It also shows the corresponding Ruby code to set a structured response that conforms to this schema.

```json
{
  "type": "object",
  "properties": {
    "preference": {
      "type": "string",
      "enum": ["option_a", "option_b", "option_c"]
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    }
  },
  "required": ["preference"]
}

```

```ruby
elicitation.structured_response = {
  "preference": "option_a",
  "confidence": 0.9
}
```

--------------------------------

### Configure RubyLLM MCP Initializer

Source: https://www.rubyllm-mcp.com/guides/rails-integration.html

Sets up global configuration for the RubyLLM MCP, including logging, filesystem roots, and sampling parameters.

```ruby
RubyLLM::MCP.configure do |config|
  config.log_level = Rails.env.production? ? Logger::WARN : Logger::INFO
  config.logger = Rails.logger
  config.config_path = Rails.root.join("config", "mcps.yml")
  config.roots = [Rails.root] if Rails.env.development?
  config.sampling.enabled = false
  config.sampling.preferred_model = "gpt-4"
  config.sampling.guard do |sample|
    true
  end
end
```

--------------------------------

### Async Approval via Websockets

Source: https://www.rubyllm-mcp.com/server/tools.html

Shows how to defer tool execution and request external approval via a websocket service, using a registry to finalize the decision.

```ruby
class WebsocketApprovalHandler < RubyLLM::MCP::Handlers::HumanInTheLoopHandler
  async_execution timeout: 300
  option :websocket_service, required: true
  option :user_id, required: true

  def execute
    options[:websocket_service].broadcast("approvals_#{options[:user_id]}", { type: "approval_request", id: approval_id, tool: tool_name, parameters: parameters })
    defer
  end
end
```

--------------------------------

### Check Resource Type (Ruby)

Source: https://www.rubyllm-mcp.com/server/resources.html

This Ruby code snippet checks if a given resource URI starts with 'temp://' to determine if it's a temporary or persistent resource. It assumes a 'client' object with a 'resource' method and that resources have a 'uri' attribute with a 'start_with?' method.

```Ruby
resource = client.resource("generated_report")
if resource.uri.start_with?("temp://")
  puts "This is a temporary resource"
else
  puts "This is a persistent resource"
end
```

--------------------------------

### Action Cable Integration for Async Elicitation

Source: https://www.rubyllm-mcp.com/client/elicitation.html

Provides a complete example of integrating asynchronous elicitation with Action Cable. The `ActionCableElicitationHandler` broadcasts new elicitation requests to a user's specific channel. The `execute` method returns `:pending`, indicating that the response will be handled asynchronously.

```Ruby
# app/handlers/action_cable_elicitation_handler.rb
class ActionCableElicitationHandler < RubyLLM::MCP::Handlers::ElicitationHandler
  async_execution timeout: 300

  option :user_id, required: true

  def execute
    # Broadcast to user's channel
    ActionCable.server.broadcast(
      "elicitation_#{options[:user_id]}",
      {
        type: "new_elicitation",
        id: elicitation.id,
        message: elicitation.message,
        schema: elicitation.requested_schema,
        expires_at: 5.minutes.from_now
      }
    )

    :pending
  end
end
```

--------------------------------

### Implement Advanced MCP Job with Progress Tracking

Source: https://www.rubyllm-mcp.com/guides/rails-integration.html

Demonstrates how to run an MCP task within a background job, including setting up progress tracking via ActionCable and configuring user-specific file system roots. It ensures tasks are executed with appropriate context and notifies the user upon completion.

```ruby
class AdvancedMCPJob < ApplicationJob
  include Rails.application.routes.url_helpers

  def perform(user_id, task_params)
    user = User.find(user_id)

    RubyLLM::MCP.establish_connection do |clients|
      setup_progress_tracking(clients, user)
      configure_user_roots(clients, user)
      result = execute_mcp_task(clients, task_params)
      notify_completion(user, result)
    end
  end

  private

  def setup_progress_tracking(clients, user)
    clients.each do |client|
      client.on_progress do |progress|
        ActionCable.server.broadcast("user_#{user.id}_progress", { progress: progress.progress, message: progress.message })
      end
    end
  end

  def configure_user_roots(clients, user)
    user.projects.each do |project|
      clients.each { |client| client.roots.add(project.path) }
    end
  end

  def execute_mcp_task(clients, params)
    chat = RubyLLM.chat(model: params[:model] || "gpt-4")
    chat.with_tools(*clients.tools)
    chat.with_resource(get_user_context_resource(clients))
    chat.ask(params[:query])
  end

  def get_user_context_resource(clients)
    clients.first.resource("user_preferences")
  end

  def notify_completion(user, result)
    UserMailer.mcp_task_completed(user, result).deliver_now
  end
end
```

--------------------------------

### Handle Elicitation Object and Validate Response in RubyLLM::MCP

Source: https://www.rubyllm-mcp.com/client/elicitation.html

This example illustrates how to interact with the `elicitation` object within a RubyLLM::MCP client's callback. It shows how to access the server's message and the requested JSON schema, construct a structured response that conforms to the schema, and set it on the `elicitation` object. The code also demonstrates how to manually validate the response against the schema before accepting or rejecting the elicitation.

```ruby
client.on_elicitation do |elicitation|
  puts "Server says: #{elicitation.message}"

  # Examine the requested schema
  schema = elicitation.requested_schema
  puts "Expected format: #{schema}"

  # Create a response that matches the schema
  response = {
    "user_choice": "option_a",
    "confidence": 0.8,
    "reasoning": "This option seems most appropriate"
  }

  # Set the response
  elicitation.structured_response = response

  # Validation happens automatically, but you can check manually
  if elicitation.validate_response
    puts "Response is valid"
    true  # Accept the elicitation
  else
    puts "Response is invalid"
    false  # Reject the elicitation
  end
end

```
Tokens:
Raw