MCP on Rails

A Rails application template that seamlessly integrates the Model Context Protocol (MCP) with Ruby on Rails applications using the mcp gem.

What This Does

This template bootstraps a new Rails application with MCP server capabilities, allowing AI assistants to interact with your Rails models through structured tools. When you scaffold new models, MCP tools are automatically generated alongside the standard Rails files.

You may read a longer introduction to the topic in my article at https://www.visuality.pl/posts/mcp-template-for-rails-applications

Quick Start

Create a new Rails application with MCP integration:

git clone https://github.com/pstrzalk/mcp-on-rails.git
rails new myapp -m mcp-on-rails/mcp
cd myapp

That's it! Your Rails app now has:

• MCP server endpoint at /mcp
• Automatic MCP tool generation during scaffolding
• All necessary MCP infrastructure configured

Adding the MCP template to an existing Rails application

You may just as easily apply this template to an existing Rails app.

git clone https://github.com/pstrzalk/mcp-on-rails.git
cd your-project/
rails app:template LOCATION=../mcp-on-rails/mcp

Usage

1. Scaffolding Models with MCP Tools

When you generate a scaffold, MCP tools are automatically created:

rails generate scaffold Post title:string content:text author:string

This creates the standard Rails files PLUS MCP tools in app/tools/posts/:

• show_tool.rb - Retrieve a single post by ID
• index_tool.rb - List posts with filtering and pagination
• create_tool.rb - Create new posts
• update_tool.rb - Update existing posts
• delete_tool.rb - Delete posts

2. Creating Custom MCP Tools

Generate standalone MCP tools for custom functionality:

rails generate mcp_tool WeatherCheckTool location:string

This creates app/tools/weather_tool.rb with a customizable MCP tool structure. When you specify attributes, the generator automatically creates the input schema with proper types and includes them as method parameters.

3. Starting Your MCP Server

rails server

Your MCP server is now available at:

• HTTP: http://localhost:3000/mcp (streamable HTTP transport)
• Development: Connect AI assistants to this endpoint

The server uses streamable HTTP transport, allowing for real-time communication between AI assistants and your Rails application.

4. Viewing Available Tools

List all registered MCP tools:

rake mcp:tools

Example: Generated MCP Tools

For a Post model with title:string and content:text, the generated create_tool.rb looks like:

module Posts
  class CreateTool < MCP::Tool
    tool_name "post-create-tool"
    description "Create a new Post entity"

    input_schema(
      properties: {
        title: { type: "string" },
        content: { type: "string" },
      },
      required: []
    )

    def self.call(title: nil, content: nil, server_context:)
      post = Post.new(title: title, content: content)

      if post.save
        MCP::Tool::Response.new([{
          type: "text",
          text: "Created #{post.to_mcp_response}"
        }])
      else
        MCP::Tool::Response.new([{
          type: "text",
          text: "Post was not created due to errors: #{post.errors.full_messages.join(', ')}"
        }])
      end
    rescue StandardError => e
      MCP::Tool::Response.new([{
        type: "text",
        text: "An error occurred: #{e.message}"
      }])
    end
  end
end

MCP Tool Features

Automatic Schema Generation

• String/Text fields: Mapped to type: "string"
• Integer/Reference fields: Mapped to type: "integer"
• Boolean fields: Mapped to type: "boolean"
• References: Automatically included in required fields and filtering

Built-in Functionality

• CRUD Operations: Full create, read, update, delete support
• Filtering: Index tools support filtering by reference fields
• Pagination: Index tools include count parameter (default: 10)
• Error Handling: Comprehensive error responses
• Validation: Rails model validations are respected

Model Integration

Each model gets a to_mcp_response method for consistent formatting:

def to_mcp_response
  result = [self.class.name]
  result += attributes.map { |key, value| "  **#{key}**: #{value}" }
  result.join("\n")
end

Project Structure

After using this template, your Rails app will have:

app/
├── controllers/
│   └── mcp_controller.rb          # MCP protocol handler
├── models/
│   └── application_record.rb      # Extended with to_mcp_response
└── tools/                         # MCP tools directory
    └── posts/                     # Auto-generated for each model
        ├── show_tool.rb
        ├── index_tool.rb
        ├── create_tool.rb
        ├── update_tool.rb
        └── delete_tool.rb

config/
├── routes.rb                      # MCP endpoint routes
└── initializers/
    └── mcp.rb                     # MCP configuration

lib/
└── generators/
    ├── mcp_tool/
    │   ├── ...
    │   └── mcp_tool_generator.rb  # Custom tool generator
    └── rails/
        ├── ...
        ├── mcp_generator.rb       # Scaffold hook generator
        └── scaffold_controller_generator.rb  # Extended for MCP

Connecting AI Assistants

Configure your AI assistant to connect to your Rails MCP server:

{
  "name": "my-app",
  "type": "StreamableHttp",
  "url": "http://localhost:3000/mcp"
}

Development Commands

# Start the Rails server
rails server

# Generate models with MCP tools
rails generate scaffold ModelName field:type otherField:otherType

# Generate custom MCP tools
rails generate mcp_tool ToolName field:type otherField:otherType

# List all MCP tools
rake mcp:tools

How It Works

This template uses Rails' generator hook system to extend the standard scaffold controller generator. When you run rails generate scaffold, it automatically invokes the MCP generator to create tools alongside the standard Rails files.

The approach:

• Only adds MCP-specific code, doesn't override Rails generators
• Works with Rails updates automatically
• Uses Rails' intended extension mechanism (like jbuilder)

Contributing

This is a Rails application template. To modify:

1. Edit mcp - the main template file
2. Update mcp_template/ - files copied to new Rails apps
3. Test with: rails new testapp -m mcp

License

MIT License - see the template code for details.