Add Keycloak OAuth Provider for Enterprise Authentication and local dev

[stephaneberle9]

Description

This PR implements native Keycloak OAuth support for FastMCP, enabling enterprise-grade authentication for organizations using Keycloak identity and access management infrastructure. The implementation provides a complete authentication provider that handles Keycloak User Realms with robust JWT token validation and Dynamic Client Registration (DCR) support. This contribution also significantly simplifies local development by providing a Docker-based Keycloak setup that allows developers to test OAuth flows instantly without external dependencies.

Contributors Checklist

• My change closes Add Keycloak OAuth Authentication Provider leveraging Dynamic Client Registration (DCR) #1918
• I have followed the repository's development workflow
• I have tested my changes manually and by adding relevant tests
• I have performed all required documentation updates

Review Checklist

• I have self-reviewed my changes
• My Pull Request is ready for review

[jlowin]

It feels like there's way too much going on in this PR. Did an LLM author this?

• The example should be a minimal server/client pair like all other auth providers. There should definitely not be a docker-compose file.
• keycloak.py seems to reimplement our oauthproxy AND oidcproxy while still claiming (in the linked issue) to natively support DCR? Ideally this would be a minor amount of configuration against one of FastMCP's establish auth classes.

[stephaneberle9]

It feels like there's way too much going on in this PR. Did an LLM author this?

I do use Claude Code, yes, but not "blindly". Means that I don't vibe-code my changes but meticulously review and iteratively adapt whatever it is suggesting. That said, I must admit that I'd missed to do that with the README.md of the new keycloak auth example which most probably has caused some degree of confusion. Sorry for that! I've fixed this as per 715aa92 now.

The example should be a minimal server/client pair like all other auth providers. There should definitely not be a docker-compose file.

Keycloak is a leading identity provider that has a big extra advantage: it can very easily be run locally using Docker or Docker Compose. Therefore, it is frequently used as a substitute for production IDPs to create fully self-contained local dev setups. The intent of this contribution is to enable both easy FastMCP auth support for productive Keycloak instances and use of Keycloak as IDP in local FastMCP dev setups.

That said, I fully understand that the presence of the Docker Compose configuration and scripts adds some extra complexity which compromises the idea of having simplistic examples. I therefore have reorganized the Keycloak example in the following way:

• All the Docker Compose stuff, the start script and an extra README.md file have been moved into the keycloak subfolder
• The example folder itself is now very similar to the other examples and basically only contains the server.py and client.py files
• The README.md file in this folder is also very compact now. It clearly indicates that there two options: running the example with an already existing Keycloak instance or creating a local Keycloak dev instance with Docker Compose. For the details regarding how to proceed in the second case the user is referred to more detailed instructions in the README.md located in the keycloak subfolder.

keycloak.py seems to reimplement our oauthproxy AND oidcproxy while still claiming (in the linked issue) to natively support DCR? Ideally this would be a minor amount of configuration against one of FastMCP's establish auth classes.

No, the KeycloakAuthProvider is clearly NOT a reimplementation of OAuthProxy/OIDCProxy. It's a fundamentally different architecture:

OAuthProxy/OIDCProxy: Full OAuth authorization server that translates between non-DCR IDPs and DCR-expecting clients
KeycloakAuthProvider: Lightweight metadata proxy that exposes Keycloak's native DCR with minimal request/response modifications

What the KeycloakAuthProvider does:

• Extends RemoteAuthProvider (NOT OAuthProvider)
• Does NOT implement the OAuth flow
• Does NOT store tokens, codes, or manage OAuth state
• Only proxies 3 HTTP endpoints for metadata/request modifications:
  • /.well-known/oauth-authorization-server - Metadata discovery
  • /register - DCR with scope injection
  • /authorize - Authorization with scope injection

Key proofs we're NOT reimplementing::

• KeycloakAuthProvider doesn't require any client ID or client secret at instantiation - because it doesn't need to authenticate with Keycloak on behalf of clients. In contrast, OAuthProxy/OIDCProxy require upstream_client_id and upstream_client_secret because they act as a full OAuth client to the upstream provider.
• KeycloakAuthProvider reuses OIDCConfiguration from oidc_proxy.py instead of reimplementing OIDC discovery - it's leveraging existing FastMCP infrastructure, not duplicating it.

