FastMcp JWT Auth

JWT Authorization header authentication extension for FastMcp RackTransport.

This gem extends the FastMcp gem to enable JWT-based user authentication via Authorization headers in Rails applications. It provides configurable callbacks for token decoding, user lookup, and validation.

Problem

FastMcp::Transports::RackTransport doesn't have built-in JWT authentication support. For integrating with external MCP clients that use JWT tokens for authentication, you need a way to:

1. Extract JWT tokens from Authorization headers
2. Decode and validate the tokens
3. Find users based on token payload
4. Set Current.user for the request duration

Solution

This gem provides a monkey patch for FastMcp::Transports::RackTransport that:

1. Extracts JWT tokens from Authorization: Bearer headers
2. Decodes tokens using configurable callbacks
3. Validates token expiration and other claims
4. Finds users using configurable lookup logic
5. Sets Current.user for request duration
6. Cleans up Current after request processing

Installation

Prerequisites: This gem requires the fast-mcp gem to be installed first.

Add both gems to your application's Gemfile:

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

And then execute:

bundle install

Note: The fast-mcp gem provides the core MCP (Model Context Protocol) server functionality, while this gem extends it with JWT authentication support.

Usage

Automatic Integration

No configuration needed for basic usage! Just add the gem to your Gemfile and configure the callbacks.

The gem will:

• ✅ Automatically patch FastMcp::Transports::RackTransport during Rails initialization
• ✅ Extract JWT tokens from Authorization: Bearer headers automatically
• ✅ Use Rails.logger for logging (no configuration required)
• ✅ Handle errors gracefully with fallback to normal request processing

MCP Server Configuration

⚠️ IMPORTANT: This gem enables JWT authentication for your Rails application when used with the fast_mcp gem. For MCP clients to authenticate with your Rails app, they need to send JWT tokens in the Authorization: Bearer header.

Client-Side MCP Configuration

When your Rails app is running as an MCP server (using fast_mcp gem and fast_mcp_jwt_auth gem), MCP clients need to be configured with proper authentication headers to connect to it.

For example create or update your .mcp.json configuration file:

cp .mcp.json.example .mcp.json

Critical: The headers section with Authorization: Bearer is essential for JWT authentication:

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

Real Example - WorkVector Integration

{
  "mcpServers": {
    "workvector-production": {
      "type": "sse",
      "name": "WorkVector Production", 
      "url": "https://workvector.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer ${WORKVECTOR_TOKEN}"
      }
    }
  }
}

Why Headers are Critical

❌ This WON'T work - missing authentication:

{
  "mcpServers": {
    "your-app": {
      "type": "sse",
      "url": "https://your-app.com/mcp/sse"
    }
  }
}

✅ This WILL work - includes JWT authentication header:

{
  "mcpServers": {
    "your-app": {
      "type": "sse", 
      "url": "https://your-app.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer ${JWT_TOKEN}"
      }
    }
  }
}

Environment Variables

Use environment variables for sensitive tokens in your .mcp.json:

• `${

... View full README on GitHub