Action MCP Example 🚀

A simple Ruby on Rails application demonstrating how to integrate and use the ActionMCP gem. The gem source code can be found on GitHub at https://github.com/seuros/mcp.

This application showcases how to define and use MCP components within a Rails project.

Requirements

• Ruby (see .ruby-version for recommended version)
• PostgreSQL (or Docker)

Getting Started

1. Clone and Setup

git clone https://github.com/seuros/mcp_rails_template.git
cd mcp_rails_template
bin/setup

2. Environment Configuration

Copy the provided .env.example file:

cp .env.example .env

Edit .env and fill in necessary values according to your setup (especially any required API keys for tools like fetch_weather_by_location_tool).

3. Database Setup

You can quickly spin up a temporary PostgreSQL instance using Docker:

make up

This will start PostgreSQL on port 5466.

Alternatively, configure your own PostgreSQL database by editing config/database.yml.

4. Run the Application

Launch the Rails server:

bin/rails s

The app will be available at http://localhost:3002.

ActionMCP Server

ActionMCP runs as a standalone server on port 62770 (via mcp.ru). Nginx proxies /mcp requests to this server.

Client → nginx:8080/mcp → ActionMCP:62770

Authentication

This application uses JWT-based authentication via the ApplicationGateway class.

Test Users (from fixtures)

Loading Fixtures

bin/rails db:fixtures:load FIXTURES=users

Generating a JWT Token

# In Rails console
user = User.find_by(email: 'test@example.com')
token = user.generate_jwt(expires_in: 10.years)  # Long-lived for demo

MCP Client Configuration

A .mcp.json file is provided with a pre-configured long-lived token:

{
  "mcpServers": {
    "mcp_rails_template": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Or test manually with curl:

curl -H "Authorization: Bearer <token>" http://localhost:8080/mcp

Gateway Configuration

The gateway is configured in config/mcp.yml:

development:
  authentication: ["jwt"]
  gateway_class: "ApplicationGateway"

Accessing User in Tools

class MyTool < ApplicationMCPTool
  def perform
    render text: "Hello #{current_user.name}!"
  end
end

MCP Components (app/mcp/)

This application includes several examples of ActionMCP components:

Prompts (app/mcp/prompts/)

• epic_adventure_prompt.rb: Generates a short, narrative adventure story based on a provided hero name and adventure type (fantasy, sci-fi, mystery). It can optionally include a placeholder image data string.

Resource Templates (app/mcp/resource_templates/)

• gemfile_template.rb: Provides access to the project's Gemfile dependencies as a JSON resource. It uses Bundler to fetch gems based on the specified environment (production, test, development, or default). The resource URI follows the pattern gemfile://{environment}.

Tools (app/mcp/tools/)

Tools define specific actions that a language model can request to be executed.

• dependency_info_tool.rb: Retrieves dependency information using Bundler from the Gemfile and Gemfile.lock. It also checks for a .gemspec file for runtime dependencies. It outputs separate JSON resources for production, test, and runtime dependencies.
• fetch_weather_by_location_tool.rb: Fetches weather forecast data from the Open-Meteo API (https://api.open-meteo.com) based on provided latitude and longitude coordinates. It returns the raw JSON response from t

... View full README on GitHub