The fact that the Keycloak auth provider proxies some HTTP requests does not mean it reimplements OAuth flow logic. This is exactly the "minor amount of configuration against one of FastMCP's established auth classes" - it's built on RemoteAuthProvider and adds only the minimal proxying required to bridge Keycloak's native DCR with MCP client expectations.

The Keycloak auth provider does include OIDC discovery because Keycloak supports it natively, and it would be unfortunate to force users to manually configure the authorization, token, and other endpoints individually instead. However, this has been achieved by reusing, not duplicating, existing logic from OIDCConfiguration.

[ksecurity45]

Waiting for this to be merged :)

[coderabbitai]

Walkthrough

Adds a Keycloak OAuth authentication provider with OIDC discovery, Dynamic Client Registration proxying, scope injection, and default JWT verification; includes documentation, example server/client, local Keycloak Docker setup, environment template, and unit/integration tests.

Changes

Cohort / File(s)	Summary
Documentation docs/docs.json, docs/integrations/keycloak.mdx	Added Integrations entry and a full Keycloak integration guide describing DCR setup, FastMCP configuration, testing, troubleshooting, and advanced verifier examples.
Examples — app & env examples/auth/keycloak_auth/server.py, examples/auth/keycloak_auth/client.py, examples/auth/keycloak_auth/.env.example, examples/auth/keycloak_auth/README.md, examples/auth/keycloak_auth/requirements.txt	Added example FastMCP server and client demonstrating KeycloakAuthProvider, env template, README, and Python requirements.
Examples — local Keycloak examples/auth/keycloak_auth/keycloak/docker-compose.yml, examples/auth/keycloak_auth/keycloak/realm-fastmcp.json, examples/auth/keycloak_auth/keycloak/start-keycloak.sh, examples/auth/keycloak_auth/keycloak/README.md	Added Docker Compose, realm configuration, startup script with readiness checks, and Keycloak-specific README for local testing and troubleshooting.
Core implementation src/fastmcp/server/auth/providers/keycloak.py	New KeycloakProviderSettings and KeycloakAuthProvider implementing OIDC discovery, DCR-compatible registration proxy, authorization proxy with scope injection, and default JWT verifier wiring.
Tests tests/server/auth/providers/test_keycloak.py, tests/integration_tests/auth/test_keycloak_provider_integration.py	Added unit and integration tests covering settings parsing, discovery, provider initialization, route behavior, registration/authorization proxy logic, end-to-end flows, error handling, concurrency, and environment loading.

Poem

🐰 I hopped into code where realms awake,
I nudged the scopes for registration's sake,
Keys danced in JWKS moonlight bright,
Clients found home by proxy light,
A rabbit cheered — secure auth takes flight 🥕

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "Add Keycloak OAuth Provider for Enterprise Authentication and local dev" directly and clearly summarizes the main change introduced in the changeset. The title specifically identifies the new feature (Keycloak OAuth Provider), its primary use cases (enterprise authentication and local development), and aligns with the substantial additions to the codebase including the new authentication provider, documentation, examples, and Docker setup. The title is concise, descriptive, and provides sufficient context for a reviewer scanning the project history.
Linked Issues Check	✅ Passed	The code changes comprehensively address all primary objectives from linked issue #1918. The implementation includes a KeycloakAuthProvider class extending RemoteAuthProvider in src/fastmcp/server/auth/providers/keycloak.py that implements automatic OIDC discovery via the _discover_oidc_configuration method, Dynamic Client Registration support with scope injection through the /register proxy endpoint, authorization-server proxy functionality via the /authorize endpoint and /.well-known/oauth-authorization-server metadata endpoint, and JWT token verification with automatic JWKS configuration. The changeset also includes comprehensive documentation, a complete working example with Docker setup (docker-compose.yml, realm-fastmcp.json, start-keycloak.sh), environment configuration examples, server and client implementations, and both integration and unit tests validating the implementation.
Out of Scope Changes Check	✅ Passed	All changes in the pull request are directly aligned with the stated objective of adding Keycloak OAuth support. The modifications include the new Keycloak authentication provider implementation, documentation updates to docs.json and the new keycloak.mdx guide, a complete example directory with server, client, environment configuration, and Docker setup files, comprehensive test coverage for both unit and integration scenarios, and related documentation. No changes appear to be unrelated to the Keycloak OAuth provider feature or introduced outside the scope of the linked issue requirements.
Description Check	✅ Passed	The pull request description follows the required template structure with all necessary sections present and completed. It includes a clear Description section explaining the implementation of native Keycloak OAuth support with enterprise-grade authentication and Docker-based local development setup. The Contributors Checklist is fully completed with all items checked, including closure of issue #1918, adherence to development workflow, manual testing with relevant tests, and documentation updates. The Review Checklist is also fully completed, indicating self-review and readiness for review. The description provides sufficient detail about what was implemented without being verbose.
Docstring Coverage	✅ Passed	Docstring coverage is 95.12% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 11

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e2d317e and edc7407.

