RubyLLM::MCP MCP server
Commit Oct 8, 2026Enables Ruby and RubyLLM applications to use MCP tools, resources, and prompts via stdio, streamable HTTP, or SSE.
Also known as patvice/ruby_llm-mcp, ruby-llm-mcp
- Stars
- 269
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 8, 2026
- License
- MIT
What is RubyLLM::MCP MCP?
RubyLLM::MCP enables Ruby and RubyLLM applications to use MCP tools, resources, and prompts via stdio, streamable HTTP, or SSE.
Summary generated from the project's README
About RubyLLM::MCP MCP server
Integrating Model Context Protocol capabilities into Ruby and RubyLLM applications is the primary function of this gem. It allows developers to connect their AI chat workflows to external tools, resources, and prompts using stdio, streamable HTTP, or SSE transports. The client is designed to be spec compliant, supporting the stable 2025-06-18 protocol by default while offering an opt-in for the 2026-01-26 draft.
Developers can use this in various environments, including standard Ruby apps, background jobs, or Rails projects. It features comprehensive OAuth 2.1 authentication support, including PKCE and automatic token refresh, with specific setup paths for per-user connections in Rails or browser-based flows for CLI tools. The library provides built-in handlers for real-time progress tracking and logging, making it suitable for interactive workflows that require monitoring task completion or system messages.
What you can do with it
- 1Automate filesystem analysisAsk an AI client to find and summarize specific files within a local directory using filesystem tools.
- 2Incorporate external documentationProvide an AI model with specific resources like release notes to generate summaries for a team.
- 3Manage secure user connectionsConnect Rails applications to MCP servers using per-user OAuth authentication.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablepatvice/ruby_llm-mcp is public and reachablegithub.com/patvice/ruby_llm-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-08github.com/patvice/ruby_llm-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMCP for Ruby and RubyLLM, as easy as possible.
RubyLLM::MCP is a Ruby client for the Model Context Protocol (MCP), built to work cleanly with RubyLLM. Aiming to be completely spec compliant.
Use MCP tools, resources, and prompts from your RubyLLM chats over stdio, streamable HTTP, or SSE.
Protocol support: Fully supports MCP spec 2025-06-18 (stable), with draft spec 2026-01-26 available.
RubyLLM::MCP Out of the Box
Our goal is to be able to plug MCP into Ruby/RubyLLM apps as easily as possible.
RubyLLM::MCP gives you that:
- Ruby-first API for using MCP tools, resources, and prompts directly in RubyLLM chat workflows
- Stable protocol track by default (
2025-06-18), with opt-in draft track (2026-01-26) - Built-in notification and response handlers for real-time and interactive workflows
- MCP OAuth 2.1 authentication support (PKCE, dynamic registration, discovery, and automatic token refresh)
- OAuth setup paths for Rails apps (per-user connections) and browser-based CLI flows
- Straightforward integration for any Ruby app, background job, or Rails project using RubyLLM
Show me the code
# Basic setup
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 Ruby files modified today and summarize what changed.")
# Resources
resource = client.resource("release_notes")
chat = RubyLLM.chat(model: "gpt-4.1-mini")
chat.with_resource(resource)
puts chat.ask("Summarize release notes for the team in 5 bullet points.")
# Prompts
prompt = client.prompt("code_review")
chat = RubyLLM.chat(model: "gpt-4.1-mini")
response = chat.ask_prompt(
prompt,
arguments: {
language: "ruby",
focus: "security"
}
)
puts response
# 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
# 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
Features
- Tools: Convert MCP tools into RubyLLM-compatible tools
- Resources: Work with resources and resource templates in chat context
- Prompts: Execute server prompts with typed arguments
- Transports:
:stdio,:streamable, and:sse - Client capabilities: Sampling, roots, progress tracking, and elicitation
- Handlers: Built-in notification and response handlers for real-time and interactive workflows
- MCP Authentication: OAuth 2.1 support with PKCE, dynamic registration, discovery, and automatic token refresh
- OAuth setup paths: Rails per-user OAuth setup and browser-based OAuth for CLI tools
- Extensions: Global/per-client extension negotiation, including MCP Apps
- Multi-client support: Manage multiple MCP servers in one workflow
- Protocol control: Stable default with explicit draft opt-in
- Adapters: Native
:ruby_llmadapter (full feature set) and optional:mcp_sdk
Installation
Add to your Gemfile:
gem "ruby_llm-mcp"
Then run:
bundle install
If you want the official SDK adapter, also add:
gem "mcp", "~> 0.7"
Rails
rails generate ruby_llm:mcp:install
For OAuth-based user connections:
rails generate ruby_llm:mcp:oauth:install User
OAuth quick example:
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
Then use explicit connection blocks in jobs/controllers/services:
RubyLLM::MCP.establish_connection do |clients|
chat = RubyLLM.chat(model: "gpt-4.1-mini")
chat.with_tools(*clients.tools)
chat.ask("Analyze this pull request and list risks.")
end
Documentation
Contributing
Issues and pull requests are welcome at patvice/ruby_llm-mcp.
License
Released under the MIT License.
RubyLLM::MCP MCP questions
Does it support OAuth authentication?
Yes, it includes MCP OAuth 2.1 support featuring PKCE, dynamic registration, discovery, and automatic token refresh.
Can I use this in a Rails application?
Yes, it provides OAuth setup paths for Rails apps for per-user connections and a dedicated installation generator.