🚀 Multi-Worker Cluster Support for fast-mcp Rails Applications

[Pepan]

Hi fast-mcp community! 👋

I wanted to share a new gem that extends the excellent fast-mcp to work seamlessly with Puma cluster mode (multiple workers) in Rails applications.

The Problem

When using fast-mcp with Puma's cluster mode (multiple workers), Server-Sent Events (SSE) clients connected to one worker don't receive messages broadcast from other workers. This happens because FastMcp::Transports::RackTransport stores clients in an in-memory hash @sse_clients that's isolated per worker process.

The Solution: fast_mcp_pubsub

I've created fast_mcp_pubsub - a Rails gem that adds PostgreSQL NOTIFY/LISTEN clustering support to fast-mcp, enabling message broadcasting across all Puma workers.

How It Works

1. Patches FastMcp::Transports::RackTransport#send_message to broadcast via PostgreSQL NOTIFY
2. Each worker runs a dedicated listener thread for PostgreSQL LISTEN
3. When a message is received, it's delivered to all local SSE clients in that worker
4. Falls back to local delivery if PubSub fails

Quick Setup Guide

If you already have fast-mcp working in your Rails app, here's how to add multi-worker support:

Step 1: Add the Gem

# Gemfile
gem 'fast-mcp', '~> 1.5.0'                              # Your existing fast-mcp
gem 'fast_mcp_pubsub', github: 'jchsoft/fast_mcp_pubsub' # Add this extension (GitHub for now)

Step 2: Bundle Install

bundle install

Step 3: Configure (Optional)

Create config/initializers/fast_mcp_pubsub.rb:

FastMcpPubsub.configure do |config|
  config.enabled = Rails.env.production?  # Enable in production cluster
  config.channel_name = 'mcp_broadcast'   # PostgreSQL channel name
  config.auto_start = true                # Auto-start listener threads
  config.logger = Rails.logger
end

Step 4: Setup Puma Cluster Mode

# config/puma/production.rb
workers ENV.fetch("WEB_CONCURRENCY") { 2 }  # Multiple workers
preload_app!

on_worker_boot do
  Rails.logger.info "MCP Transport: Starting PubSub listener for cluster mode worker #{Process.pid}"
  FastMcpPubsub::Service.start_listener
end

Step 5: Deploy and Test! 🎉

That's it! Your existing fast-mcp setup now works across multiple Puma workers with zero code changes to your MCP resources or tools.

Requirements

• Rails 7.0+ (uses Railtie for integration)
• PostgreSQL database (requires NOTIFY/LISTEN - won't work with MySQL/SQLite)
• Puma web server in cluster mode
• Your existing fast-mcp setup (this is an extension, not a replacement)

Features

✅ Zero code changes - your existing MCP resources work unchanged
✅ Automatic integration - hooks into Rails and Puma lifecycle
✅ Fallback mechanism - degrades gracefully if PubSub fails
✅ Thread-safe - designed for multi-worker environments
✅ Error handling - automatic retry with backoff for transient errors
✅ Payload size limits - handles PostgreSQL NOTIFY 8KB limit with error responses

Real-World Usage

We're using this in production at WorkVector.com with multiple Puma workers, handling MCP requests from Claude Code IDE. It seamlessly broadcasts responses to all connected clients regardless of which worker they're connected to.

Links

• GitHub: https://github.com/jchsoft/fast_mcp_pubsub
• RubyGems: https://rubygems.org/gems/fast_mcp_pubsub (planned for future release)

Note: For now, install directly from GitHub as shown in Step 1. RubyGems release planned once we gather community feedback.

Questions?

Happy to answer questions or help with integration! This gem is designed to be a drop-in extension for existing fast-mcp Rails applications.

Thanks to @yjacquin for the excellent fast-mcp foundation! 🙏

---

This extension was developed for WorkVector.com to support Claude Code MCP integration in production cluster environments.

[JrmKrb]

Using this right now at Matera, thanks a lot for the contribution!

[Pepan]

I am very happy to hear that.