ActionMCP

- Provides base classes for Prompt, Tool, and ResourceTemplate.
- Supports MCP 2025-06-18 with backward compatibility to 2025-03-26.
- Full JSON‑RPC 2.0 transport layer with capability negotiation.
- Consent management for sensitive tool operations.
- Structured output via output_schema and resource_link support.
- Task‑augmented tools with async execution and progress updates.

- Ruby: 3.4.8+ or 4.0.0+
- Rails: 8.1.1+
- Database: PostgreSQL, MySQL, or SQLite3

ActionMCP is tested against Ruby 3.4.8 and 4.0.0 with Rails 8.1.1+.

bundle install

bin/rails generate action_mcp:install

- Installation & Configuration - Initial setup, database migrations, and basic configuration
- Authentication with Gateway - User authentication and authorization patterns

- Session Storage - Volatile vs ActiveRecord vs custom session stores
- Thread Pool Management - Performance tuning and graceful shutdown
- Profiles System - Multi-tenant capability filtering
- Production Deployment - Falcon, Unix sockets, and reverse proxy setup

Rails.application.configure do
config.action_mcp.session_store_type = :active_record # or :volatile
end

Or in config/mcp.yml:

You can configure the thread pool in your config/mcp.yml:

production:
ActionMCP includes generators to help you set up your project quickly. The install generator creates all necessary base classes and configuration files:

bin/rails generate action_mcp:install

This will create:

- app/mcp/prompts/application_mcp_prompt.rb - Base prompt class

- app/mcp/tools/application_mcp_tool.rb - Base tool class

- app/mcp/resource_templates/application_mcp_res_template.rb - Base resource template class

- app/mcp/application_gateway.rb - Gateway for authentication

- config/mcp.yml - Configuration file with example settings for all environments

- mcp/config.ru - Standalone Rack server configuration

- bin/mcp - Server binstub (prefers Falcon, falls back to Puma)

> Note: Authentication and authorization are not included. You are responsible for securing the endpoint.
ActionMCP provides a Gateway system for handling authentication. The Gateway allows you to authenticate users and make them available throughout your MCP components. For the full gateway reference including identifier classes, session persistence, profile switching, and production hardening tips, see GATEWAY.md.
ActionMCP uses a Gateway pattern with pluggable identifiers for authentication. You can implement custom authentication strategies using session-based auth, API keys, bearer tokens, or integrate with existing authentication systems like Warden, Devise, or external OAuth providers.
> Note: Auth errors return HTTP 200 with a JSON-RPC error payload (not HTTP 401). This is correct per the MCP specification — all MCP communication uses JSON-RPC over HTTP, and protocol-level errors are expressed within the JSON-RPC envelope. The initialize request bypasses authentication per MCP spec.
{

      user: user,

      organization: user.organization

    }

  end

end

ActionMCP::Tool allows you to create interactive functions that LLMs can call with arguments to perform specific tasks. Each tool is a Ruby class that inherits from ApplicationMCPTool.

Key features:
- Define input properties with types, descriptions, and validation
- Return multiple response types (text, images, errors)
- Progressive responses with multiple render calls
- Automatic input validation based on property definitions
- Consent management for sensitive operations

Example:

class CalculateSumTool < ApplicationMCPTool
  tool_name "calculate_sum"
  description "Calculate the sum of two numbers"
property :a, type: "number", description: "The first number", required: true

  property :b, type: "number", description: "The second number", required: true
def perform

    sum = a + b

    render(text: "Calculating #{a} + #{b}...")

    render(text: "The sum is #{sum}")
When you want to hand back a URI instead of embedding the payload, use the built-in render_resource_link, which produces the MCP resource_link content type.

property :report_id, type: "string", required: true

def perform
render_resource_link(
uri: "reports://#{report_id}.json",
name: "Report #{report_id}",
description: "Downloadable JSON for report #{report_id}",
mime_type: "application/json"
)
end
end

Clients can resolve the URI with a separate resources/read call, keeping tool responses lightweight while still discoverable.

Use MCP Tasks when work might take seconds/minutes. Advertise task support with task_required! (or task_optional!) and let callers opt in by sending _meta.task on tools/call. While running as a task, you can emit progress updates with report_progress!.

task_required! # advertise that this tool is intended to run as a task
property :items, type: "array_string", description: "Items to index", required: true

def perform
total = items.length
items.each_with_index do |item, idx|
index_item(item) # your indexing logic

percent = ((idx + 1) * 100.0 / total).round
report_progress!(percent: percent, message: "Indexed #{idx + 1}/#{total}")
end

render(text: "Indexed #{total} items")
end

private

def index_item(item)