📒 Files selected for processing (14)

• docs/docs.json (1 hunks)
• docs/integrations/keycloak.mdx (1 hunks)
• examples/auth/keycloak_auth/.env.example (1 hunks)
• examples/auth/keycloak_auth/README.md (1 hunks)
• examples/auth/keycloak_auth/client.py (1 hunks)
• examples/auth/keycloak_auth/keycloak/README.md (1 hunks)
• examples/auth/keycloak_auth/keycloak/docker-compose.yml (1 hunks)
• examples/auth/keycloak_auth/keycloak/realm-fastmcp.json (1 hunks)
• examples/auth/keycloak_auth/keycloak/start-keycloak.sh (1 hunks)
• examples/auth/keycloak_auth/requirements.txt (1 hunks)
• examples/auth/keycloak_auth/server.py (1 hunks)
• src/fastmcp/server/auth/providers/keycloak.py (1 hunks)
• tests/integration_tests/auth/test_keycloak_provider_integration.py (1 hunks)
• tests/server/auth/providers/test_keycloak.py (1 hunks)

🧰 Additional context used

📓 Path-based instructions (7)

docs/**/*.mdx

📄 CodeRabbit inference engine (docs/.cursor/rules/mintlify.mdc)

docs/**/*.mdx: Use clear, direct language appropriate for technical audiences
Write instructions and procedures in second person ("you")
Use active voice over passive voice
Use present tense for current states and future tense for outcomes
Maintain consistent terminology across the documentation
Keep sentences concise while preserving necessary context
Use parallel structure in lists, headings, and procedures
Lead with the most important information (inverted pyramid)
Use progressive disclosure: basic concepts before advanced ones
Break complex procedures into numbered steps
Include prerequisites and context before instructions
Provide expected outcomes for each major step
End sections with next steps or related information
Use descriptive, keyword-rich headings for navigation and SEO
Focus on user goals and outcomes rather than system features
Anticipate common questions and address them proactively
Include troubleshooting for likely failure points
Offer multiple pathways when appropriate (beginner vs advanced) and provide an opinionated recommended path
Use for supplementary information that supports the main content
Use for expert advice, shortcuts, or best practices
Use for critical cautions, breaking changes, or destructive actions
Use for neutral background or contextual information
Use to confirm success or completion
Provide single code examples using fenced code blocks with language (and filename when relevant)
Use to present the same concept in multiple languages
For API docs, use to show requests
For API docs, use to show responses
Use and to document procedures and sequential instructions
Use and for platform-specific or alternative approaches
Use / for supplementary content that might interrupt flow
In API docs, use for parameters (path, body, query, header) with type and required/default as appropria...

Files:

• docs/integrations/keycloak.mdx

docs/**/*.{md,mdx}

📄 CodeRabbit inference engine (AGENTS.md)

docs/**/*.{md,mdx}: Documentation code examples should be explained before the code and be fully runnable, including imports
Use clear headers with logical H2/H3 hierarchy to form navigation
Write user-focused content that motivates the why before the how
Prefer prose for important information over code comments in docs

Files:

• docs/integrations/keycloak.mdx

