FastMcp JWT Auth - JWT Authentication Extension for FastMcp RackTransport

[Pepan]

👋 Hi everyone!

I'm excited to share a new extension for the amazing FastMcp gem that adds JWT authentication support to the RackTransport.

The Problem

While FastMcp provides excellent MCP (Model Context Protocol) server functionality for Rails applications, it doesn't have built-in support for JWT authentication via Authorization headers. This becomes essential when integrating with external MCP clients that need to authenticate users through JWT tokens.

Without proper JWT authentication, you can't:

• Authenticate MCP clients using JWT tokens
• Set Current.user based on token payload
• Integrate with systems that require user-specific authentication
• Maintain secure user context throughout MCP request processing

The Solution

FastMcp JWT Auth is a lightweight gem that monkey patches FastMcp::Transports::RackTransport to add seamless JWT authentication support.

🚀 Key Benefits:

• ✅ Zero configuration needed - just add to Gemfile and configure callbacks
• ✅ Automatic JWT extraction from Authorization: Bearer headers
• ✅ Thread-safe - works perfectly in multi-threaded Rails environments
• ✅ Configurable callbacks for token decoding, user lookup, and validation
• ✅ Graceful error handling - falls back to normal processing on auth failures
• ✅ Rails integration via Railtie for automatic setup

Quick Setup

1. Installation

Add to your Gemfile:

gem 'fast-mcp'                                    # Required base gem
gem 'fast_mcp_jwt_auth', github: 'jchsoft/fast_mcp_jwt_auth'

2. Configuration

Create an initializer:

# config/initializers/fast_mcp_jwt_auth.rb
FastMcpJwtAuth.configure do |config|
  config.enabled = true
  
  # JWT token decoding
  config.jwt_decoder = ->(jwt_token) do
    JWT.decode(jwt_token, Rails.application.credentials.secret_key_base, true, algorithm: 'HS256')[0]
  end
  
  # User lookup from decoded token
  config.user_finder = ->(decoded_token) do
    User.find_by(authentication_token: decoded_token['authentication_token'])
  end
end

3. Client Configuration

Configure MCP clients with JWT authentication:

{
  "mcpServers": {
    "your-rails-app": {
      "type": "sse",
      "name": "Your Rails MCP Server", 
      "url": "https://your-app.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer ${JWT_TOKEN}"
      }
    }
  }
}

Requirements

• Ruby >= 3.1.0
• Rails >= 7.0
• FastMcp gem

Features

✅ Automatic JWT Authentication - Extracts and validates JWT tokens from Authorization headers
✅ Configurable Callbacks - Customize token decoding, user lookup, and validation logic
✅ Thread Safety - Works seamlessly in multi-threaded Rails applications
✅ Current User Context - Automatically sets and cleans up Current.user
✅ Error Recovery - Graceful fallback when authentication fails
✅ Rails Integration - Automatic setup via Railtie, respects Rails logging
✅ Security Best Practices - Proper token handling and context cleanup
✅ Zero Dependencies - Only requires Rails and FastMcp

Real-World Usage

We're using this gem in production at WorkVector to enable secure MCP client authentication with our Rails application. It seamlessly handles JWT token validation and user context for thousands of MCP requests.

The gem arose from a practical need to integrate external MCP clients (like Claude Code) with our Rails application while maintaining proper user authentication and authorization.

How It Works

1. Request Interception - Patches FastMcp::Transports::RackTransport#send_message
2. Header Extraction - Looks for Authorization: Bearer <token> header
3. Token Processing - Uses configured callbacks to decode and validate JWT
4. User Lookup - Finds user based on token payload
5. Context Management - Sets Current.user for request duration
6. Cleanup - Automatically resets context after processing

Links

• GitHub: https://github.com/jchsoft/fast_mcp_jwt_auth
• Documentation: Comprehensive README with examples and configuration options
• Real Example: Used in production at WorkVector for MCP client authentication

Acknowledgments

Huge thanks to @yjacquin for creating the excellent FastMcp gem that made this extension possible! 🙏

---

Would love to hear your thoughts, questions, or feedback! This gem was born from a real production need, and I'm excited to see how the community might use it.

Has anyone else been looking for JWT authentication with FastMcp? What authentication patterns are you using with MCP servers?