
A Ruby Implementation of the Model Context Protocol
A Ruby Implementation of the Model Context Protocol
·
No complex protocols, no integration headaches, no compatibility issues – just beautiful, expressive Ruby code.
AI models are powerful, but they need to interact with your applications to be truly useful. Traditional approaches mean wrestling with:
Fast MCP solves all these problems by providing a clean, Ruby-focused implementation of the Model Context Protocol, making AI integration a joy, not a chore.
# Define tools for AI models to use
server = FastMcp::Server.new(name: 'popular-users', version: '1.0.0')
# Define a tool by inheriting from FastMcp::Tool
class CreateUserTool < FastMcp::Tool
description "Create a user"
# These arguments will generate the needed JSON to be presented to the MCP Client
# And they will be validated at run time.
# The validation is based off Dry-Schema, with the addition of the description.
arguments do
required(:first_name).filled(:string).description("First name of the user")
optional(:age).filled(:integer).description("Age of the user")
required(:address).description("The shipping address").hash do
required(:street).filled(:string).description("Street address")
optional(:city).filled(:string).description("City name")
optional(:zipcode).maybe(:string).description("Postal code")
end
end
def call(first_name:, age: nil, address: {})
User.create!(first_name:, age:, address:)
end
end
# Register the tool with the server
server.register_tool(CreateUserTool)
# Share data resources with AI models by inheriting from FastMcp::Resource
class PopularUsers < FastMcp::Resource
uri "myapp:///users/popular"
resource_name "Popular Users"
mime_type "application/json"
def content
JSON.generate(User.popular.limit(5).as_json)
end
end
class User < FastMcp::Resource
uri "myapp:///users/{id}" # This is a resource template
resource_name "user"
mime_type "application/json"
def content
id = params[:id] # params are computed from the uri pattern
JSON.generate(User.find(id).as_json)
end
end
# Register the resource with the server
server.register_resources(PopularUsers, User)
# Accessing the resource through the server
server.read_resource(PopularUsers.uri)
# Notify the resource content has been updated to clients
server.notify_resource_updated(PopularUsers.variabilized_uri)
# Notifiy the content of a resource from a template has been updated to clients
server.notify_resource_updated(User.variabilized_uri(id: 1))Control which tools and resources are available based on request context:
# Tag your tools for easy filtering
class AdminTool < FastMcp::Tool
tags :admin, :dangerous
description "Perform admin operations"
def call
# Admin only functionality
end
end
# Filter tools based on user permissions
server.filter_tools do |request, tools|
user_role = request.params['role']
case user_role
when 'admin'
tools # Admins see all tools
when 'user'
tools.reject { |t| t.tags.include?(:admin) }
else
tools.select { |t| t.tags.include?(:public) }
end
endbundle add fast-mcp
bin/rails generate fast_mcp:installThis will add a configurable fast_mcp.rb initializer
require 'fast_mcp'
FastMcp.mount_in_rails(
Rails.application,
name: Rails.application.class.module_parent_name.underscore.dasherize,
version: '1.0.0',
path_prefix: '/mcp', # This is the default path prefix
messages_route: 'messages', # This is the default route for the messages endpoint
sse_route: 'sse', # This is the default route for the SSE endpoint
# Add allowed origins below, it defaults to Rails.application.config.hosts
# allowed_origins: ['localhost', '127.0.0.1', 'example.com', /.*\.example\.com/],
# localhost_only: true, # Set to false to allow connections from other hosts
# whitelist specific ips to if you want to run on localhost and allow connections from other IPs
# allowed_ips: ['127.0.0.1', '::1']
# authenticate: true, # Uncomment to enable authentication
# auth_token: 'your-token' # Required if authenticate: true
) do |server|
Rails.application.config.after_initialize do
# FastMcp will automatically discover and register:
# - All classes that inherit from ApplicationTool (which uses ActionTool::Base)
# - All classes that inherit from ApplicationResource (which uses ActionResource::Base)
server.register_tools(*ApplicationTool.descendants)
server.register_resources(*ApplicationResource.descendants)
# alternatively, you can register tools and resources manually:
# server.register_tool(MyTool)
# server.register_resource(MyResource)
end
endThe install script will also:
For Rails applications, FastMCP provides Rails-style class names to better fit with Rails conventions:
ActionTool::Base - An alias for FastMcp::ToolActionResource::Base - An alias for FastMcp::ResourceThese are automatically set up in Rails applications. You can use either naming convention in your code:
# Using Rails-style naming:
class MyTool < ActionTool::Base
description "My awesome tool"
arguments do
required(:input).filled(:string)
end
def call(input:)
# Your implementation
end
end
# Using standard FastMcp naming:
class AnotherTool < FastMcp::Tool
# Both styles work interchangeably in Rails apps
endWhen creating new tools or resources, the generators will use the Rails naming convention by default:
# app/tools/application_tool.rb
class ApplicationTool < ActionTool::Base
# Base methods for all tools
end
# app/resources/application_resource.rb
class ApplicationResource < ActionResource::Base
# Base methods for all resources
endI'll let you check out the dedicated sinatra integration docs.
require 'fast_mcp'
# Create an MCP server
server = FastMcp::Server.new(name: 'my-ai-server', version: '1.0.0')
# Define a tool by inheriting from FastMcp::Tool
class SummarizeTool < FastMcp::Tool
description "Summarize a given text"
arguments do
required(:text).filled(:string).description("Text to summarize")
optional(:max_length).filled(:integer).description("Maximum length of summary")
end
def call(text:, max_length: 100)
# Your summarization logic here
text.split('.').first(3).join('.') + '...'
end
end
# Register the tool with the server
server.register_tool(SummarizeTool)
# Create a resource by inheriting from FastMcp::Resource
class StatisticsResource < FastMcp::Resource
uri "data/statistics"
resource_name "Usage Statistics"
description "Current system statistics"
mime_type "application/json"
def content
JSON.generate({
users_online: 120,
queries_per_minute: 250,
popular_topics: ["Ruby", "AI", "WebDev"]
})
end
end
# Register the resource with the server
server.register_resource(StatisticsResource)
# Start the server
server.startMCP has developed a very useful inspector. You can use it to validate your implementation. I suggest you use the examples I provided with this project as an easy boilerplate. Clone this project, then give it a go !
npx @modelcontextprotocol/inspector examples/server_with_stdio_transport.rbOr to test with an SSE transport using a rack middleware:
npx @modelcontextprotocol/inspector examples/rack_middleware.rbOr to test over SSE with an authenticated rack middleware:
npx @modelcontextprotocol/inspector examples/authenticated_rack_middleware.rbYou can test your custom implementation with the official MCP inspector by using:
# Test with a stdio transport:
npx @modelcontextprotocol/inspector path/to/your_ruby_file.rb
# Test with an HTTP / SSE server. In the UI select SSE and input your address.
npx @modelcontextprotocol/inspector# app.rb
require 'sinatra'
require 'fast_mcp'
use FastMcp::RackMiddleware.new(name: 'my-ai-server', version: '1.0.0') do |server|
# Register tools and resources here
server.register_tool(SummarizeTool)
end
get '/' do
'Hello World!'
endAdd your server to your Claude Desktop configuration at:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json{
"mcpServers": {
"my-great-server": {
"command": "ruby",
"args": ["/Users/path/to/your/awesome/fast-mcp/server.rb"]
}
}
}Please refer to configuring_mcp_clients
| Feature | Status |
|---|---|
| ✅ JSON-RPC 2.0 | Full implementation for communication |
| ✅ Tool Definition & Calling | Define and call tools with rich argument types |
| ✅ Resource & Resource Templates Management | Create, read, update, and subscribe to resources |
| ✅ Transport Options | STDIO, HTTP, and SSE for flexible integration |
| ✅ Framework Integration | Rails, Sinatra, Hanami, and any Rack-compatible framework |
| ✅ Authentication | Secure your AI endpoints with token authentication |
| ✅ Schema Support | Full JSON Schema for tool arguments with validation |
Fast MCP includes built-in security features to protect your applications:
The HTTP/SSE transport validates the Origin header on all incoming connections to prevent DNS rebinding attacks, which could allow malicious websites to interact with local MCP servers.
# Configure allowed origins (defaults to ['localhost', '127.0.0.1'])
FastMcp.rack_middleware(app,
allowed_origins: ['localhost', '127.0.0.1', 'your-domain.com', /.*\.your-domain\.com/],
localhost_only: false,
allowed_ips: ['192.168.1.1', '10.0.0.1'],
# other options...
)Fast MCP supports token-based authentication for all connections:
# Enable authentication
FastMcp.authenticated_rack_middleware(app,
auth_token: 'your-secret-token',
# other options...
)Check out the examples directory for more detailed examples:
🔨 Basic Examples:
🌐 Web Integration:
We welcome contributions to Fast MCP! Here's how you can help:
git checkout -b my-new-feature)git commit -am 'Add some feature')git push origin my-new-feature)Please read our Contributing Guide for more details.
This project is available as open source under the terms of the MIT License.
Pick your client and paste the snippet. Each one is the same server, written the way that client expects it.
claude mcp add my-great-server -- ruby /Users/path/to/your/awesome/fast-mcp/server.rb{
"mcpServers": {
"my-great-server": {
"args": [
"/Users/path/to/your/awesome/fast-mcp/server.rb"
],
"command": "ruby"
}
}
}code --add-mcp '{"name":"my-great-server","args":["/Users/path/to/your/awesome/fast-mcp/server.rb"],"command":"ruby"}'[mcp_servers.my-great-server]
command = "ruby"
args = ["/Users/path/to/your/awesome/fast-mcp/server.rb"]Runs locally on your device. Your client starts the server itself, so nothing has to be hosted.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/fast-mcp to learn what the "Fast MCP" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
npx @modelcontextprotocol/inspector examples/server_with_stdio_transport.rb
npx @modelcontextprotocol/inspector examples/rack_middleware.rb
npx @modelcontextprotocol/inspector examples/authenticated_rack_middleware.rb
npx @modelcontextprotocol/inspector path/to/your_ruby_file.rb
npx @modelcontextprotocol/inspectorThis server runs locally, so we can't read its tool list over the web yet.
We could not run this server: it ships no npx package for our sandbox and no public endpoint. The four checks that need a live server are left out, and the grade tops out at B until one exists.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/fast-mcp)Nothing comparable is listed yet.
v1.6.0Release notesv1.5.0Release notesv1.4.0Release notesv1.3.2Release notesv1.3.1Release notesv1.3.0Release notesv1.2.0Release notesv1.1.0Release notesv1.0.0Release notesv0.1.0Release notesConnect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "fast-mcp" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.