Content
# Active MCP 🔌
<div align="center">
[](https://badge.fury.io/rb/active_mcp)
[](LICENSE)
[](https://rubyonrails.org/)
A Ruby on Rails engine for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) - connect your Rails apps to AI tools with minimal effort.
</div>
## 📖 Table of Contents
- [Active MCP 🔌](#active-mcp-)
- [📖 Table of Contents](#-table-of-contents)
- [✨ Features](#-features)
- [📦 Installation](#-installation)
- [🚀 Setup](#-setup)
- [🔌 MCP Connection Methods](#-mcp-connection-methods)
- [1. Direct HTTP Connection](#1-direct-http-connection)
- [2. Standalone MCP Server](#2-standalone-mcp-server)
- [🛠 Rails Generators](#-rails-generators)
- [Install Generator](#install-generator)
- [Tool Generator](#tool-generator)
- [Resource Generator](#resource-generator)
- [🧰 Creating MCP Tools](#-creating-mcp-tools)
- [📋 Input Schema](#-input-schema)
- [🔐 Authorization \& Authentication](#-authorization--authentication)
- [Authorization for Tools](#authorization-for-tools)
- [Authentication Options](#authentication-options)
- [1. Server Configuration](#1-server-configuration)
- [2. Token Verification in Tools](#2-token-verification-in-tools)
- [📦 MCP Resources](#-mcp-resources)
- [Creating Resources](#creating-resources)
- [Resource Types](#resource-types)
- [📦 MCP Resource Templates](#-mcp-resource-templates)
- [Creating Resource Templates](#creating-resource-templates)
- [💬 MCP Prompts](#-mcp-prompts)
- [Creating Prompt](#creating-prompt)
- [📥 Using Context in the Schema](#-using-context-in-the-schema)
- [💡 Best Practices](#-best-practices)
- [1. Create Specific Tool Classes](#1-create-specific-tool-classes)
- [2. Validate and Sanitize Inputs](#2-validate-and-sanitize-inputs)
- [3. Return Structured Responses](#3-return-structured-responses)
- [🧪 Development](#-development)
- [👥 Contributing](#-contributing)
- [📄 License](#-license)
## ✨ Features
- **Simple Integration**: Easily expose Rails functionality as MCP tools
- **Resource Support**: Share files and data with AI assistants through MCP resources
- **Powerful Generators**: Quickly scaffold MCP tools and resources with Rails generators
- **Authentication Support**: Built-in authentication and authorization capabilities
- **Flexible Configuration**: Multiple deployment and connection options
## 📦 Installation
Add this line to your application's Gemfile:
```ruby
gem 'active_mcp'
```
And then execute:
```bash
$ bundle install
```
Or install it yourself as:
```bash
$ gem install active_mcp
```
## 🚀 Setup
1. Initialize
The easiest way to set up Active MCP in your Rails application is to use the install generator:
```bash
$ rails generate active_mcp:install
```
This generator will create a configuration initializer at `config/initializers/active_mcp.rb`
2. Create a tool by inheriting from `ActiveMcp::Tool::Base`:
```bash
$ rails generate active_mcp:tool create_note
```
```ruby
class CreateNoteTool < ActiveMcp::Tool::Base
def tool_name
"create_note"
end
def description
"Create Note"
end
argument :title, :string, required: true
argument :content, :string, required: true
def call(title:, content:, context:)
note = Note.create(title: title, content: content)
"Created note with ID: #{note.id}"
end
end
```
3. Create schema for your application:
```ruby
class MySchema < ActiveMcp::Schema::Base
def tools
[
CreateNoteTool.new
]
end
end
```
4. Create controller ans set up routing:
```ruby
class MyMcpController < ActiveMcp::BaseController
private
def schema
MySchema.new(context:)
end
end
```
```ruby
Rails.application.routes.draw do
post "/mcp", to: "my_mcp#index"
# Your other routes
end
```
## 🔌 MCP Connection Methods
Active MCP supports two connection methods:
### 1. Direct HTTP Connection
Set your MCP client to connect directly to your Rails application:
```
https://your-app.example.com/mcp
```
### 2. Standalone MCP Server
Start a dedicated MCP server that communicates with your Rails app:
```ruby
# script/mcp_server.rb
server = ActiveMcp::Server.new(
name: "My App MCP Server",
uri: 'https://your-app.example.com/mcp'
)
server.start
```
Then configure your MCP client:
```json
{
"mcpServers": {
"my-rails-app": {
"command": "/path/to/ruby",
"args": ["/path/to/script/mcp_server.rb"]
}
}
}
```
## 🛠 Rails Generators
Active MCP provides generators to help you quickly set up and extend your MCP integration:
### Install Generator
Initialize Active MCP in your Rails application:
```bash
$ rails generate active_mcp:install
```
### Tool Generator
Create new MCP tools quickly:
```bash
$ rails generate active_mcp:tool search_users
```
This creates a new tool file at `app/mcp/tools/search_users_tool.rb` with ready-to-customize starter code.
### Resource Generator
Generate new MCP resources to share data with AI:
```bash
$ rails generate active_mcp:resource profile_image
```
This creates a new resource file at `app/mcp/resources/profile_image_resource.rb` that you can customize to provide various types of content to AI assistants.
## 🧰 Creating MCP Tools
MCP tools are Ruby classes that inherit from `ActiveMcp::Tool::Base` and define an interface for AI to interact with your application:
```ruby
class SearchUsersTool < ActiveMcp::Tool::Base
def tool_name
"Search Users"
end
def description
'Search users by criteria'
end
argument :email, :string, required: false, description: 'Email to search for'
argument :name, :string, required: false, description: 'Name to search for'
argument :limit, :integer, required: false, description: 'Maximum number of records to return'
def call(email: nil, name: nil, limit: 10, context: {})
criteria = {}
criteria[:email] = email if email.present?
criteria[:name] = name if name.present?
users = User.where(criteria).limit(limit)
users.attributes
end
end
```
## 📋 Input Schema
Define arguments for your tools using the `argument` method:
```ruby
argument :name, :string, required: true, description: 'User name'
argument :age, :integer, required: false, description: 'User age'
argument :addresses, :array, required: false, description: 'User addresses'
argument :preferences, :object, required: false, description: 'User preferences'
```
Supported types:
| Type | Description |
| ---------- | ------------------------------- |
| `:string` | Text values |
| `:integer` | Whole numbers |
| `:number` | Decimal numbers (float/decimal) |
| `:boolean` | True/false values |
| `:array` | Lists of values |
| `:object` | Hash/dictionary structures |
| `:null` | Null values |
## 🔐 Authorization & Authentication
### Authorization for Tools
Control access to tools by overriding the `visible?` class method:
```ruby
class AdminOnlyTool < ActiveMcp::Tool::Base
def tool_name
"admin_only_tool"
end
def description
"Admin-only tool"
end
argument :command, :string, required: true, description: "Admin command"
# Only allow admins to access this tool
def visible?(context:)
return false unless context
return false unless context[:auth_info][:type] == :bearer
# Check if the token belongs to an admin
context[:auth_info] == "admin-token" || User.find_by_token(context[:auth_info])&.admin?
end
def call(command:, context: {})
# Tool implementation
end
end
```
### Authentication Options
#### 1. Server Configuration
```ruby
server = ActiveMcp::Server.new(
name: "My Secure MCP Server",
uri: 'http://localhost:3000/mcp',
auth: {
type: :bearer,
token: ENV['MCP_AUTH_TOKEN']
}
)
server.start
```
#### 2. Token Verification in Tools
```ruby
def call(resource_id:, context: {})
# Check if authentication is provided
unless context[:auth_info].present?
raise "Authentication required"
end
# Verify the token
user = User.authenticate_with_token(context[:auth_info][:token])
unless user
raise "Invalid authentication token"
end
# Proceed with authenticated operation
# ...
end
```
## 📦 MCP Resources
MCP Resources allow you to share data and files with AI assistants. Resources have a URI, MIME type, and can return either text or binary data.
### Creating Resources
Resources are Ruby classes `**Resource`:
```ruby
class UserResource < ActiveMcp::Resource::Base
class << self
def mime_type
"application/json"
end
end
def initialize(id:)
@user = User.find(id)
end
def resource_name
@user.name
end
def uri
"data://localhost/users/#{@user.id}"
end
def description
@user.profile
end
def visible?(context:)
# Your logic...
end
def text
# Return JSON data
{
id: @user.id,
name: @user.name,
email: @user.email,
created_at: @user.created_at
}
end
end
```
```ruby
class MySchema < ActiveMcp::Schema::Base
def resources
User.all.each do |user|
UserResource.new(id: user.id)
end
end
end
```
### Resource Types
Resources can return two types of content:
1. **Text Content** - Use the `text` method to return structured data:
```ruby
def text
# Return strings, arrays, hashes, or any JSON-serializable object
{ items: Product.all.map(&:attributes) }
end
```
2. **Binary Content** - Use the `blob` method to return binary files:
```ruby
class ImageResource < ActiveMcp::Resource::Base
class << self
def mime_type
"image/png"
end
end
def resource_name
"profile_image"
end
def uri
"data://localhost/image"
end
def description
"Profile image"
end
def blob
# Return binary file content
File.read(Rails.root.join("public", "profile.png"))
end
end
```
Resources can be protected using the same authorization mechanism as tools:
```ruby
def visible?(context: {})
return false unless context
return false unless context[:auth_info][:type] == :bearer
# Check if the token belongs to an admin
User.find_by_token(context[:auth_info][:token])&.admin?
end
```
## 📦 MCP Resource Templates
MCP Resource Teamplates allow you to define template of resources.
### Creating Resource Templates
Resource teamplates are Ruby classes `**Resource`:
```ruby
class UserResource < ActiveMcp::Resource::Base
class << self
def resource_template_name
"users"
end
def uri_template
"data://localhost/users/{id}"
end
def mime_type
"application/json"
end
def description
"This is a test."
end
def visible?(context:)
# Your logic...
end
end
argument :id, complete: ->(value, context) do
User.all.pluck(:id).filter { _1.match(value) }
end
def initialize(id:)
@user = User.find(id)
end
def resource_name
@user.name
end
def description
@user.profile
end
def uri
"data://localhost/users/#{@user.name}"
end
def text
{ name: @user.name }
end
end
```
```ruby
class MySchema < ActiveMcp::Schema::Base
def resources
User.all.each do |user|
UserResource.new(id: user.id)
end
end
end
```
## 💬 MCP Prompts
MCP Prompts allow you to define prompt set.
### Creating Prompt
Resources are Ruby classes `**Prompt`:
```ruby
class HelloPrompt < ActiveMcp::Prompt::Base
argument :name, required: true, description: "User name", complete: ->(value, context) do
User.all.pluck(:name).filter { _1.match(value) }
end
def initialize(greeting:)
@greeting = greeting
end
def prompt_name
"hello"
end
def description
"This is a test."
end
def visible?(context:)
# Your logic...
end
def messages(name:)
[
ActiveMcp::Message::Text.new(
role: "user",
text: "#{@greeting} #{name}"
),
ActiveMcp::Message::Image.new(
role: "assistant",
data: File.read(file),
mime_type: "image/png"
),
ActiveMcp::Message::Audio.new(
role: "user",
data: File.read(file),
mime_type: "audio/mpeg"
),
ActiveMcp::Message::Resource.new(
role: "assistant",
resource: UserResource.new(name: @name)
)
]
end
end
```
```ruby
class MySchema < ActiveMcp::Schema::Base
def prompts
[
HelloPrompt.new(greeting: "Hello!")
]
end
end
```
## 📥 Using Context in the Schema
```ruby
class MySchema < ActiveMcp::Schema::Base
def prompts
user = User.find_by_token(context[:auth_info][:token])
user.greetings.map do |greeting|
GreetingPrompt.new(greeting: greeting)
end
end
end
```
```ruby
class GreetingPrompt < ActiveMcp::Prompt::Base
def initialize(greeting:)
@greeting = greeting
end
def prompt_name
"greeting_#{@greeting.text}"
end
def messages
# ...
end
end
```
## 💡 Best Practices
### 1. Create Specific Tool Classes
Create dedicated tool classes for each model or operation instead of generic tools:
```ruby
# ✅ GOOD: Specific tool for a single purpose
class SearchUsersTool < ActiveMcp::Tool::Base
# ...specific implementation
end
# ❌ BAD: Generic tool that dynamically loads models
class GenericSearchTool < ActiveMcp::Tool::Base
# Avoid this pattern - security and maintainability issues
end
```
### 2. Validate and Sanitize Inputs
Always validate and sanitize inputs in your tool implementations:
```ruby
def call(user_id:, context: {})
# Validate input
unless user_id.is_a?(Integer) || user_id.to_s.match?(/^\d+$/)
raise "Invalid user ID format"
end
# Proceed with validated data
user = User.find_by(id: user_id)
# ...
end
```
### 3. Return Structured Responses
Return structured responses that are easy for AI to parse:
```ruby
def call(query:, context: {})
results = User.search(query)
{
content: results.to_json(only: [:id, :name, :email]),
metadata: {
count: results.size,
query: query
}
}
end
```
## 🧪 Development
After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rake` to run the tests.
## 👥 Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/moekiorg/active_mcp. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/moekiorg/active_mcp/blob/main/CODE_OF_CONDUCT.md).
## 📄 License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
