Active MCP: Integrating Model Context Protocol with Rails

Introduction

Since the beginning of 2025, Model Context Protocol (MCP) has been getting attention as an implementation method for LLM-based solutions. MCP is a protocol that standardizes the interface between AI models and applications, allowing LLMs to be provided with application features as tools.

I think the methods for data exploration using LLMs will gradually transition from the standard vector database approach to MCP.

On a personal note, I hadn't been following MCP much so I only recently started researching it. I tried implementing it with TypeScript SDK and mcp-rb, but I couldn't quite grasp the specifications, so I thought I'd create something from scratch and started writing a library.

This time, I created a gem called "Active MCP" that allows Rails applications to easily generate MCP server schemas.

https://github.com/moekiorg/active_mcp

Overview of MCP

For details, please refer to the official documentation, but as a refresher, when looking at MCP from client-side and server-side perspectives, it breaks down as follows:

• Client Side (e.g., Claude Desktop)
  • Interprets natural language prompts from users and makes requests according to the MCP schema
• Server Side (various MCP servers)
  • Performs operations or resource retrieval based on client requests and returns responses

Also, the core of the MCP schema consists of Resources, Tools, and Prompts.

• Resources: Content like file contents or database information. Can be assigned URIs
• Tools: Define operations such as adding or deleting data
• Prompts: Define templates for prompt interactions that users can call like slash commands

Features of Active MCP

It consists of two main parts:

1. ActiveMcp::Tool - Define MCP Tools within a Rails application
2. ActiveMcp::Server - Launch an MCP server completely separate from the Rails application to communicate with the Rails app

Since MCP-defined processes are mediated through HTTP, the MCP core handled by Active MCP currently includes only Tools, not Prompts and Resources. This approach may change in the future.
When starting, ActiveMcp::Server fetches Tools defined by ActiveMcp::Tool from Rails and uses them to inform the client about available processes. When a request comes from an MCP client, it is processed within Rails via ActiveMcp::Server, and the response is returned to the MCP client.

Installation

Installing ActiveMCP is simple. First, add the following line to your Gemfile:

gem 'active_mcp'

Then, run the following command:

$ bundle install

Or you can install it directly:

$ gem install active_mcp

Basic Usage

1. Setting up Routes

First, mount the Active MCP engine in your config/routes.rb:

Rails.application.routes.draw do
  mount ActiveMcp::Engine, at: "/mcp"

  # Other route configurations
end

This makes /mcp the endpoint for executing processes defined in MCP.

2. Creating Tools

Next, create tools that can be used with MCP. For example, you can define a tool to create notes as follows:

class CreateNoteTool < ActiveMcp::Tool
  description "Create a new note"

  property :title, :string, required: true, description: 'Note title'
  property :content, :string, required: true, description: 'Note content'

  def call(title:, content:)
    note = Note.create(
      title: title,
      content: content
    )

    if note.persisted? 
      "Note \"#{title}\" has been created. ID: #{note.id}" 
    else
      "Failed to create note: #{note.errors.full_messages.join(', ')}" 
    end
  end
end

In this example:

• description defines the tool description
• property defines required parameters and their types
• The call method implements the actual process of the tool

The return value of the call method can be anything, but it will be sent directly to the MCP client and interpreted as text.

3. Starting the MCP Server

To start an MCP server locally during development, create a script like this:

# server.rb
require 'active_mcp'

server = ActiveMcp::Server.new(
  name: "MyApp MCP Server",
  uri: 'http://localhost:3000/mcp' # Remote servers work too, of course
)
server.start

4. Configuring the MCP Client

To connect a server to an MCP client, specify it in the client's configuration as follows:

{
  "mcpServers": {
    "my-rails-app": {
      "command": "/path/to/ruby",
      "args": ["/path/to/server.rb"]
    }
  }
}

Implementing Authentication

To implement authentication with MCP clients, specify a token in your server configuration:

server = ActiveMcp::Server.new(
  name: "MyApp MCP Server",
  uri: 'http://localhost:3000/mcp',
  auth: {
    type: :bearer,
    token: ENV['MCP_ACCESS_TOKEN']
  }
)

And to use authentication information within a tool:

def call(param1:, auth_info: nil)
  # auth_info = { type: :bearer, token: 'xxx', header: 'Bearer xxx' }

  unless auth_info.present?
    return { type: "error", content: "Authentication required" }
  end

  # Verify authentication token and get user
  token = auth_info[:token]
  user = User.find_by_token(token)

  unless user
    return { type: "error", content: "Invalid token" }
  end

  # Process after successful authentication
  # ...
end

Convenient Generators

ActiveMCP includes generators to help create tools:

# Generate a new MCP tool
$ rails generate active_mcp:tool search_users

This generates a basic tool template at app/tools/search_users_tool.rb.

Summary and Future Outlook

Through these implementations, I've finally been able to understand the concept of MCP to some extent. To retrieve or process information from an existing Rails application, you would normally need to set up external APIs and define MCP schemas that correspond to them, but Active MCP should make this process a bit easier.

Conclusion

I welcome your feedback and contributions.

https://github.com/moekiorg/active_mcp