• JSON-RPC 2.0 transport layer
• Capability negotiation during initialization
• Error handling with proper error codes (-32601 for method not found, -32002 for consent required)
• Session management with resumable sessions
• Change notifications for dynamic capability updates

For a detailed (and entertaining) breakdown of protocol versions, features, and our design decisions, see The Hitchhiker's Guide to MCP.

Don't Panic: The guide contains everything you need to know about surviving MCP protocol versions.

Note: STDIO transport is not supported in ActionMCP. This gem is focused on production-ready, network-based deployments. STDIO is only suitable for desktop or script-based experimentation and is intentionally excluded.

Instead of implementing MCP support from scratch, you can subclass and configure the provided Prompt, Tool, and ResourceTemplate classes to expose your app's functionality to LLMs.

ActionMCP handles the underlying MCP message format and routing, so you can adhere to the open standard with minimal effort.

In short, ActionMCP helps you build an MCP server (the component that exposes capabilities to AI) more quickly and with fewer mistakes.

Client connections: The client part of ActionMCP is meant to connect to remote MCP servers only. Connecting to local processes (such as via STDIO) is not supported.

Requirements

• 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+.

Installation

To start using ActionMCP, add it to your project:

# Add gem to your Gemfile
$ bundle add actionmcp

# Install dependencies
bundle install

# Copy migrations from the engine
bin/rails action_mcp:install:migrations

# Generate base classes and configuration
bin/rails generate action_mcp:install

# Create necessary database tables
bin/rails db:migrate

The action_mcp:install generator will:

• Create base application classes (ApplicationGateway, ApplicationMCPTool, etc.)
• Generate the MCP configuration file (config/mcp.yml)
• Set up the basic directory structure for MCP components (app/mcp/)

Database migrations are copied separately using bin/rails action_mcp:install:migrations.

Core Components

ActionMCP provides three core abstractions to streamline MCP server development:

ActionMCP::Prompt

ActionMCP::Prompt enables you to create reusable prompt templates that can be discovered and used by LLMs. Each prompt is defined as a Ruby class that inherits from ApplicationMCPPrompt.

Key features:

• Define expected arguments with descriptions and validation rules
• Build multi-step conversations with mixed content types
• Support for text, images, audio, and resource attachments
• Add messages with different roles (user/assistant)

Example:

class AnalyzeCodePrompt < ApplicationMCPPrompt
  prompt_name "analyze_code"
  description "Analyze code for potential improvements"

  argument :language, description: "Programming language", default: "Ruby"
  argument :code, description: "Code to explain", required: true

  validates :language, inclusion: { in: %w[Ruby Python JavaScript] }

  def perform
    render(text: "Please analyze this #{language} code for improvements:")
    render(text: code)

    # You can add assistant messages too
    render(text: "Here are some things to focus on in your analysis:", role: :assistant)

    # Even add resources if needed
    render(resource: "file://documentation/#{language.downcase}_style_guide.pdf",
           mime_type: "application/pdf",
           blob: get_style_guide_pdf(language))
  end

  private

  def get_style_guide_pdf(language)
    # Implementation to retrieve style guide as base64
  end
end

Prompts can be executed by instantiating them and calling the call method:

analyze_prompt = AnalyzeCodePrompt.new(language: "Ruby", code: "def hello; puts 'Hello, world!'; end")
result = analyze_prompt.call

ActionMCP::Tool

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}")

    # You can report errors if needed
    if sum > 1000
      report_error("Warning: Sum exceeds recommended limit")
    end

    # Or even images
    render(image: generate_visualization(a, b), mime_type: "image/png")
  end

  private

  def generate_visualization(a, b)
    # Implementation to create a visualization as base64
  end
end

Consent Management

For tools that perform sensitive operations (file system access, database modifications, external API calls), you can require explicit user consent:

class FileSystemTool < ApplicationMCPTool
  tool_name "read_file"
  description "Read contents of a file"

  # Require explicit consent before execution
  requires_consent!

  property :file_path, type: "string", description: "Path to file", required: true

  def perform
    # This code only runs after user grants consent
    content = File.read(file_path)
    render(text: "File contents: #{content}")
  end
end

Consent Flow:

1. When a consent-required tool is called without consent, it returns a JSON-RPC error with code -32002
2. The client must explicitly grant consent for the specific tool
3. Once granted, the tool can execute normally for that session
4. Consent is session-scoped and can be revoked at any time

Managing Consent:

# Check if consent is granted
session.consent_granted_for?("read_file")

# Grant consent for a tool
session.grant_consent("read_file")

# Revoke consent
session.revoke_consent("read_file")

Tools can be executed by instantiating them and calling the call method:

sum_tool = CalculateSumTool.new(a: 5, b: 10)
result = sum_tool.call

Structured output (output_schema)

Advertise a JSON Schema for your tool's structuredContent and return machine-validated results alongside any text output.

class PriceQuoteTool < ApplicationMCPTool
  tool_name "price_quote"
  description "Return a structured price quote"

  property :sku, type: "string", description: "SKU to price", required: true

  output_schema do
    string :sku, required: true, description: "SKU that was priced"
    number :price_cents, required: true, description: "Total price in cents"
    object :meta do
      string :currency, required: true, enum: %w[USD EUR GBP]
      boolean :cached, default: false
    end
  end

  def perform
    price_cents = lookup_price_cents(sku) # Implement your lookup

    render structured: { sku: sku,
                         price_cents: price_cents,
                         meta: { currency: "USD", cached: false } }
  end
end

The schema is included in the tool definition, and the structured payload is emitted as structuredContent in the response while remaining compatible with text/audio/image renders.

Returning resource links from a tool

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.

class ReportLinkTool < ApplicationMCPTool
  tool_name "report_link"
  description "Return a downloadable report link"

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