**/*.{md,mdx}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{md,mdx}: Be brief and to the point in written materials; avoid regurgitating obvious code details
Avoid defensive constructions like "This isn't X" or "Not just X, but Y"; state what it is directly

Files:

• docs/integrations/keycloak.mdx
• examples/auth/keycloak_auth/keycloak/README.md
• examples/auth/keycloak_auth/README.md

{docs.json,docs/docs.json}

📄 CodeRabbit inference engine (AGENTS.md)

Documentation pages must be listed in docs.json to be included

Files:

• docs/docs.json

**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

Never use bare except; always catch specific exception types

Files:

• examples/auth/keycloak_auth/client.py
• tests/integration_tests/auth/test_keycloak_provider_integration.py
• tests/server/auth/providers/test_keycloak.py
• examples/auth/keycloak_auth/server.py
• src/fastmcp/server/auth/providers/keycloak.py

tests/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

tests/**/*.py: Tests must be atomic, self-contained, and cover a single functionality
Use pytest parameterization for multiple examples of the same functionality
Use separate tests for distinct pieces of functionality
Always put imports at the top of test files; do not import inside test bodies
Do not add @pytest.mark.asyncio; asyncio_mode = "auto" is set globally
Prefer in-memory transport for tests; use HTTP transport only when explicitly testing networking
For slow/long-running tests, mark them as integration or optimize (default timeout is 5s)
In tests, use # type: ignore[attr-defined] for MCP results instead of type assertions

Files:

• tests/integration_tests/auth/test_keycloak_provider_integration.py
• tests/server/auth/providers/test_keycloak.py

src/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

Use Python ≥ 3.10 and provide full type annotations for library code

Files:

• src/fastmcp/server/auth/providers/keycloak.py

🧬 Code graph analysis (4)

tests/integration_tests/auth/test_keycloak_provider_integration.py (2)

src/fastmcp/server/server.py (2)

• FastMCP (148-2693)
• http_app (2136-2183)

src/fastmcp/server/auth/providers/keycloak.py (1)

• KeycloakAuthProvider (46-396)

tests/server/auth/providers/test_keycloak.py (3)

src/fastmcp/server/server.py (1)

• http_app (2136-2183)

src/fastmcp/server/auth/oidc_proxy.py (1)

• OIDCConfiguration (27-169)

src/fastmcp/server/auth/providers/jwt.py (1)

• JWTVerifier (165-498)

examples/auth/keycloak_auth/server.py (3)

src/fastmcp/server/auth/providers/keycloak.py (1)

• KeycloakAuthProvider (46-396)

src/fastmcp/server/dependencies.py (1)

• get_access_token (104-135)

src/fastmcp/utilities/logging.py (1)

• configure_logging (29-95)

src/fastmcp/server/auth/providers/keycloak.py (5)

src/fastmcp/server/auth/auth.py (2)

• RemoteAuthProvider (192-262)
• TokenVerifier (166-189)

src/fastmcp/server/auth/oidc_proxy.py (1)

• OIDCConfiguration (27-169)

src/fastmcp/server/auth/providers/jwt.py (1)

• JWTVerifier (165-498)

src/fastmcp/utilities/auth.py (1)

• parse_scopes (9-34)

src/fastmcp/utilities/logging.py (1)

• get_logger (14-26)

🪛 dotenv-linter (4.0.0)

examples/auth/keycloak_auth/.env.example

[warning] 3-3: [UnorderedKey] The FASTMCP_SERVER_AUTH_KEYCLOAK_BASE_URL key should go before the FASTMCP_SERVER_AUTH_KEYCLOAK_REALM_URL key

(UnorderedKey)

---

[warning] 6-6: [EndingBlankLine] No blank line at the end of the file

(EndingBlankLine)

🪛 markdownlint-cli2 (0.18.1)

examples/auth/keycloak_auth/keycloak/README.md

28-28: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

32-32: Trailing spaces
Expected: 0 or 2; Actual: 1

(MD009, no-trailing-spaces)

---

129-129: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)

examples/auth/keycloak_auth/README.md

20-20: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

---

24-24: Trailing spaces
Expected: 0 or 2; Actual: 1

(MD009, no-trailing-spaces)

---

26-26: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Run tests with lowest-direct dependencies
• GitHub Check: Run tests: Python 3.10 on windows-latest

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Fix the Docker Compose reference.

The link text/path points to examples/auth/keycloak_auth/docker-compose.yml, but the compose file actually lives under examples/auth/keycloak_auth/keycloak/docker-compose.yml. Following the current link gives a 404. Please update both the label (docker-compose.yml) and the href to include the keycloak/ subdirectory.

