Skip to content
Back to search

fast-mcp

A Ruby Implementation of the Model Context Protocol

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yjacquin--fast-mcp/badge.svg)](/listings/yjacquin--fast-mcp)

HTML

<a href="/listings/yjacquin--fast-mcp"><img src="/api/listings/yjacquin--fast-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Create a Server with Tools and Resources and STDIO transport

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.start

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 449 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Fast MCP 🚀
  2. <div align="center">
  3. <h3>Connect AI models to your Ruby applications with ease</h3>
  4. <p>No complex protocols, no integration headaches, no compatibility issues – just beautiful, expressive Ruby code.</p>
  5. </div>
  6. <p align="center">
  7. <a href="https://badge.fury.io/rb/fast-mcp"><img src="https://badge.fury.io/rb/fast-mcp.svg" alt="Gem Version" /></a>
  8. <a href="https://github.com/yjacquin/fast-mcp/workflows/CI/badge.svg"><img src="https://github.com/yjacquin/fast-mcp/workflows/CI/badge.svg" alt="CI Status" /></a>
  9. <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
  10. <a href="code_of_conduct.md"><img src="https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg" alt="Contributor Covenant" /></a>
  11. <a href="https://discord.gg/9HHfAtY3HF"><img src = "https://dcbadge.limes.pink/api/server/https://discord.gg/9HHfAtY3HF?style=flat" alt="Discord invite link" /></a>
  12. </p>
  13. ## 🌟 Interface your Servers with LLMs in minutes
  14. AI models are powerful, but they need to interact with your applications to be truly useful. Traditional approaches mean wrestling with:
  15. - 🔄 Complex communication protocols and custom JSON formats
  16. - 🔌 Integration challenges with different model providers
  17. - 🧩 Compatibility issues between your app and AI tools
  18. - 🧠 Managing the state between AI interactions and your data
  19. Fast MCP solves all these problems by providing a clean, Ruby-focused implementation of the [Model Context Protocol](https://github.com/modelcontextprotocol), making AI integration a joy, not a chore.
  20. ## ✨ Features
  21. - 🛠️ **Tools API** - Let AI models call your Ruby functions securely, with in-depth argument validation through [Dry-Schema](https://github.com/dry-rb/dry-schema).
  22. - 📚 **Resources API** - Share data between your app and AI models
  23. - 🔄 **Multiple Transports** - Choose from STDIO, HTTP, or SSE based on your needs
  24. - 🧩 **Framework Integration** - Works seamlessly with Rails, Sinatra or any Rack app.
  25. - 🔒 **Authentication Support** - Secure your AI-powered endpoints with ease
  26. - 🚀 **Real-time Updates** - Subscribe to changes for interactive applications
  27. - 🎯 **Dynamic Filtering** - Control tool/resource access based on request context (permissions, API versions, etc.)
  28. ## 💎 What Makes FastMCP Great
  29. ```ruby
  30. # Define tools for AI models to use
  31. server = FastMcp::Server.new(name: 'popular-users', version: '1.0.0')
  32. # Define a tool by inheriting from FastMcp::Tool
  33. class CreateUserTool < FastMcp::Tool
  34. description "Create a user"
  35. # These arguments will generate the needed JSON to be presented to the MCP Client
  36. # And they will be validated at run time.
  37. # The validation is based off Dry-Schema, with the addition of the description.
  38. arguments do
  39. required(:first_name).filled(:string).description("First name of the user")
  40. optional(:age).filled(:integer).description("Age of the user")
  41. required(:address).description("The shipping address").hash do
  42. required(:street).filled(:string).description("Street address")
  43. optional(:city).filled(:string).description("City name")
  44. optional(:zipcode).maybe(:string).description("Postal code")
  45. end
  46. end
  47. def call(first_name:, age: nil, address: {})
  48. User.create!(first_name:, age:, address:)
  49. end
  50. end
  51. # Register the tool with the server
  52. server.register_tool(CreateUserTool)
  53. # Share data resources with AI models by inheriting from FastMcp::Resource
  54. class PopularUsers < FastMcp::Resource
  55. uri "myapp:///users/popular"
  56. resource_name "Popular Users"
  57. mime_type "application/json"
  58. def content
  59. JSON.generate(User.popular.limit(5).as_json)
  60. end
  61. end
  62. class User < FastMcp::Resource
  63. uri "myapp:///users/{id}" # This is a resource template
  64. resource_name "user"
  65. mime_type "application/json"
  66. def content
  67. id = params[:id] # params are computed from the uri pattern
  68. JSON.generate(User.find(id).as_json)
  69. end
  70. end
  71. # Register the resource with the server
  72. server.register_resources(PopularUsers, User)
  73. # Accessing the resource through the server
  74. server.read_resource(PopularUsers.uri)
  75. # Notify the resource content has been updated to clients
  76. server.notify_resource_updated(PopularUsers.variabilized_uri)
  77. # Notifiy the content of a resource from a template has been updated to clients
  78. server.notify_resource_updated(User.variabilized_uri(id: 1))
  79. ```
  80. ### 🎯 Dynamic Tool Filtering
  81. Control which tools and resources are available based on request context:
  82. ```ruby
  83. # Tag your tools for easy filtering
  84. class AdminTool < FastMcp::Tool
  85. tags :admin, :dangerous
  86. description "Perform admin operations"
  87. def call
  88. # Admin only functionality
  89. end
  90. end
  91. # Filter tools based on user permissions
  92. server.filter_tools do |request, tools|
  93. user_role = request.params['role']
  94. case user_role
  95. when 'admin'
  96. tools # Admins see all tools
  97. when 'user'
  98. tools.reject { |t| t.tags.include?(:admin) }
  99. else
  100. tools.select { |t| t.tags.include?(:public) }
  101. end
  102. end
  103. ```
  104. ### 🚂 Fast Ruby on Rails implementation
  105. ```shell
  106. bundle add fast-mcp
  107. bin/rails generate fast_mcp:install
  108. ```
  109. This will add a configurable `fast_mcp.rb` initializer
  110. ```ruby
  111. require 'fast_mcp'
  112. FastMcp.mount_in_rails(
  113. Rails.application,
  114. name: Rails.application.class.module_parent_name.underscore.dasherize,
  115. version: '1.0.0',
  116. path_prefix: '/mcp', # This is the default path prefix
  117. messages_route: 'messages', # This is the default route for the messages endpoint
  118. sse_route: 'sse', # This is the default route for the SSE endpoint
  119. # Add allowed origins below, it defaults to Rails.application.config.hosts
  120. # allowed_origins: ['localhost', '127.0.0.1', 'example.com', /.*\.example\.com/],
  121. # localhost_only: true, # Set to false to allow connections from other hosts
  122. # whitelist specific ips to if you want to run on localhost and allow connections from other IPs
  123. # allowed_ips: ['127.0.0.1', '::1']
  124. # authenticate: true, # Uncomment to enable authentication
  125. # auth_token: 'your-token' # Required if authenticate: true
  126. ) do |server|
  127. Rails.application.config.after_initialize do
  128. # FastMcp will automatically discover and register:
  129. # - All classes that inherit from ApplicationTool (which uses ActionTool::Base)
  130. # - All classes that inherit from ApplicationResource (which uses ActionResource::Base)
  131. server.register_tools(*ApplicationTool.descendants)
  132. server.register_resources(*ApplicationResource.descendants)
  133. # alternatively, you can register tools and resources manually:
  134. # server.register_tool(MyTool)
  135. # server.register_resource(MyResource)
  136. end
  137. end
  138. ```
  139. The install script will also:
  140. - add app/resources folder
  141. - add app/tools folder
  142. - add app/tools/sample_tool.rb
  143. - add app/resources/sample_resource.rb
  144. - add ApplicationTool to inherit from
  145. - add ApplicationResource to inherit from as well
  146. #### Rails-friendly class naming conventions
  147. For Rails applications, FastMCP provides Rails-style class names to better fit with Rails conventions:
  148. - `ActionTool::Base` - An alias for `FastMcp::Tool`
  149. - `ActionResource::Base` - An alias for `FastMcp::Resource`
  150. These are automatically set up in Rails applications. You can use either naming convention in your code:
  151. ```ruby
  152. # Using Rails-style naming:
  153. class MyTool < ActionTool::Base
  154. description "My awesome tool"
  155. arguments do
  156. required(:input).filled(:string)
  157. end
  158. def call(input:)
  159. # Your implementation
  160. end
  161. end
  162. # Using standard FastMcp naming:
  163. class AnotherTool < FastMcp::Tool
  164. # Both styles work interchangeably in Rails apps
  165. end
  166. ```
  167. When creating new tools or resources, the generators will use the Rails naming convention by default:
  168. ```ruby
  169. # app/tools/application_tool.rb
  170. class ApplicationTool < ActionTool::Base
  171. # Base methods for all tools
  172. end
  173. # app/resources/application_resource.rb
  174. class ApplicationResource < ActionResource::Base
  175. # Base methods for all resources
  176. end
  177. ```
  178. ### Easy Sinatra setup
  179. I'll let you check out the dedicated [sinatra integration docs](./docs/sinatra_integration.md).
  180. ## 🚀 Quick Start
  181. ### Create a Server with Tools and Resources and STDIO transport
  182. ```ruby
  183. require 'fast_mcp'
  184. # Create an MCP server
  185. server = FastMcp::Server.new(name: 'my-ai-server', version: '1.0.0')
  186. # Define a tool by inheriting from FastMcp::Tool
  187. class SummarizeTool < FastMcp::Tool
  188. description "Summarize a given text"
  189. arguments do
  190. required(:text).filled(:string).description("Text to summarize")
  191. optional(:max_length).filled(:integer).description("Maximum length of summary")
  192. end
  193. def call(text:, max_length: 100)
  194. # Your summarization logic here
  195. text.split('.').first(3).join('.') + '...'
  196. end
  197. end
  198. # Register the tool with the server
  199. server.register_tool(SummarizeTool)
  200. # Create a resource by inheriting from FastMcp::Resource
  201. class StatisticsResource < FastMcp::Resource
  202. uri "data/statistics"
  203. resource_name "Usage Statistics"
  204. description "Current system statistics"
  205. mime_type "application/json"
  206. def content
  207. JSON.generate({
  208. users_online: 120,
  209. queries_per_minute: 250,
  210. popular_topics: ["Ruby", "AI", "WebDev"]
  211. })
  212. end
  213. end
  214. # Register the resource with the server
  215. server.register_resource(StatisticsResource)
  216. # Start the server
  217. server.start
  218. ```
  219. ## 🧪 Testing with the inspector
  220. MCP has developed a very [useful inspector](https://github.com/modelcontextprotocol/inspector).
  221. You can use it to validate your implementation. I suggest you use the examples I provided with this project as an easy boilerplate.
  222. Clone this project, then give it a go !
  223. ```shell
  224. npx @modelcontextprotocol/inspector examples/server_with_stdio_transport.rb
  225. ```
  226. Or to test with an SSE transport using a rack middleware:
  227. ```shell
  228. npx @modelcontextprotocol/inspector examples/rack_middleware.rb
  229. ```
  230. Or to test over SSE with an authenticated rack middleware:
  231. ```shell
  232. npx @modelcontextprotocol/inspector examples/authenticated_rack_middleware.rb
  233. ```
  234. You can test your custom implementation with the official MCP inspector by using:
  235. ```shell
  236. # Test with a stdio transport:
  237. npx @modelcontextprotocol/inspector path/to/your_ruby_file.rb
  238. # Test with an HTTP / SSE server. In the UI select SSE and input your address.
  239. npx @modelcontextprotocol/inspector
  240. ```
  241. #### Sinatra
  242. ```ruby
  243. # app.rb
  244. require 'sinatra'
  245. require 'fast_mcp'
  246. use FastMcp::RackMiddleware.new(name: 'my-ai-server', version: '1.0.0') do |server|
  247. # Register tools and resources here
  248. server.register_tool(SummarizeTool)
  249. end
  250. get '/' do
  251. 'Hello World!'
  252. end
  253. ```
  254. ### Integrating with Claude Desktop
  255. Add your server to your Claude Desktop configuration at:
  256. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  257. - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  258. ```json
  259. {
  260. "mcpServers": {
  261. "my-great-server": {
  262. "command": "ruby",
  263. "args": ["/Users/path/to/your/awesome/fast-mcp/server.rb"]
  264. }
  265. }
  266. }
  267. ```
  268. ## How to add a MCP server to Claude, Cursor, or other MCP clients?
  269. Please refer to [configuring_mcp_clients](docs/configuring_mcp_clients.md)
  270. ## 📊 Supported Specifications
  271. | Feature | Status |
  272. | ----------------------------------------------- | --------------------------------------------------------- |
  273. | ✅ **JSON-RPC 2.0** | Full implementation for communication |
  274. | ✅ **Tool Definition & Calling** | Define and call tools with rich argument types |
  275. | ✅ **Resource & Resource Templates Management** | Create, read, update, and subscribe to resources |
  276. | ✅ **Transport Options** | STDIO, HTTP, and SSE for flexible integration |
  277. | ✅ **Framework Integration** | Rails, Sinatra, Hanami, and any Rack-compatible framework |
  278. | ✅ **Authentication** | Secure your AI endpoints with token authentication |
  279. | ✅ **Schema Support** | Full JSON Schema for tool arguments with validation |
  280. ## 🗺️ Use Cases
  281. - 🤖 **AI-powered Applications**: Connect LLMs to your Ruby app's functionality
  282. - 📊 **Real-time Dashboards**: Build dashboards with live AI-generated insights
  283. - 🔗 **Microservice Communication**: Use MCP as a clean protocol between services
  284. - 📚 **Interactive Documentation**: Create AI-enhanced API documentation
  285. - 💬 **Chatbots and Assistants**: Build AI assistants with access to your app's data
  286. ## 🔒 Security Features
  287. Fast MCP includes built-in security features to protect your applications:
  288. ### DNS Rebinding Protection
  289. 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.
  290. ```ruby
  291. # Configure allowed origins (defaults to ['localhost', '127.0.0.1'])
  292. FastMcp.rack_middleware(app,
  293. allowed_origins: ['localhost', '127.0.0.1', 'your-domain.com', /.*\.your-domain\.com/],
  294. localhost_only: false,
  295. allowed_ips: ['192.168.1.1', '10.0.0.1'],
  296. # other options...
  297. )
  298. ```
  299. ### Authentication
  300. Fast MCP supports token-based authentication for all connections:
  301. ```ruby
  302. # Enable authentication
  303. FastMcp.authenticated_rack_middleware(app,
  304. auth_token: 'your-secret-token',
  305. # other options...
  306. )
  307. ```
  308. ## 📖 Documentation
  309. - [🚀 Getting Started Guide](docs/getting_started.md)
  310. - [🧩 Integration Guide](docs/integration_guide.md)
  311. - [🛤️ Rails Integration](docs/rails_integration.md)
  312. - [🌐 Sinatra Integration](docs/sinatra_integration.md)
  313. - [📚 Resources](docs/resources.md)
  314. - [🛠️ Tools](docs/tools.md)
  315. - [🔒 Security](docs/security.md)
  316. - [🎯 Dynamic Filtering](docs/filtering.md)
  317. ## 💻 Examples
  318. Check out the [examples directory](examples) for more detailed examples:
  319. - **🔨 Basic Examples**:
  320. - [Simple Server](examples/server_with_stdio_transport.rb)
  321. - [Tool Examples](examples/tool_examples.rb)
  322. - **🌐 Web Integration**:
  323. - [Rack Middleware](examples/rack_middleware.rb)
  324. - [Authenticated Endpoints](examples/authenticated_rack_middleware.rb)
  325. ## 🧪 Requirements
  326. - Ruby 3.2+
  327. ## 👥 Contributing
  328. We welcome contributions to Fast MCP! Here's how you can help:
  329. 1. Fork the repository
  330. 2. Create your feature branch (`git checkout -b my-new-feature`)
  331. 3. Commit your changes (`git commit -am 'Add some feature'`)
  332. 4. Push to the branch (`git push origin my-new-feature`)
  333. 5. Create a new Pull Request
  334. Please read our [Contributing Guide](CONTRIBUTING.md) for more details.
  335. ## 📄 License
  336. This project is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
  337. ## 🙏 Acknowledgments
  338. - The [Model Context Protocol](https://github.com/modelcontextprotocol) team for creating the specification
  339. - The [Dry-Schema](https://github.com/dry-rb/dry-schema) team for the argument validation.
  340. - All contributors to this project

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.