- Add null checks for client_id before using in OAuthTransaction, AuthorizationCode, AccessToken, RefreshToken
- Add null check for redirect_uris before len() call
- Import AuthorizeError from mcp.server.auth.provider
Allow traceback-related kwargs to override defaults by building a dict
with defaults first, then updating with user-provided values.
Fixes#2356
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: William Easton <strawgate@users.noreply.github.com>
OAuth consent tests were timing out on Windows due to SQLite database
locking when OAuthProxy instances used the default DiskStore without
explicit MemoryStore configuration. Added explicit client_storage=MemoryStore()
to three tests in TestConsentPageServerIcon.
Also restored parallel testing on Windows (--numprocesses auto) which
was previously disabled but is now safe with proper test isolation.
* Fix consent form action for subpath mounting
When a FastMCP server is mounted at a subpath (e.g., /api/v1), the consent
form used a hardcoded absolute path (/consent/submit) that didn't include
the mount prefix, causing 404 errors on submission.
Changed the form to use an empty action (action="") which submits to the
current URL, making it work correctly regardless of mount path. Also
consolidated the consent endpoints to handle both GET and POST at /consent.
Fixes#2380
* Update integration test to use /consent instead of /consent/submit
* Allow OAuth instance to use the same httpx factory as the Transport
* Fix test
* Update SSL verification mode assertion in tests
* This is actually not needed
* Creating a Client instance is not needed for this test
* Fix test
* Apply httpx_client_factory fix to SSETransport
Extends the OAuth httpx_client_factory changes to SSETransport.
SSETransport had the same issues as StreamableHttpTransport where it
wasn't passing the custom httpx client factory to OAuth, causing
certificate verification settings to be ignored during OAuth flows.
Changes:
- Set httpx_client_factory before calling _set_auth()
- Pass httpx_client_factory to OAuth constructor
- Add test for SSETransport OAuth client factory propagation
---------
Co-authored-by: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>
* Fix OAuth metadata endpoint URLs when base_url differs from issuer_url
OAuth operational endpoints (/authorize, /token) are mounted at base_url,
but metadata was incorrectly declaring them at issuer_url. This caused
clients following the documented mounting pattern to receive incorrect
endpoint URLs in /.well-known/oauth-authorization-server.
Fixes#2287
* Update auth.py
* Remove unnecessary assertion from OAuthProvider init
* Add info log when issuer_url differs from base_url
* feat: Add optional meta parameter to Client tool call methods
* fix: Add support for mcp<1.19
* chore: cleaner solution
* Refactor call_tool to directly accept meta parameter and add tests for meta functionality
---------
Co-authored-by: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>
* Add manual initialization control to Client
- Add auto_initialize parameter (default True) to control automatic initialization
- Make initialize() method public with idempotent caching
- Add comprehensive test suite for initialization behavior
* Document client initialization control and server instructions
- Expand documentation to cover auto_initialize parameter
- Show manual initialization for advanced use cases
- Document accessing server instructions via initialize_result
* Update client.mdx
* Bump ty to >=0.0.1a25 with type fixes
Follow-up to #2295. Updates ty and fixes compatibility issues with alpha 25, including:
- Updated ignore comment syntax (possibly-unbound-attribute → possibly-missing-attribute)
- Fixed async generator type handling with anext()
- Fixed type narrowing for timeout parameters
- Converted base_url assignments to AnyHttpUrl after string manipulation
- Added CallToolResult to return type annotations
- Removed redundant type casts
- Fixed test form data to use strings instead of bytes
ty alpha 25 has limitations with isinstance() narrowing on unions (see pyproject.toml for details), requiring some targeted type ignores.
* Pin ty to ==0.0.1a25
Alpha releases can have breaking changes, so pin to the tested version.
* 🤖 Security: Validate Cursor deeplink URLs and replace cmd.exe on Windows
- Add URL scheme validation to reject non-cursor:// URLs
- Replace subprocess cmd.exe call with os.startfile() on Windows
- Add tests for scheme validation and error handling
* 🤖 Fix tests for cross-platform deeplink validation
* Add meta to ToolResult
* add this at the client level and test the full integration
* add example
* slipped through linting somehow
---------
Co-authored-by: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>
* Mark flaky Windows test for retry
test_multi_client_transform_with_filtering occasionally times out on Windows CI during exception formatting in linecache.checkcache(). Add @pytest.mark.flaky with 3 retries.
* Remove unnecessary delay from flaky marker
* Added to_data_uri method and path_to_data_uri classmethod for Image class.
* Removed path_to_data_uri classmethod and modified _get_mime_type to use mimetypes.guess_type function instead of hardcoded dictionary.
* Register image/webp with mimetypes before guess_type to support WEBP mimetype detection on Python 3.10.
* Improved branch coverage for Image.to_data_uri.
* Added Image._to_data_uri example in the docs.
* Add custom token verifier support to OIDCProxy
OIDCProxy now accepts an optional token_verifier parameter to support
non-JWT token formats like opaque tokens from providers such as Clerk.
When provided, the custom verifier is used instead of creating a default
JWTVerifier. Parameters that only apply to JWTVerifier creation (algorithm,
required_scopes) raise clear errors when specified alongside a custom
verifier. Parameters with other purposes (audience for OAuth flow,
timeout_seconds for config fetch) remain allowed.
The custom verifier's required_scopes are automatically loaded and
advertised through OAuth discovery endpoints.
* Document custom token verifier support in OIDC proxy
* Update docs for required scopes
* add scopes
* Fix Azure scope validation
Azure returns unprefixed scopes in JWT tokens but requires prefixed scopes in authorization requests. The previous implementation incorrectly validated tokens against prefixed scopes, causing "invalid_token" errors.
Simplified AzureProvider to use standard JWTVerifier with unprefixed scopes for validation. Scopes are only prefixed when building the Azure authorization URL via _build_upstream_authorize_url() override.
Closes#2263
* Checkpoint progress
* Checkpoint progress
* add derive b64 method
* PR clean-up
* refactor da proxy
* Updates to tests
* Make jwt_signing_key required for oauth proxy
* use typing_extensions and fix tests
* PR Cleanup
* also adjust integration tests
* Update docs, use client secret to derive jwt signing key
* You win some you lose some, gg claude
* check for both in derive
* update documentation / clean up
* Update http.mdx
---------
Co-authored-by: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>
* Add compatibility tools contrib module
Implements four standalone tools that expose resources and prompts
as callable tools for clients that only support the tools capability.
Features:
- list_resources: List all available resources
- get_resource: Read a resource by URI
- list_prompts: List all available prompts
- get_prompt: Get a prompt with optional arguments
The tools use Context to access the server instance and can be easily
added to any FastMCP server using the add_compatibility_tools helper
or by adding individual tool instances directly.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: William Easton <strawgate@users.noreply.github.com>
* Simplify compatibility tools to return raw MCP protocol objects
Return raw MCP protocol objects (ListResourcesResult, ReadResourceResult,
ListPromptsResult, GetPromptResult) instead of custom dictionaries. This
makes the tools simpler and more predictable by directly exposing what
the client methods return.
Co-authored-by: William Easton <strawgate@users.noreply.github.com>
* Add tool injection middleware
* cleanup contrib module
* More clean-up
* Clean up tool injection middleware.
* Update src/fastmcp/server/middleware/tool_injection.py
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* Add tool injection docs
* Small cleanup of prompt middleware
* PR Feedback
* Fix tool injection tests
---------
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: William Easton <strawgate@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* feat: use abstract collection types in FastMCP.__init__
Use Sequence, Collection, and Mapping from collections.abc for more
flexible typing in FastMCP.__init__ parameters. This allows downstream
developers to pass tuples, sets, and other collection types instead of
being restricted to list and dict.
Changes:
- middleware: list -> Sequence (converted to list internally)
- tools: list -> Sequence
- tool_transformations: dict -> Mapping (ToolManager updated)
- include_tags: set -> Collection
- exclude_tags: set -> Collection
- dependencies: kept as list per maintainer request
Closes#2212
Co-authored-by: William Easton <strawgate@users.noreply.github.com>
* Concrete types in class inits
* Small imports cleanup
* Fix include/exclude tag handling
---------
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: William Easton <strawgate@users.noreply.github.com>
* Fix Azure scope mismatch causing MCP client validation errors
The AzureProvider was prefixing scopes during authorization but not in
token validation or Protected Resource Metadata, causing MCP clients to
reject tokens with "Server granted unauthorized scopes".
Changes:
- Prefix required_scopes once during __init__ and use consistently
- Pass prefixed scopes to JWTVerifier for token validation
- PRM now advertises prefixed scopes to MCP clients
- Remove unnecessary idempotent prefixing logic in authorize()
- Update comprehensive documentation explaining scope handling
- Update tests to reflect corrected behavior
Closes#2151
* Clarify that identifier_uri is optional in docstring
This test makes external HTTP requests to GitHub and is subject to
network latency, causing CI timeouts. Marking it as an integration test
excludes it from default test runs while keeping it available for
explicit integration testing.
Co-authored-by: William Easton <strawgate@users.noreply.github.com>
* Enhance OAuth Proxy error responses with branded HTML pages
OAuth Proxy authentication errors now show styled HTML error pages in browsers
instead of raw JSON, with content negotiation for API clients. Enhanced error
messages explain common causes (ephemeral storage, server restarts) and provide
clear remediation steps.
Changes:
- Created enhanced authorization handler that extends SDK's AuthorizationHandler
- Created enhanced auth middleware that extends SDK's RequireAuthMiddleware
- HTML error pages use server branding (icon, name) from FastMCP instance
- Added comprehensive troubleshooting section to OAuth Proxy docs
- Added FAQ entry linking to detailed troubleshooting
* Add comprehensive tests for enhanced OAuth error responses
Tests cover:
- HTML error pages for browser requests with server branding
- Enhanced JSON responses with registration endpoint hints
- Content negotiation between HTML and JSON
- Enhanced middleware error messages for invalid_token
- WWW-Authenticate header format consistency with SDK
* Update language for new storage defaults
* update docs
* Update tests for simplified error messages
* Clean up messages
* Add comprehensive keyring integration tests
Prevents OS keyring pollution during testing by adding a global mock in
conftest.py. Tests verify keyring behavior across platforms and fallback
scenarios without writing to the actual system keyring.
- Add global mock_keyring fixture to tests/conftest.py
- Add TestOAuthProxyKeyring class with 6 keyring-specific tests
- Remove try/except ImportError for keyring (now required dependency)
- Add keyring extra to py-key-value-aio dependency
- Clean up extraneous implementation comments in oauth_proxy.py
* Update OAuth keyring documentation
Update all OAuth-related documentation to reflect keyring-based key management:
- Add version badges to jwt_signing_key, token_encryption_key, and client_storage parameters
- Standardize "Default behavior (`None`):" formatting with backticks
- Ensure consistent messaging about development-only defaults across all docs
- Update oauth-proxy.mdx, oidc-proxy.mdx, http.mdx, storage-backends.mdx, and upgrade-guide.mdx
* Use anyio as testing backend
* Remove asyncio markers
* Update streamable http tests
* Replace all subprocess tests
* Replace anyio task groups with asyncio context managers in tests
- Convert run_server_async from anyio task group pattern to asyncio.create_task with async context manager
- Remove task_group fixture from conftest
- Update all test fixtures to use async with run_server_async pattern
- Remove TaskGroup imports from all test files
- Tests now work with pytest-asyncio instead of pytest-anyio
* Update test_github_provider_integration.py
* Implement icon support in fastmcp
* Fix icon feature tests
- Update snapshot for ResourceTemplate to include icons field
- Remove OAuth mounting tests (belong to PR #2119, not this feature)
* Update docs
* Customize consent screen
* Use server website link if available
* Anchor link shouldnt have trailing slash
* Remove 'a FastMCP server named' from consent page message
* Update docs
* Implement icon support in fastmcp
* Fix icon feature tests
- Update snapshot for ResourceTemplate to include icons field
- Remove OAuth mounting tests (belong to PR #2119, not this feature)
* Update docs
* Add issuer_url parameter to OAuth providers for mounting scenarios
* Add get_well_known_routes
* Update docs
* Improve docs and tests
* Trigger CI
* Fix conditional test execution for Windows
* Upgrade to MCP 1.17+ with RFC 9728 compliance
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)
* Fix RemoteAuthProvider integration tests for RFC 9728
* Fix parameterized test for nested base URL paths
