rails_mcp_engine

Rails MCP Engine provides a unified tool-definition pipeline for Rails 8 applications. It scans service classes under Tools::, which declare Sorbet-typed signatures and metadata, and automatically generates both RubyLLM and FastMCP tool wrappers at boot. This means you can define business logic as simple service objects, and at runtime you’ll have accessible tools for an LLM workflow and for MCP-based conversations. The engine also exposes a built-in MetaToolService you can query to list, inspect, and run registered tools, making it easy to explore what tools are available and invoke them from Ruby or via the MCP interfaces.

To use the MCP capabilities, run your Rails app with the engine included. You can access the Playground at /rails_mcp_engine/playground to dynamically register tool services, test JSON arguments, and view tool schemas. The Chat interface at /rails_mcp_engine/chat lets you converse with an OpenAI model (e.g., gpt-4o) and see tool calls and results in the chat history. In host applications, fetch the generated RubyLLM tool classes via Tools::MetaToolService.ruby_llm_tools and pass them to your LLM client to enable tool invocation during conversations.

Prerequisites:

• Ruby (compatible with Rails 8)
• Bundler and Rails installed in the project
• A Rails application where you want to enable the MCP engine

Steps:

1. Add the gem to your Gemfile:

# Gemfile
gem 'rails_mcp_engine'

2. Install dependencies:

bundle install

3. Bundle the engine into your Rails application and initialize as you would a normal Rails engine. Ensure routes are mounted so you can access the Playground and Chat interfaces (example in README):

# config/routes.rb
mount RailsMcpEngine::Engine => '/rails_mcp_engine'

4. Run the Rails server:

bundle exec rails server

5. Open the MCP playground and chat interfaces:

• Playground: http://localhost:3000/rails_mcp_engine/playground
• Chat: http://localhost:3000/rails_mcp_engine/chat

6. (Optional) Define service tools in app/services/tools/ as described in the README, then restart the server to generate the corresponding RubyLLM and FastMCP wrappers at boot.

Tips and notes:

• Tools are defined as services under Tools::, extending ToolMeta and using Sorbet signatures for the entrypoint. The engine generates RubyLLM::Tool and MCP ApplicationTool wrappers automatically at Rails boot.
• The MetaToolService provides actions like list, list_summary, search, get, and run to explore and invoke tools at runtime. The register action is restricted for security; tools can be registered programmatically at runtime if needed.
• Mounting the engine is essential to access the Playground and Chat interfaces. Ensure routes are configured as shown in the README.
• Environment variables such as RAILS_ENV can influence which tools are generated or exposed; adjust accordingly for development, testing, or production.
• If you modify tool definitions, restart the Rails server to trigger regeneration of the corresponding tool wrappers.
• The engine relies on RubyLLM and FastMCP for tool definitions and server behavior; keep dependencies up to date to benefit from improvements and compatibility fixes.