Support MCP 2025-06-18 Protocol Revision

[yjacquin]

Update MCP protocol version to 2025-06-18

This branch regroups all issues to come from #109

• Update PROTOCOL_VERSION constant from '2024-11-05' to '2025-06-18'
• Add MCP-Protocol-Version header validation to BaseTransport
• Implement protocol version validation in RackTransport
• Add proper error responses for unsupported protocol versions
• Maintain backward compatibility with lenient validation

Closes #109

[Copilot]

Pull Request Overview

This PR implements comprehensive support for the MCP 2025-06-18 protocol revision by updating the protocol version, adding extensive test coverage, and implementing new transport layers with OAuth 2.1 support and metadata validation.

• Updates PROTOCOL_VERSION constant from '2024-11-05' to '2025-06-18' throughout the codebase
• Implements new StreamableHTTP transport with unified endpoint support and protocol version validation
• Adds OAuth 2.1 compliant transport with scope-based authorization and RFC 9728 protected resource metadata

Reviewed Changes

Copilot reviewed 45 out of 53 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
spec/ files	Comprehensive test coverage for new OAuth functionality, transport layers, and compliance validation
lib/mcp/transports/	New transport implementations including StreamableHTTP, OAuth, and authenticated variants
lib/mcp/protocol_version.rb	Centralized protocol version definition
lib/mcp/oauth/	OAuth 2.1 implementation with token validation and resource server components
lib/mcp/metadata.rb	Metadata validation with reserved prefix checking
examples/	Demonstration servers showing new transport capabilities

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[spikex]

Hey @yjacquin, thanks for your great work on this project! Any timeline on releasing 2025-06-18 support?

[alejandrok93]

hi @yjacquin wanted to check if this PR is ready to merge?

[quorak]

Hey there, massive amount of work. thank you!

We’re currently trying to use OpenID Connect with Doorkeeper as our auth server in a Rails stack. Token issuing works, and we’re also able to connect via the http_streaming method.

Our opaque_token_validator successfully receives the Bearer token, validates it against Doorkeeper, and returns a valid hash with scope (including mcp:tools), subject, and other fields.

However, when we try to list the available tools, the request fails with:

MCP error -32001: Error POSTing to endpoint (HTTP 403):
{"error":"invalid_scope","error_description":"Required scope: mcp:tools"}

I debugged into it and It looks like its trying to extract the extract_claims:

• It looks like TokenValidator.extract_claims is not working for opaque_token and always returns an empty scope.

• The call chain is as follows: ResourceServer.extract_token_info -->LocalIntrospector.token_info --> TokenValidator.extract_claims

Not totally sure what the right approach here would be. Hope this helps!

[postpostmodern]

Hey there, massive amount of work. thank you!

We’re currently trying to use OpenID Connect with Doorkeeper as our auth server in a Rails stack. Token issuing works, and we’re also able to connect via the http_streaming method.

Our opaque_token_validator successfully receives the Bearer token, validates it against Doorkeeper, and returns a valid hash with scope (including mcp:tools), subject, and other fields.

However, when we try to list the available tools, the request fails with:

MCP error -32001: Error POSTing to endpoint (HTTP 403):
{"error":"invalid_scope","error_description":"Required scope: mcp:tools"}

I debugged into it and It looks like its trying to extract the extract_claims:

* It looks like [TokenValidator.extract_claims](https://github.com/yjacquin/fast-mcp/blob/5892fcc2a5fa39cfac39b279ce1a08f4573f3c3f/lib/mcp/oauth/token_validator.rb#L59) is not working for opaque_token and always returns an empty scope.

* The call chain is as follows: [ResourceServer.extract_token_info](https://github.com/yjacquin/fast-mcp/blob/5892fcc2a5fa39cfac39b279ce1a08f4573f3c3f/lib/mcp/oauth/resource_server.rb#L75) -->[LocalIntrospector.token_info](https://github.com/yjacquin/fast-mcp/blob/mcp-2025-06-18/lib/mcp/oauth/introspection.rb#L16) --> [TokenValidator.extract_claims](https://github.com/yjacquin/fast-mcp/blob/5892fcc2a5fa39cfac39b279ce1a08f4573f3c3f/lib/mcp/oauth/token_validator.rb#L59)

Not totally sure what the right approach here would be. Hope this helps!

I had the same issue. I don't know if this is the best approach, but here's how I fixed it:

diff --git a/lib/mcp/oauth/token_validator.rb b/lib/mcp/oauth/token_validator.rb
index 97e7bf0..79c66b2 100644
--- a/lib/mcp/oauth/token_validator.rb
+++ b/lib/mcp/oauth/token_validator.rb
@@ -56,11 +56,20 @@ module FastMcp

       # Extract claims from a valid token (for debugging/logging)
       def extract_claims(token)
-        return nil unless jwt_token?(token)
-
-        # Decode without verification for claim extraction
-        payload, = JWT.decode(token, nil, false)
-        payload
+        if jwt_token?(token)
+          # Decode without verification for claim extraction
+          payload, = JWT.decode(token, nil, false)
+          payload
+        else
+          opaque_token_info = @opaque_token_validator.call(token)
+          opaque_token_info.transform_keys(
+            {
+              scopes: 'scope',
+              subject: 'sub',
+              valid: 'valid'
+            }
+          )
+        end
       rescue StandardError => e
         @logger.debug("Failed to extract claims: #{e.message}")
         nil

[manuelmeurer]

Hey @yjacquin , how can we help to get this over the finish line?