Skip to content

Conversation

@jlowin
Copy link
Owner

@jlowin jlowin commented Oct 17, 2025

This PR upgrades FastMCP to require MCP 1.17+ and implements RFC 9728-compliant OAuth protected resource metadata URL handling.

Closes #2123, closes #2077

What Changed

The MCP Python SDK introduced a breaking change in version 1.17 to properly implement RFC 9728. OAuth protected resource metadata endpoints are now registered at path-aware locations rather than always at the root.

Before (MCP 1.16)

mcp = FastMCP("server", auth=auth_provider)
app = mcp.http_app(path="/mcp")

# Metadata was always at:
# GET /.well-known/oauth-protected-resource

After (MCP 1.17+)

mcp = FastMCP("server", auth=auth_provider)
app = mcp.http_app(path="/mcp")

# Metadata is now at the path-aware location:
# GET /.well-known/oauth-protected-resource/mcp

This ensures proper OAuth discovery for path-based resource servers and aligns with RFC 9728 §3.1 requirements.

Key Changes

  • Minimum MCP version: Now requires mcp>=1.17.0 (was >=1.12.4)
  • RFC 9728 compliance: FastMCP now uses build_resource_metadata_url() from the MCP SDK to construct metadata URLs
  • CI improvement: Tests now run with --upgrade to always validate against the latest compatible package versions
  • WWW-Authenticate headers: Now correctly point to path-aware metadata locations

Impact

This is a breaking change for servers using authentication with path-based mounting. If your MCP server is mounted at a path (e.g., /mcp, /api/v1/mcp), OAuth clients will need to discover metadata at the new path-aware location. I believe the core mechanism for what broke is that the WWW headers were pointing to the wrong location.

Servers mounted at the root path are unaffected.

Updates FastMCP to require MCP 1.17+ and implements RFC 9728-compliant
OAuth protected resource metadata URL handling.

The key change is that .well-known/oauth-protected-resource endpoints
are now registered at path-aware locations. For example, if an MCP
server is mounted at /mcp, the metadata endpoint is now at
/.well-known/oauth-protected-resource/mcp instead of
/.well-known/oauth-protected-resource.

This ensures proper OAuth discovery for path-based resource servers
and aligns with the MCP SDK's implementation of RFC 9728 §3.1.

Changes include:
- Update minimum MCP version from 1.12.4 to 1.17.0
- Use build_resource_metadata_url() for RFC 9728 compliance
- Configure CI to test with latest package versions (--upgrade)
- Update tests for path-aware metadata URLs
- Add icons field to Tool model (introduced in MCP 1.17)
@marvin-context-protocol marvin-context-protocol bot added enhancement Improvement to existing functionality. For issues and smaller PR improvements. breaking change Breaks backward compatibility. Requires minor version bump. Critical for maintainer attention. auth Related to authentication (Bearer, JWT, OAuth, WorkOS) for client or server. http Related to HTTP transport, networking, or web server functionality. labels Oct 17, 2025
@jlowin jlowin merged commit 4a9f02c into main Oct 17, 2025
11 of 12 checks passed
@jlowin jlowin deleted the upgrade-mcp-1.17 branch October 17, 2025 13:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

auth Related to authentication (Bearer, JWT, OAuth, WorkOS) for client or server. breaking change Breaks backward compatibility. Requires minor version bump. Critical for maintainer attention. enhancement Improvement to existing functionality. For issues and smaller PR improvements. http Related to HTTP transport, networking, or web server functionality.

Projects

None yet

2 participants