action_mcp
Rails Engine with MCP compliant Spec.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/seuros/action_mcp with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/seuros/action_mcp'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/seuros--action-mcp)HTML
<a href="/listings/seuros--action-mcp"><img src="/api/listings/seuros--action-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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`.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 1,396 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # ActionMCP
- **ActionMCP** is a Ruby gem focused on providing Model Context Protocol (MCP) capability to Ruby on Rails applications, specifically as a server.
- ActionMCP is designed for production Rails environments and does **not** support STDIO transport. STDIO is not included because it is not production-ready and is only suitable for desktop or script-based use cases. Instead, ActionMCP is built for robust, network-based deployments.
- The client functionality in ActionMCP is intended to connect to remote MCP servers, not to local processes via STDIO.
- It offers base classes and helpers for creating MCP applications, making it easier to integrate your Ruby/Rails application with the MCP standard.
- With ActionMCP, you can focus on your app's logic while it handles the boilerplate for MCP compliance.
- ## Introduction
- **Model Context Protocol (MCP)** is an open protocol that standardizes how applications provide context to large language models (LLMs).
- Think of it as a universal interface for connecting AI assistants to external data sources and tools.
- MCP allows AI systems to plug into various resources in a consistent, secure way, enabling two-way integration between your data and AI-powered applications.
- This means an AI (like an LLM) can request information or actions from your application through a well-defined protocol, and your app can provide context or perform tasks for the AI in return.
- **ActionMCP** is targeted at developers building MCP-enabled Rails applications. It simplifies the process of integrating Ruby and Rails apps with the MCP standard by providing a set of base classes and an easy-to-use server interface.
- ## Protocol Support
- ActionMCP targets the released **MCP 2025-11-25** protocol. Older protocol versions and unreleased draft versions are not accepted. Core handling includes:
- - **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)
- - **Stateful session management** with explicit termination
- - **Tasks, tools, prompts, resources, completion, logging, sampling, roots, and elicitation** message handling
- The built-in Streamable HTTP endpoint returns one `application/json` message for
- requests and intentionally returns HTTP 405 for GET because it does not provide
- SSE streams. That behavior is allowed by the transport specification. Outbound
- server requests and notifications are retained in session message storage, but
- an application needs an SSE or custom transport to push those messages to a
- client outside the response to an active request.
- For a detailed (and entertaining) breakdown of protocol versions, features, and our design decisions, see [The Hitchhiker's Guide to MCP](The_Hitchhikers_Guide_to_MCP.md).
- *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:
- ```bash
- # 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:**
- ```ruby
- 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:
- ```ruby
- 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:**
- ```ruby
- 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
- ```
- #### Schema Keywords
- Extra keyword arguments on `property` and `collection` become JSON Schema keywords, and arguments are validated against that schema before `perform` runs. Write them in snake_case (`min_length`, `multiple_of`); they are emitted with their JSON Schema names (`minLength`, `multipleOf`). On a `collection`, `min_items`, `max_items` and `unique_items` describe the array; every other keyword describes each item:
- ```ruby
- property :priority, type: "string", enum: %w[low normal high]
- property :retries, type: "integer", minimum: 0, maximum: 5
- collection :labels, type: "string", enum: %w[bug feature docs], min_items: 1, unique_items: true
- ```
- A keyword given as a proc is resolved each time the schema is built, both for `tools/list` and for argument validation. The proc runs with `session`, `session_data`, `current_user` and `current_gateway` in scope, so each client sees and is held to its own values:
- ```ruby
- property :tool, type: "string", required: true, enum: -> { current_user.allowed_tools }
- collection :labels, type: "string", enum: -> { current_user.project.labels.pluck(:name) }, max_items: -> { session_data["label_limit"] }
- ```
- Tools without procs keep a cached validator. Outside a request (rake tasks), `session` and `current_user` are `nil`.
- A proc that raises is reported to `Rails.error` as `ActionMCP::SchemaResolutionError`. That tool is left out of `tools/list` and answers `tools/call` like an unknown tool; every other tool is unaffected.
- #### Consent Management
- For tools that perform sensitive operations (file system access, database modifications, external API calls), you can require explicit user consent:
- ```ruby
- 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:**
- ```ruby
- # 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:
- ```ruby
- 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.
- ```ruby
- 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.
- ```ruby
- class ReportLinkTool < ApplicationMCPTool
- tool_name "report_link"
- description "Return a downloadable report link"
- 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.
- #### Task-augmented tools (async execution with progress)
- 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!`.
- ```ruby
- class BatchIndexTool < ApplicationMCPTool
- tool_name "batch_index"
- description "Index many items asynchronously with progress updates"
- 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)
- # Implement your indexing logic here
- end
- end
- ```
- Call it as a task from a client by adding top-level `task` params (creates a Task record and runs the tool via `ToolExecutionJob`):
- ```json
- {
- "jsonrpc": "2.0",
- "id": 1,
- "method": "tools/call",
- "params": {
- "name": "batch_index",
- "arguments": { "items": ["a", "b", "c"] },
- "task": { "ttl": 120000 }
- }
- }
- ```
- Poll task status with `tasks/get` or fetch the result with `tasks/result`.
- As required by MCP 2025-11-25, `tasks/result` waits while a task is in any non-terminal state, including `input_required`, and returns once it reaches `completed`, `failed`, or `cancelled`. The internal database polling interval must be positive and can be tuned for your Rails app:
- ```ruby
- config.action_mcp.tasks_result_poll_interval = 0.25.seconds
- ```
- Use `tasks/cancel` to stop non-terminal tasks. `tasks/list` returns tasks in recent-first order and always paginates (default 50 per page, or `pagination_page_size` if configured). The response includes an opaque `nextCursor` when more results are available; treat cursors as opaque tokens.
- ### ActionMCP::ResourceTemplate
- `ActionMCP::ResourceTemplate` facilitates the creation of URI templates for dynamic resources that LLMs can access.
- This allows models to request specific data using parameterized URIs.
- Templates support two MCP resource surfaces:
- - **`resources/templates/list`** — parameterized URI patterns (existing behavior)
- - **`resources/list`** — concrete resources with known URIs (via `self.list`)
- > **Note:** Not all MCP clients support both resource endpoints. Claude Code (as of v2.1.50) only calls `resources/list`, and Codex stubs resource methods entirely. Implement `self.list` on your templates to ensure resources are visible to all clients. Crush and VS Code support both endpoints.
- **Example:**
- ```ruby
- class ProductResourceTemplate < ApplicationMCPResTemplate
- uri_template "product/{id}"
- description "Access product information by ID"
- mime_type "application/json"
- parameter :id, description: "Product identifier", required: true
- validates :id, format: { with: /\A\d+\z/, message: "must be numeric" }
- # Optional: enumerate concrete resources for resources/list
- def self.list(session: nil)
- Product.limit(50).map do |product|
- build_resource(
- uri: "product/#{product.id}",
- name: product.name,
- title: "Product ##{product.id}"
- )
- end
- end
- # Resolve a specific resource for resources/read
- def resolve
- product = Product.find_by(id: id)
- return unless product
- ActionMCP::Content::Resource.new(
- "product/#{id}",
- mime_type,
- text: product.to_json
- )
- end
- end
- ```
- **Callbacks:**
- ```ruby
- before_resolve do |template|
- # Starting to resolve product: #{template.product_id}
- end
- after_resolve do |template|
- # Finished resolving product resource for product: #{template.product_id}
- end
- around_resolve do |template, block|
- start_time = Time.current
- resource = block.call
- resource
- end
- ```
- Resource templates are automatically registered and used when LLMs request resources matching their patterns.
- See [RESOURCE_TEMPLATES.md](RESOURCE_TEMPLATES.md) for the full API reference including pagination, deduplication, and read contract details.
- ## 📚 Documentation
- ActionMCP provides comprehensive documentation across multiple specialized guides. Each guide focuses on specific aspects to keep information organized and prevent context overload:
- ### Getting Started & Setup
- - **[Installation & Configuration](README.md#installation)** - Initial setup, database migrations, and basic configuration
- - **[Authentication with Gateway](README.md#authentication-with-gateway)** - User authentication and authorization patterns
- ### Component Development
- - **[📋 TOOLS.MD](TOOLS.MD)** - Complete guide to developing MCP tools
- - Generator usage and best practices
- - Property definitions, validation, and consent management
- - Output schemas for structured responses
- - Error handling, testing, and security considerations
- - Advanced features like additional properties and authentication context
- - **[📝 PROMPTS.MD](PROMPTS.MD)** - Prompt template development guide
- - Creating reusable prompt templates
- - Multi-step conversations and mixed content types
- - Argument validation and prompt chaining
- - **[🔗 RESOURCE_TEMPLATES.md](RESOURCE_TEMPLATES.md)** - Resource template implementation
- - URI template patterns and parameter extraction
- - Dynamic resource resolution and collections
- - Callbacks and validation patterns
- ### Client & Integration
- - **[🔌 CLIENTUSAGE.MD](CLIENTUSAGE.MD)** - Complete client implementation guide
- - Session management and resumability
- - Transport configuration and connection handling
- - Tool, prompt, and resource collections
- - Production deployment patterns
- - **[🔐 GATEWAY.md](GATEWAY.md)** - Authentication gateway guide
- - Implementing `ApplicationGateway`
- - Identifier handling via `ActionMCP::Current`
- - Auth patterns, error handling, and hardening tips
- ### Protocol & Technical Details
- - **[🚀 The Hitchhiker's Guide to MCP](The_Hitchhikers_Guide_to_MCP.md)** - Protocol versions and migration
- - Historical protocol comparison and the current 2025-11-25 behavior
- - Design decisions and architectural rationale
- - Migration paths and compatibility considerations
- - Feature evolution and technical specifications (*Don't Panic!*)
- ### Advanced Configuration
- - **[Session Storage](README.md#session-storage)** - Volatile vs ActiveRecord vs custom session stores
- - **[Thread Pool Management](README.md#thread-pool-management)** - Performance tuning and graceful shutdown
- - **[Profiles System](README.md#profiles)** - Multi-tenant capability filtering
- - **[Production Deployment](README.md#production-deployment-of-mcps0)** - Falcon, Unix sockets, and reverse proxy setup
- ### Development & Testing
- - **[Generators](README.md#generators)** - Rails generators for scaffolding components
- - **[Testing with TestHelper](README.md#testing-with-testhelper)** - Comprehensive testing strategies
- - **[Development Commands](README.md#development-commands)** - Rake tasks for debugging and inspection
- - **[MCP Inspector Integration](README.md#inspecting-your-mcp-server)** - Interactive testing and validation
- ### Troubleshooting & Production
- - **[Error Handling](README.md#error-handling-and-troubleshooting)** - JSON-RPC error codes and debugging
- - **[Production Considerations](README.md#production-considerations)** - Security, performance, and monitoring
- - **[Middleware Conflicts](README.md#dealing-with-middleware-conflicts)** - Using `mcp_vanilla.ru` for production
- > **💡 Pro Tip**: Start with the component-specific guides (TOOLS.MD, PROMPTS.MD, RESOURCE_TEMPLATES.md) for hands-on development, then reference the Hitchhiker's Guide for protocol details and CLIENTUSAGE.MD for integration patterns.
- ## Configuration
- ActionMCP is configured via `config.action_mcp` in your Rails application.
- By default, the name is set to your application's name and the version defaults to "0.0.1" unless your app has a version file.
- You can override these settings in your configuration (e.g., in `config/application.rb`):
- ```ruby
- module Tron
- class Application < Rails::Application
- config.action_mcp.name = "Friendly MCP (Master Control Program)" # defaults to Rails.application.name
- config.action_mcp.version = "1.2.3" # defaults to "0.0.1"
- config.action_mcp.logging_enabled = true # defaults to true
- config.action_mcp.logging_level = :info # defaults to :info, can be :debug, :info, :warn, :error, :fatal
- # Server instructions - helps LLMs understand the server's purpose
- config.action_mcp.server_instructions = [
- "Use this server to access and control Tron system programs",
- "Helpful for managing system processes and user data"
- ]
- end
- end
- ```
- For dynamic versioning, consider adding the `rails_app_version` gem.
- ### Pagination
- All list endpoints (`tools/list`, `prompts/list`, `resources/list`, `resources/templates/list`) support cursor-based pagination per the MCP specification. Pagination is **off by default** — set `pagination_page_size` to enable:
- ```ruby
- config.action_mcp.pagination_page_size = 10
- ```
- Or in `config/mcp.yml`:
- ```yaml
- shared:
- pagination_page_size: 10
- ```
- When set, responses include an opaque `nextCursor` when more items are available. When `nil` (default), all items are returned in a single response. Enable only when your clients support cursor-based pagination.
- `tasks/list` always paginates regardless of this setting (defaults to 50 per page, or `pagination_page_size` if configured).
- ### Custom JSON-RPC Methods
- Vendor methods can be served next to the MCP core methods. Names take the form `vendor/method`; the MCP namespaces (`tools/`, `prompts/`, `resources/`, `notifications/`, ...) are reserved. The handler receives the request params and the session, and its return value becomes the JSON-RPC result:
- ```ruby
- # config/initializers/action_mcp.rb
- ActionMCP.configure do |config|
- config.register_method("acme/toolsets/list") do |params, session|
- { toolsets: Toolset.visible_to(ActionMCP::Current.user).as_json }
- end
- end
- ```
- Raise `JSON_RPC::JsonRpcError` to answer with a specific error code; any other exception is reported to `Rails.error` and answered with `internal_error`.
- ### Server Instructions
- Server instructions help LLMs understand **what your server is for** and **when to use it**. They describe the server's purpose and goal, not technical details like rate limits or authentication (tools are self-documented via their own descriptions).
- Instructions are returned at the top level of the MCP initialization response.
- You can configure server instructions in your `config/mcp.yml` file:
- ```yaml
- shared:
- # Describe the server's purpose - helps LLMs know when to use this server
- server_instructions:
- - "Use this server to manage Fizzy project tickets and workflows"
- - "Helpful for tracking bugs, features, and sprint planning"
- development:
- # Development-specific purpose description
- server_instructions:
- - "Development server for testing Fizzy integration"
- - "Use for prototyping ticket management workflows"
- production:
- # Production-specific purpose description
- server_instructions:
- - "Production Fizzy server for managing live project data"
- ```
- Instructions are sent as a single string (joined by newlines) at the top level of the initialization response, helping LLMs understand your server's purpose.
- ## Session Storage
- ActionMCP provides a pluggable session storage system that allows you to choose how sessions are persisted based on your environment and requirements.
- ### Session Store Types
- ActionMCP includes three session store implementations:
- 1. **`:volatile`** - In-memory storage using Concurrent::Hash
- - Default for development and test environments
- - Sessions are lost on server restart
- - Fast and lightweight for local development
- - No external dependencies
- 2. **`:active_record`** - Database-backed storage
- - Default for production environment
- - Sessions persist across server restarts
- - Supports session resumability
- - Requires database migrations
- 3. **`:test`** - Special store for testing
- - Tracks notifications and method calls
- - Provides assertion helpers
- - Automatically used in test environment when using TestHelper
- ### Configuration
- You can configure the session store type in your Rails configuration or `config/mcp.yml`:
- ```ruby
- # config/application.rb or environment files
- Rails.application.configure do
- config.action_mcp.session_store_type = :active_record # or :volatile
- end
- ```
- Or in `config/mcp.yml`:
- ```yaml
- # Global session store type (used by both client and server)
- session_store_type: volatile
- # Client-specific session store type (falls back to session_store_type if not specified)
- client_session_store_type: volatile
- # Server-specific session store type (falls back to session_store_type if not specified)
- server_session_store_type: active_record
- ```
- The defaults are:
- - Production: `:active_record`
- - Development: `:volatile`
- - Test: `:volatile` (or `:test` when using TestHelper)
- ### Separate Client and Server Session Stores
- You can configure different session store types for client and server operations:
- - **`session_store_type`**: Global setting used by both client and server when specific types aren't set
- - **`client_session_store_type`**: Session store used by ActionMCP client connections (falls back to global setting)
- - **`server_session_store_type`**: Session store used by ActionMCP server sessions (falls back to global setting)
- This allows you to optimize each component separately. For example, you might use volatile storage for client sessions (faster, temporary) while using persistent storage for server sessions (maintains state across restarts).
- ### Using Different Session Stores
- ```ruby
- # The session store is automatically selected based on configuration
- # You can access it directly if needed:
- session_store = ActionMCP::Server.session_store
- # Create a session
- session = session_store.create_session(session_id, {
- status: "initialized",
- protocol_version: "2025-11-25",
- # ... other session attributes
- })
- # Load a session
- session = session_store.load_session(session_id)
- # Update a session
- session_store.update_session(session_id, { status: "active" })
- # Delete a session
- session_store.delete_session(session_id)
- ```
- ### Session Resumability
- With the `:active_record` store, clients can resume sessions after disconnection:
- ```ruby
- # Client includes session ID in request headers
- # Server automatically resumes the existing session
- headers["Mcp-Session-Id"] = "existing-session-id"
- # If the session exists, it will be resumed
- # If not, a new session will be created
- ```
- ### Custom Session Stores
- You can create custom session stores by inheriting from `ActionMCP::Server::SessionStore::Base`:
- ```ruby
- class MyCustomSessionStore < ActionMCP::Server::SessionStore::Base
- def create_session(session_id, payload = {})
- # Implementation
- end
- def load_session(session_id)
- # Implementation
- end
- def update_session(session_id, updates)
- # Implementation
- end
- def delete_session(session_id)
- # Implementation
- end
- def exists?(session_id)
- # Implementation
- end
- end
- # Register your custom store
- ActionMCP::Server.session_store = MyCustomSessionStore.new
- ```
- ## Thread Pool Management
- ActionMCP uses thread pools to efficiently handle message callbacks. This prevents the system from being overwhelmed by too many threads under high load.
- ### Thread Pool Configuration
- You can configure the thread pool in your `config/mcp.yml`:
- ```yaml
- production:
- # Thread pool configuration
- min_threads: 10 # Minimum number of threads to keep in the pool
- max_threads: 20 # Maximum number of threads the pool can grow to
- max_queue: 500 # Maximum number of tasks that can be queued
- ```
- The thread pool will automatically:
- - Start with `min_threads` threads
- - Scale up to `max_threads` as needed
- - Queue tasks up to `max_queue` limit
- - Use caller's thread if queue is full (fallback policy)
- ### Graceful Shutdown
- When your application is shutting down, you should call:
- ```ruby
- ActionMCP::Server.shutdown
- ```
- This ensures all thread pools are properly terminated and tasks are completed.
- ## Engine and Mounting
- > **WARNING: Do NOT mount ActionMCP::Engine in your `routes.rb`.** ActionMCP is a standalone Rack application that runs on its own port via `mcp/config.ru`. Mounting it as a Rails engine route will not work correctly.
- When you use `run ActionMCP.server` in your `mcp/config.ru`, the MCP endpoint is available at the root path (`/`) by default and can be configured via `config.action_mcp.base_path`. Always use `ActionMCP.server` (not `ActionMCP::Engine` directly) — it initializes required subsystems.
- ### Installing ActionMCP
- ActionMCP includes generators to help you set up your project quickly. The install generator creates all necessary base classes and configuration files:
- ```bash
- # Install ActionMCP with base classes and configuration
- 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.
- ## Authentication with Gateway
- 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](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:** When a Gateway is configured, it authenticates every MCP HTTP request, including `initialize`, GET, and DELETE. Authentication failures return HTTP 401 with a `WWW-Authenticate: Bearer` challenge and a JSON-RPC error body.
- ### Creating an ApplicationGateway
- When you run the install generator, it creates an `ApplicationGateway` class:
- ```ruby
- # app/mcp/application_gateway.rb
- class ApplicationGateway < ActionMCP::Gateway
- # Specify what attributes identify a connection
- identified_by :user
- protected
- def authenticate!
- token = extract_bearer_token
- raise ActionMCP::UnauthorizedError, "Missing token" unless token
- payload = ActionMCP::JwtDecoder.decode(token)
- user = resolve_user(payload)
- raise ActionMCP::UnauthorizedError, "Unauthorized" unless user
- # Return a hash with all identified_by attributes
- { user: user }
- end
- private
- def resolve_user(payload)
- user_id = payload["user_id"] || payload["sub"]
- User.find_by(id: user_id) if user_id
- end
- end
- ```
- ### Using Multiple Identifiers
- You can identify connections by multiple attributes:
- ```ruby
- class ApplicationGateway < ActionMCP::Gateway
- identified_by :user, :organization
- protected
- def authenticate!
- # ... authentication logic ...
- {
- user: user,
- organization: user.organization
- }
- end
- end
- ```
- ### Accessing Current User in Components
- Once authenticated, the current user (and other identifiers) are available in your tools, prompts, and resource templates:
- ```ruby
- class MyTool < ApplicationMCPTool
- def perform
- # Access the authenticated user
- if current_user
- render text: "Hello, #{current_user.name}!"
- else
- render text: "Hi Stranger! It's been a while "
- end
- end
- end
- ```
- ### Current Attributes
- ActionMCP uses Rails' CurrentAttributes to store the authenticated context. The `ActionMCP::Current` class provides:
- - `ActionMCP::Current.user` - The authenticated user
- - `ActionMCP::Current.gateway` - The gateway instance
- - Any other attributes you define with `identified_by`
- ### Persisting Context on Sessions
- Override `configure_session` in your gateway to persist auth context (user_id, tenant_id, roles) on the session for use in audit trails, background jobs, and cross-request scenarios:
- ```ruby
- class ApplicationGateway < ActionMCP::Gateway
- identified_by UserIdentifier
- def configure_session(session)
- session.session_data = { "user_id" => user.id, "tenant_id" => user.tenant_id }
- end
- end
- ```
- Tools access it via `session_data["user_id"]`. See [GATEWAY.md](GATEWAY.md) for details.
- ### Per-Request `_meta`
- Tools, prompts and resource templates read the `_meta` object of the current `tools/call`, `prompts/get` or `resources/read` request through `request_meta` (an indifferent-access hash, empty when the client sent none):
- ```ruby
- class OrdersTemplate < ApplicationMCPResTemplate
- def resolve
- trace_id = request_meta["example.com/trace"]
- # ...
- end
- end
- ```
- The MCP specification does not authenticate `_meta`. Use it as a lookup hint, and authorize from the session.
- ### 1. Create `mcp/config.ru`
- The install generator (`rails generate action_mcp:install`) creates this automatically. If you need to create it manually:
- ```ruby
- # Load the full Rails environment to access models, DB, Redis, etc.
- require_relative "../config/environment"
- $stdout.sync = true
- # Eager load so all tools, prompts, and resources are registered.
- Rails.application.eager_load!
- # IMPORTANT: Use ActionMCP.server — it initializes required subsystems.
- # Do NOT use ActionMCP::Engine directly.
- run ActionMCP.server
- ```
- ### 2. Start the server
- ```bash
- bin/mcp # Uses Falcon (recommended)
- bundle exec rails s -c mcp/config.ru -p 62770 # Uses Puma (fallback)
- ```
- ### Dealing with Middleware Conflicts
- If your Rails application uses middleware that interferes with MCP server operation (like Devise, Warden, Ahoy, Rack::Cors, etc.), use `mcp_vanilla.ru` instead:
- ```ruby
- # mcp_vanilla.ru - A minimal Rack app with only essential middleware
- # This avoids conflicts with authentication, tracking, and other web-specific middleware
- # See the file for detailed documentation on when and why to use it
- bundle exec rails s -c mcp_vanilla.ru -p 62770
- # Or with Falcon:
- bundle exec falcon serve --bind http://127.0.0.1:62770 --config mcp_vanilla.ru
- ```
- Common middleware that can cause issues:
- - **Devise/Warden** - Expects cookies and sessions, throws `Devise::MissingWarden` errors
- - **Ahoy** - Analytics tracking that intercepts requests
- - **Rack::Attack** - Rate limiting designed for web traffic
- - **Rack::Cors** - CORS headers meant for browsers
- - Any middleware assuming HTML responses or cookie-based authentication
- An example of a minimal `mcp_vanilla.ru` file is located in the dummy app : test/dummy/mcp_vanilla.ru.
- This file is a minimal Rack application that only includes the essential middleware needed for MCP server operation, avoiding conflicts with web-specific middleware.
- But remember to add any instrumentation or logging middleware you need, as the minimal setup will not include them by default.
- ```ruby
- ## Production Deployment of MCPS0
- In production, **MCPS0** (the MCP server) is a standard Rack application. You can run it using any Rack-compatible server (such as Puma, Unicorn, or Passenger).
- > **For best performance and concurrency, it is highly recommended to use a modern, synchronous server like [Falcon](https://github.com/socketry/falcon)**. Falcon is optimized for streaming and concurrent workloads, making it ideal for MCP servers. You can still use Puma, Unicorn, or Passenger, but Falcon will generally provide superior throughput and responsiveness for real-time and streaming use cases.
- You have several main options for exposing the server:
- ### 1. Dedicated Port
- Run MCPS0 on its own TCP port (commonly `62770`):
- **With Falcon:**
- ```bash
- bundle exec falcon serve --bind http://0.0.0.0:62770 --config mcp/config.ru
- ```
- **With Puma:**
- ```bash
- bundle exec rails s -c mcp/config.ru -p 62770
- ```
- **With Passenger:**
- ```bash
- passenger start --rackup mcp/config.ru --port 62770
- ```
- Then, use your web server (Nginx, Apache, etc.) to reverse proxy requests to this port.
- ### 2. Unix Socket
- Alternatively, you can run MCPS0 on a Unix socket for improved performance and security (especially when the web server and app server are on the same machine):
- **With Falcon:**
- ```bash
- bundle exec falcon serve --bind unix:/tmp/mcps0.sock mcp/config.ru
- ```
- **With Puma:**
- ```bash
- bundle exec puma -C config/puma.rb -b unix:///tmp/mcps0.sock -c mcp/config.ru
- ```
- **With Passenger:**
- ```bash
- passenger start --rackup mcp/config.ru --socket /tmp/mcps0.sock
- ```
- And configure your web server to proxy to the socket:
- ```nginx
- location /mcp/ {
- proxy_pass http://unix:/tmp/mcps0.sock:;
- proxy_set_header Host $host;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- }
- ```
- ### 3. Nginx With Passenger
- You can run both the main app and the MCP app using Passenger processes within Nginx.
- ```nginx
- location / {
- root /path/to/current/public;
- passenger_app_root /path/to/current;
- passenger_enabled on;
- # ... additional configuration for the main Rails app
- }
- location ~* ^/mcp {
- root /path/to/current/public;
- passenger_app_root /path/to/current;
- passenger_enabled on;
- passenger_startup_file mcp/config.ru;
- passenger_app_group_name mcp;
- }
- ```
- You must set the `config.action_mcp.base_path` to match the above Nginx configuration, i.e. `config.action_mcp.base_path = '/mcp'`.
- **Key Points:**
- - MCPS0 is a standalone Rack app—run it separately from your main Rails server.
- - You can expose it via a TCP port (e.g., 62770) or a Unix socket.
- - Use a reverse proxy (Nginx, Apache, etc.) to route requests to MCPS0 as needed.
- - This separation ensures reliability and scalability for both your main app and MCP services.
- ## Generators
- ActionMCP includes Rails generators to help you quickly set up your MCP server components.
- First, install ActionMCP to create base classes and configuration:
- ```bash
- bin/rails action_mcp:install:migrations # to copy the migrations
- bin/rails generate action_mcp:install
- ```
- This will create the base application classes, configuration file, authentication gateway, `mcp/config.ru` rackup file, and `bin/mcp` binstub in your app directory.
- ### Generate a New Prompt
- ```bash
- bin/rails generate action_mcp:prompt AnalyzeCode
- ```
- ### Generate a New Tool
- ```bash
- bin/rails generate action_mcp:tool CalculateSum
- ```
- ## Testing with TestHelper
- ActionMCP provides a `TestHelper` module to simplify testing of tools and prompts:
- ```ruby
- require "test_helper"
- require "action_mcp/test_helper"
- class ToolTest < ActiveSupport::TestCase
- include ActionMCP::TestHelper
- test "CalculateSumTool returns the correct sum" do
- assert_mcp_tool_findable("calculate_sum")
- result = execute_mcp_tool("calculate_sum", a: 5, b: 10)
- assert_mcp_tool_output("15.0", result)
- end
- test "AnalyzeCodePrompt returns the correct analysis" do
- assert_mcp_prompt_findable("analyze_code")
- result = execute_mcp_prompt("analyze_code", language: "Ruby", code: "def hello; puts 'Hello, world!'; end")
- assert_mcp_prompt_output("Analyzing Ruby code: def hello; puts 'Hello, world!'; end", result)
- end
- end
- ```
- The TestHelper provides several assertion and execution methods:
- **Tools:**
- - `assert_mcp_tool_findable(name)` - Verifies a tool exists and is registered
- - `execute_mcp_tool(name, **args)` - Executes a tool with arguments and asserts success
- - `execute_mcp_tool_with_error(name, **args)` - Executes a tool without asserting success (for testing error cases)
- - `assert_mcp_tool_output(expected, response)` - Asserts tool output matches expected content
- **Prompts:**
- - `assert_mcp_prompt_findable(name)` - Verifies a prompt exists and is registered
- - `execute_mcp_prompt(name, **args)` - Executes a prompt with arguments
- - `assert_mcp_prompt_output(expected, response)` - Asserts prompt output matches expected content
- **Resource Templates:**
- - `assert_mcp_resource_template_findable(name)` - Verifies a resource template exists and is registered
- - `resolve_mcp_resource(uri)` - Resolves a resource URI and asserts success
- - `resolve_mcp_resource_with_error(uri)` - Resolves a resource URI without asserting success (for testing error cases)
- **General:**
- - `assert_mcp_error_code(code, response)` - Asserts a specific JSON-RPC error code
- ### Testing Resource Templates
- ```ruby
- require "test_helper"
- require "action_mcp/test_helper"
- class ProductResourceTest < ActiveSupport::TestCase
- include ActionMCP::TestHelper
- test "product template is registered" do
- assert_mcp_resource_template_findable("products")
- end
- test "resolves a product resource by URI" do
- resp = resolve_mcp_resource("ecommerce://products/1")
- assert resp.success?
- assert_not_empty resp.contents
- assert_equal "application/json", resp.contents.first.mime_type
- end
- test "returns error for nonexistent product" do
- resp = resolve_mcp_resource_with_error("ecommerce://products/0")
- assert resp.is_error
- end
- end
- ```
- ## Inspecting Your MCP Server
- You can use the MCP Inspector to test your server implementation:
- ```bash
- # Start your MCP server
- bundle exec rails s -c mcp/config.ru -p 62770
- # In another terminal, run the inspector
- npx @modelcontextprotocol/inspector --url http://localhost:62770
- ```
- The MCP Inspector provides an interactive interface to:
- - Test tool executions with custom arguments
- - Validate prompt responses
- - Inspect resource templates and their outputs
- - Debug protocol compliance and error handling
- ## Development Commands
- ActionMCP includes several rake tasks for development and debugging:
- ```bash
- # List all MCP components
- bundle exec rails action_mcp:list
- # List specific component types
- bundle exec rails action_mcp:list_tools
- bundle exec rails action_mcp:list_prompts
- bundle exec rails action_mcp:list_resources
- bundle exec rails action_mcp:list_widgets
- bundle exec rails action_mcp:list_profiles
- # Show configuration and statistics
- bundle exec rails action_mcp:info
- bundle exec rails action_mcp:stats
- # Show profile configuration
- bundle exec rails action_mcp:show_profile[profile_name]
- ```
- ### Linting
- RuboCop runs as a git pre-commit hook on staged Ruby files. Enable it once per clone:
- ```bash
- git config core.hooksPath .githooks
- ```
- ## Error Handling and Troubleshooting
- ActionMCP provides comprehensive error handling following the JSON-RPC 2.0 specification:
- ### Error Codes
- - **-32601**: Method not found - The requested method doesn't exist
- - **-32002**: Consent required - Tool requires user consent to execute
- - **-32603**: Internal error - Server encountered an unexpected error
- - **-32600**: Invalid request - The request is malformed
- ### Context-Aware Error Messages
- Tools should return clear error messages to the LLM using the `render` method:
- ```ruby
- class MyTool < ApplicationMCPTool
- def perform
- # Check for error conditions and return clear messages
- if some_error_condition?
- report_error("Clear error message for the LLM")
- return
- end
- # Normal processing
- render(text: "Success message")
- end
- end
- ```
- ### Common Issues
- 1. **Session not found**: Ensure sessions are properly created and saved in the session store
- 2. **Tool not registered**: Verify tools are properly defined and inherit from ApplicationMCPTool
- 3. **Consent required**: Grant consent using `session.grant_consent(tool_name)`
- 4. **Middleware conflicts**: Use `mcp_vanilla.ru` to avoid web-specific middleware
- ### Debugging Tips
- - Check server logs for detailed error information
- - Use `bundle exec rails action_mcp:info` to verify configuration
- - Test with MCP Inspector to isolate protocol issues
- - Ensure proper session management in production environments
- ## Profiles
- ActionMCP supports a flexible profile system that allows you to selectively expose tools, prompts, and resources based on different usage scenarios. This is particularly useful for applications that need different MCP capabilities for different contexts (e.g., public API vs. admin interface).
- ### Understanding Profiles
- Profiles are named configurations that define:
- - Which tools are available
- - Which prompts are accessible
- - Which resources can be accessed
- - Configuration options like logging level and change notifications
- By default, ActionMCP includes two profiles:
- - `primary`: Exposes all tools, prompts, and resources
- - `minimal`: Exposes no tools, prompts, or resources by default
- ### Configuring Profiles
- Profiles are configured via a `config/mcp.yml` file in your Rails application. If this file doesn't exist, ActionMCP will use default settings from the gem.
- **Example configuration:**
- ```yaml
- default:
- tools:
- - all # Include all tools
- prompts:
- - all # Include all prompts
- resources:
- - all # Include all resources
- options:
- list_changed: false
- logging_enabled: true
- logging_level: info
- resources_subscribe: false
- api_only:
- tools:
- - calculator
- - weather
- prompts: [] # No prompts for API
- resources:
- - user_profile
- options:
- list_changed: false
- logging_level: warn
- admin:
- tools:
- - all
- options:
- logging_level: debug
- list_changed: true
- resources_subscribe: true
- ```
- Each profile can specify:
- - `tools`: Array of tool names to include (use `all` to include all tools)
- - `prompts`: Array of prompt names to include (use `all` to include all prompts)
- - `resources`: Array of resource names to include (use `all` to include all resources)
- - `options`: Additional configuration options:
- - `list_changed`: Whether to send change notifications
- - `logging_enabled`: Whether to enable logging
- - `logging_level`: The logging level to use
- - `resources_subscribe`: Whether to enable resource subscriptions
- ### Switching Profiles
- You can switch between profiles programmatically in your code:
- ```ruby
- # Permanently switch to a different profile
- ActionMCP.configuration.use_profile(:only_tools) # Switch to a profile named "only_tools"
- # Temporarily use a profile for a specific operation
- ActionMCP.with_profile(:minimal) do
- # Code here uses the minimal profile
- # After the block, reverts to the previous profile
- end
- ```
- This makes it easy to control which MCP capabilities are available in different contexts of your application.
- ### Inspecting Profiles
- ActionMCP includes rake tasks to help you manage and inspect your profiles:
- ```bash
- # List all available profiles with their configurations
- bin/rails action_mcp:list_profiles
- # Show detailed information about a specific profile
- bin/rails action_mcp:show_profile[admin]
- # List all tools, prompts, resources, UI widgets, and profiles
- bin/rails action_mcp:list
- ```
- The profile inspection tasks will highlight any issues, such as configured tools, prompts, or resources that don't actually exist in your application.
- ### Use Cases
- Profiles are particularly useful for:
- 1. **Multi-tenant applications**: Use different profiles for different customer tiers with Dorp or other gems
- 2. **Access control**: Create profiles for different user roles (admin, staff, public)
- 3. **Performance optimization**: Use a minimal profile for high-traffic endpoints
- 4. **Testing environments**: Use specific test profiles in your test environment
- 5. **Progressive enhancement**: Start with a minimal profile and gradually add capabilities
- By leveraging profiles, you can maintain a single ActionMCP codebase while providing tailored MCP capabilities for different contexts.
- ## Client Usage
- ActionMCP includes a client for connecting to remote MCP servers. The client handles session management, protocol negotiation, and provides a simple API for interacting with MCP servers.
- For comprehensive client documentation, including examples, session management, transport configuration, and API usage, see [CLIENTUSAGE.md](CLIENTUSAGE.md).
- ## Production Considerations
- ### Security
- - **Never expose sensitive data** through MCP components
- - **Use authentication** via Gateway for production deployments
- - **Implement proper authorization** in your tools and prompts
- - **Validate all inputs** using property definitions and Rails validations
- - **Use consent management** for sensitive operations
- - **Protect against DNS rebinding**: ActionMCP validates the `Origin` header on every request without trusting the request's `Host` header. Loopback origins (`localhost`, `127.0.0.1`, and `::1`) are allowed by default. Other browser origins receive HTTP 403 unless their host is explicitly listed in `allowed_origins`. Non-browser clients that omit `Origin` are unaffected:
- ```ruby
- # config/initializers/action_mcp.rb
- ActionMCP.configure do |config|
- config.allowed_origins = ["app.example.com", "api.example.com"]
- end
- ```
- For defence-in-depth, also configure Rails' `ActionDispatch::HostAuthorization` to restrict which `Host` headers are accepted (a separate check against host-header injection):
- ```ruby
- # config/environments/production.rb
- config.hosts = ["api.example.com"]
- ```
- ### Performance
- - **Configure appropriate thread pools** for high-traffic scenarios
- - **Use Redis or SolidMCP** for production pub/sub
- - **Choose ActiveRecord session store** for session persistence
- - **Monitor session cleanup** to prevent memory leaks
- - **Use profiles** to limit exposed capabilities
- ### Monitoring
- - **Enable logging** and configure appropriate log levels
- - **Monitor session statistics** using `action_mcp:stats`
- - **Track tool usage** and performance metrics
- - **Set up alerts** for error rates and response times
- ### Deployment
- - **Use Falcon** for optimal performance with streaming workloads
- - **Deploy on dedicated ports** or Unix sockets
- - **Use reverse proxies** (Nginx, Apache) for SSL termination
- - **Implement health checks** for your MCP endpoints
- - **Use `mcp_vanilla.ru`** to avoid middleware conflicts
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.