-If you prefer using Docker Compose instead, you may want to have a look at the [`docker-compose.yaml`](https://github.com/jlowin/fastmcp/blob/main/examples/auth/keycloak_auth/docker-compose.yml) file included in the Keycloak auth example.
+If you prefer using Docker Compose instead, review [`docker-compose.yml`](https://github.com/jlowin/fastmcp/blob/main/examples/auth/keycloak_auth/keycloak/docker-compose.yml) included with the Keycloak auth example.

Committable suggestion skipped: line range outside the PR's diff.

🤖 Prompt for AI Agents

In examples/auth/keycloak_auth/keycloak/README.md around lines 38 to 40, the
Docker Compose link text and href wrongly point to
examples/auth/keycloak_auth/docker-compose.yml; update the link label to
"keycloak/docker-compose.yml" (or include the subdirectory in the label) and
change the href to examples/auth/keycloak_auth/keycloak/docker-compose.yml so
the link points to the actual file location.

[stephaneberle9]

Fixed as suggested as per eb73267

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check the current content of the README to verify the Docker Compose link fix
cat examples/auth/keycloak_auth/keycloak/README.md | grep -A 2 -B 2 "docker-compose"

Length of output: 81

---

🏁 Script executed:

#!/bin/bash
# Check the specific commit mentioned by the user
git show eb732675686c59d86c97ab3d362dd7f3e28eecc3 --stat

Length of output: 1654

---

🏁 Script executed:

#!/bin/bash
# Show the actual changes in that commit for the README file
git show eb732675686c59d86c97ab3d362dd7f3e28eecc3 -- examples/auth/keycloak_auth/keycloak/README.md | head -50

Length of output: 1873

---

@stephaneberle9 Thank you for the quick fix! I can confirm the commit addresses the path issues in the keycloak/README.md file. The troubleshooting section paths have been corrected to reference files relative to the keycloak directory (e.g., realm-fastmcp.json instead of keycloak/realm-fastmcp.json), which makes sense since users would be running commands from within that directory. The changes look good! ✅

[coderabbitai]

Actionable comments posted: 3

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between edc7407 and eb73267.

⛔ Files ignored due to path filters (1)

• tests/integration_tests/auth/test_keycloak_provider_integration.py is excluded by none and included by none

📒 Files selected for processing (6)

• examples/auth/keycloak_auth/README.md (1 hunks)
• examples/auth/keycloak_auth/client.py (1 hunks)
• examples/auth/keycloak_auth/keycloak/README.md (1 hunks)
• examples/auth/keycloak_auth/requirements.txt (1 hunks)
• examples/auth/keycloak_auth/server.py (1 hunks)
• src/fastmcp/server/auth/providers/keycloak.py (1 hunks)

🧰 Additional context used

📓 Path-based instructions (3)

**/*.{md,mdx}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{md,mdx}: Be brief and to the point in written materials; avoid regurgitating obvious code details
Avoid defensive constructions like "This isn't X" or "Not just X, but Y"; state what it is directly

Files:

• examples/auth/keycloak_auth/keycloak/README.md
• examples/auth/keycloak_auth/README.md

**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

Never use bare except; always catch specific exception types

Files:

• examples/auth/keycloak_auth/server.py
• examples/auth/keycloak_auth/client.py
• src/fastmcp/server/auth/providers/keycloak.py

src/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

Use Python ≥ 3.10 and provide full type annotations for library code

Files:

• src/fastmcp/server/auth/providers/keycloak.py

🧠 Learnings (10)

📚 Learning: 2025-10-27T14:38:52.614Z

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: docs/.cursor/rules/mintlify.mdc:0-0
Timestamp: 2025-10-27T14:38:52.614Z
Learning: Applies to docs/**/*.mdx : Confirm proper heading hierarchy with H2 for main sections, H3 for subsections

Applied to files:

• examples/auth/keycloak_auth/README.md

📚 Learning: 2025-10-27T14:38:52.613Z

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: docs/.cursor/rules/mintlify.mdc:0-0
Timestamp: 2025-10-27T14:38:52.613Z
Learning: Applies to docs/**/*.mdx : Use <Warning> for critical cautions, breaking changes, or destructive actions

Applied to files:

• examples/auth/keycloak_auth/README.md

📚 Learning: 2025-10-27T14:38:52.614Z

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: docs/.cursor/rules/mintlify.mdc:0-0
Timestamp: 2025-10-27T14:38:52.614Z
Learning: Applies to docs/**/*.mdx : Add appropriate <Warning> callouts for destructive or security-sensitive actions

Applied to files:

• examples/auth/keycloak_auth/README.md

📚 Learning: 2025-10-27T14:38:52.614Z

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: docs/.cursor/rules/mintlify.mdc:0-0
Timestamp: 2025-10-27T14:38:52.614Z
Learning: Applies to docs/**/*.mdx : Ensure proper heading hierarchy starting with H2 for main sections and H3 for subsections

Applied to files:

• examples/auth/keycloak_auth/README.md

📚 Learning: 2025-10-27T14:38:52.614Z

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: docs/.cursor/rules/mintlify.mdc:0-0
Timestamp: 2025-10-27T14:38:52.614Z
Learning: Applies to docs/**/*.mdx : Check for consistency in terminology, formatting, and component usage

Applied to files:

• examples/auth/keycloak_auth/README.md

📚 Learning: 2025-10-27T14:38:52.614Z

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: docs/.cursor/rules/mintlify.mdc:0-0
Timestamp: 2025-10-27T14:38:52.614Z
Learning: Applies to docs/**/*.mdx : Use <Tabs> for platform-specific content or alternative approaches

Applied to files:

• examples/auth/keycloak_auth/README.md

📚 Learning: 2025-10-27T14:40:00.422Z

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-10-27T14:40:00.422Z
Learning: Applies to docs/**/*.{md,mdx} : Use clear headers with logical H2/H3 hierarchy to form navigation

Applied to files:

• examples/auth/keycloak_auth/README.md

📚 Learning: 2025-10-27T14:38:52.614Z

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: docs/.cursor/rules/mintlify.mdc:0-0
Timestamp: 2025-10-27T14:38:52.614Z
Learning: Applies to docs/**/*.mdx : Include verification/testing steps with expected outcomes

Applied to files:

• examples/auth/keycloak_auth/README.md

📚 Learning: 2025-10-27T14:38:52.614Z

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: docs/.cursor/rules/mintlify.mdc:0-0
Timestamp: 2025-10-27T14:38:52.614Z
Learning: Applies to docs/**/*.mdx : Explain prerequisites clearly before instructions

Applied to files:

• examples/auth/keycloak_auth/README.md

📚 Learning: 2025-10-27T14:38:52.613Z

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: docs/.cursor/rules/mintlify.mdc:0-0
Timestamp: 2025-10-27T14:38:52.613Z
Learning: Applies to docs/**/*.mdx : Use parallel structure in lists, headings, and procedures

Applied to files:

• examples/auth/keycloak_auth/README.md

🧬 Code graph analysis (3)

examples/auth/keycloak_auth/server.py (3)

src/fastmcp/server/auth/providers/keycloak.py (1)

• KeycloakAuthProvider (46-407)

src/fastmcp/server/dependencies.py (1)

• get_access_token (104-135)

src/fastmcp/utilities/logging.py (1)

• configure_logging (29-95)

examples/auth/keycloak_auth/client.py (1)

src/fastmcp/client/client.py (1)

• Client (97-941)

src/fastmcp/server/auth/providers/keycloak.py (5)

src/fastmcp/server/auth/auth.py (2)

• RemoteAuthProvider (192-262)
• TokenVerifier (166-189)

src/fastmcp/server/auth/oidc_proxy.py (1)

• OIDCConfiguration (27-169)

src/fastmcp/server/auth/providers/jwt.py (1)

• JWTVerifier (165-498)

src/fastmcp/utilities/auth.py (1)

• parse_scopes (9-34)

src/fastmcp/utilities/logging.py (1)

• get_logger (14-26)

🪛 markdownlint-cli2 (0.18.1)

examples/auth/keycloak_auth/keycloak/README.md

28-28: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

32-32: Trailing spaces
Expected: 0 or 2; Actual: 1

(MD009, no-trailing-spaces)

---

129-129: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Run tests: Python 3.10 on windows-latest
• GitHub Check: Run tests with lowest-direct dependencies

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between eb73267 and 6f5622c.

📒 Files selected for processing (3)

• examples/auth/keycloak_auth/keycloak/README.md (1 hunks)
• examples/auth/keycloak_auth/server.py (1 hunks)
• src/fastmcp/server/auth/providers/keycloak.py (1 hunks)

🧰 Additional context used

📓 Path-based instructions (3)

**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

Never use bare except; always catch specific exception types

Files:

• examples/auth/keycloak_auth/server.py
• src/fastmcp/server/auth/providers/keycloak.py

**/*.{md,mdx}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{md,mdx}: Be brief and to the point in written materials; avoid regurgitating obvious code details
Avoid defensive constructions like "This isn't X" or "Not just X, but Y"; state what it is directly

Files:

• examples/auth/keycloak_auth/keycloak/README.md

src/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

Use Python ≥ 3.10 and provide full type annotations for library code

Files:

• src/fastmcp/server/auth/providers/keycloak.py

🧬 Code graph analysis (2)

examples/auth/keycloak_auth/server.py (3)

src/fastmcp/server/auth/providers/keycloak.py (1)

• KeycloakAuthProvider (46-415)

src/fastmcp/server/dependencies.py (1)

• get_access_token (104-135)

src/fastmcp/utilities/logging.py (1)

• configure_logging (29-95)

src/fastmcp/server/auth/providers/keycloak.py (5)

src/fastmcp/server/auth/auth.py (2)

• RemoteAuthProvider (192-262)
• TokenVerifier (166-189)

src/fastmcp/server/auth/oidc_proxy.py (1)

• OIDCConfiguration (27-169)

src/fastmcp/server/auth/providers/jwt.py (1)

• JWTVerifier (165-498)

src/fastmcp/utilities/auth.py (1)

• parse_scopes (9-34)

src/fastmcp/utilities/logging.py (1)

• get_logger (14-26)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Run tests with lowest-direct dependencies
• GitHub Check: Run tests: Python 3.10 on windows-latest

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

Fix the invalid AnyHttpUrl call
AnyHttpUrl is a type alias (typing.Annotated) in Pydantic v2, so calling AnyHttpUrl(base_url) raises TypeError: 'typing.Annotated' object is not callable. As soon as KeycloakAuthProvider is instantiated the app will crash, so no request ever succeeds. Pass the already validated realm/base URL as a plain string (or via a TypeAdapter) instead.

-        super().__init__(
-            token_verifier=token_verifier,
-            authorization_servers=[AnyHttpUrl(base_url)],
-            base_url=base_url,
-        )
+        super().__init__(
+            token_verifier=token_verifier,
+            authorization_servers=[str(settings.realm_url)],
+            base_url=base_url,
+        )

Committable suggestion skipped: line range outside the PR's diff.

🤖 Prompt for AI Agents

In src/fastmcp/server/auth/providers/keycloak.py around lines 152 to 156, the
code mistakenly calls AnyHttpUrl(base_url) (Pydantic v2 AnyHttpUrl is a
typing.Annotated and not callable) which raises a TypeError at instantiation;
fix by passing the already-validated realm/base_url as a plain string into
authorization_servers (or, if you need runtime validation, run the value through
a Pydantic TypeAdapter for AnyHttpUrl and pass the adapter-validated string),
ensuring authorization_servers receives a string URL rather than calling
AnyHttpUrl.

[stephaneberle9]

The claim that AnyHttpUrl(base_url) is invalid is incorrect.

Evidence

1. Direct testing confirms it works:

   from pydantic import AnyHttpUrl, TypeAdapter
   import sys
   
   print(f"Python version: {sys.version}")
   print(f"AnyHttpUrl type: {type(AnyHttpUrl)}")
   print(f"AnyHttpUrl: {AnyHttpUrl}")
   
   # Direct instantiation
   url1 = AnyHttpUrl("https://example.com")
   print(f"SUCCESS: Direct instantiation works: {url1}")
   
   # Output:
   # Python version: 3.12.10 (tags/v3.12.10:0cc8128, Apr  8 2025, 12:21:36) [MSC v.1943 64 bit (AMD64)]
   # AnyHttpUrl type: <class 'type'>
   # AnyHttpUrl: <class 'pydantic.networks.AnyHttpUrl'>
   # SUCCESS: Direct instantiation works: https://example.com/

2. The parent class RemoteAuthProvider constructor explicitly expects this pattern:

   def __init__(
       self,
       token_verifier: TokenVerifier,
       authorization_servers: list[AnyHttpUrl],  # ← expects AnyHttpUrl instances
       base_url: AnyHttpUrl | str,
       ...
   ):
   

3. This pattern is used throughout the FastMCP codebase without issues:

   • supabase.py:124: authorization_servers=[AnyHttpUrl(f"{self.project_url}/auth/v1")]
   • workos.py:379: authorization_servers=[AnyHttpUrl(self.authkit_domain)]
   • scalekit.py:129: AnyHttpUrl(f"{self.environment_url}/resources/{self.resource_id}")
   • descope.py:121: AnyHttpUrl(f"{self.descope_base_url}/v1/apps/{self.project_id}")

4. If this were truly invalid, most tests would fail. The test suite extensively uses AnyHttpUrl() instantiation:

   • All tests in test_remote_auth_provider.py
   • All tests in test_oidc_proxy.py
   • All tests in test_oauth_mounting.py
   • And many more...

Conclusion: The code is correct as-is. AnyHttpUrl is fully instantiable in Pydantic v2.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check RemoteAuthProvider's __init__ signature
echo "=== RemoteAuthProvider signature ==="
ast-grep --pattern $'class RemoteAuthProvider {
  $$$
  def __init__($$$) {
    $$$
  }
  $$$
}'

# Check the type annotations in RemoteAuthProvider
rg -n "class RemoteAuthProvider" -A 30 --type=py

# Check AnyHttpUrl usage in other provider files mentioned
echo -e "\n=== Supabase provider AnyHttpUrl usage ==="
rg -n "AnyHttpUrl" src/fastmcp/server/auth/providers/supabase.py -C 2

echo -e "\n=== WorkOS provider AnyHttpUrl usage ==="
rg -n "AnyHttpUrl" src/fastmcp/server/auth/providers/workos.py -C 2

echo -e "\n=== Scalekit provider AnyHttpUrl usage ==="
rg -n "AnyHttpUrl" src/fastmcp/server/auth/providers/scalekit.py -C 2

echo -e "\n=== Descope provider AnyHttpUrl usage ==="
rg -n "AnyHttpUrl" src/fastmcp/server/auth/providers/descope.py -C 2

Length of output: 6631

---

🏁 Script executed:

#!/bin/bash
# Check where AnyHttpUrl is imported from and its definition
echo "=== AnyHttpUrl imports in codebase ==="
rg -n "from pydantic.*import.*AnyHttpUrl" --type=py | head -20

# Check Pydantic version in requirements
echo -e "\n=== Pydantic version ==="
rg "pydantic" pyproject.toml setup.py requirements.txt 2>/dev/null || echo "No explicit pydantic version found in common files"

# Check if there's a networks module or AnyHttpUrl definition
echo -e "\n=== Pydantic networks module usage ==="
rg "from pydantic.networks import" --type=py | head -10

Length of output: 2537

---

🏁 Script executed:

#!/bin/bash
# Check tests that use AnyHttpUrl instantiation
echo "=== Tests using AnyHttpUrl() instantiation ==="
rg -n "AnyHttpUrl\(" tests/ --type=py -C 1 | head -50

Length of output: 3783

---

@stephaneberle9 You're absolutely right, and I apologize for the incorrect comment. Thank you for the detailed evidence.

After reviewing the codebase, I can confirm:

1. RemoteAuthProvider signature explicitly expects list[AnyHttpUrl]:

   def __init__(
       self,
       token_verifier: TokenVerifier,
       authorization_servers: list[AnyHttpUrl],  # ← expects AnyHttpUrl instances
       base_url: AnyHttpUrl | str,
       ...
   ):

2. The pattern is used consistently across all provider implementations:

   • supabase.py:124: authorization_servers=[AnyHttpUrl(f"{self.project_url}/auth/v1")]
   • workos.py:379: authorization_servers=[AnyHttpUrl(self.authkit_domain)]
   • scalekit.py:129: AnyHttpUrl(f"{self.environment_url}/resources/{self.resource_id}")
   • descope.py:121: AnyHttpUrl(f"{self.descope_base_url}/v1/apps/{self.project_id}")

3. Tests extensively use this pattern without issues:

   • test_oauth_mounting.py
   • test_remote_auth_provider.py
   • test_oidc_proxy.py
   • test_auth_integration.py

While AnyHttpUrl is indeed a type alias in Pydantic v2, it's callable and the codebase (using Pydantic >=2.11.7) relies on this behavior throughout. Your implementation at line 152-156 is correct and follows the established pattern.

My original comment was wrong. The code is fine as-is. 🙏

[ksecurity45]

Waiting for this to be merged :)