Add Agent Authentication and MCP Auth Quickstart Guides for Python #5755
Conversation
WalkthroughAdds two new Python quick-start landing pages and their detailed guide partials, and updates mkdocs navigation to expose them. All changes are documentation-only; no executable code or public API changes. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Organization UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🧰 Additional context used🪛 LanguageToolen/includes/quick-starts/agent-auth-py.md[style] ~714-~714: Using many exclamation marks might seem excessive (in this case: 19 exclamation marks for a text that’s 7309 characters long) (EN_EXCESSIVE_EXCLAMATION) 🔇 Additional comments (4)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
en/includes/quick-starts/mcp-auth-server-py.md (1)
308-313: Clarify SSL verification setting for development vs. production.Line 312 sets
ssl_verify=True(production) but the inline comment suggests setting it toFalsefor development. This could confuse users testing locally with self-signed certificates, as JWKS fetches will fail without explicit guidance.Consider either:
- Documenting that development users should set
ssl_verify=Falsewhen testing locally, or- Making this configurable via an environment variable:
ssl_verify = os.getenv("SSL_VERIFY", "True").lower() == "true"This would allow users to easily toggle for their environment without modifying code.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
en/asgardeo/docs/quick-starts/agent-auth-py.md(1 hunks)en/asgardeo/docs/quick-starts/mcp-auth-server-py.md(1 hunks)en/asgardeo/mkdocs.yml(1 hunks)en/includes/quick-starts/agent-auth-py.md(1 hunks)en/includes/quick-starts/mcp-auth-server-py.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
en/includes/quick-starts/mcp-auth-server-py.md
[style] ~418-~418: Using many exclamation marks might seem excessive (in this case: 16 exclamation marks for a text that’s 4991 characters long)
Context: ...propriate WWW-Authenticate header. !!! Important With CORS enabled, browse...
(EN_EXCESSIVE_EXCLAMATION)
en/includes/quick-starts/agent-auth-py.md
[style] ~467-~467: Using many exclamation marks might seem excessive (in this case: 16 exclamation marks for a text that’s 6356 characters long)
Context: ...our browser and log in as a test user. !!! Info You need to create a test user...
(EN_EXCESSIVE_EXCLAMATION)
🔇 Additional comments (8)
en/includes/quick-starts/agent-auth-py.md (3)
103-104: Clarify the.envfile location handling between flows.The agent-credential flow loads
.envwithout a path (line 104), but the OBO flow usesPath(__file__).resolve().parents[2](line 356). If both code examples are meant to run from the project root, this path calculation appears incorrect—parents[2]would traverse two parent directories from the script location. Clarify the expected file structure or use consistent.envloading:- ROOT_DIR = Path(__file__).resolve().parents[2] - load_dotenv(ROOT_DIR / ".env") + load_dotenv() # Looks for .env in current working directoryAlternatively, if the script is nested deeper than the project root, document the expected directory structure clearly.
Also applies to: 356-357
262-323: Well-implemented OAuth callback handler with proper error resilience.The
OAuthCallbackServerimplementation correctly handles multiple scenarios: OAuth errors (line 279), successful authorization (line 287), invalid redirects (line 296), and timeout logic (lines 318–323). Async/await patterns and threading are used appropriately.
338-437: Ensure LangChain version pinning for create_agent compatibility.The code imports
create_agentfromlangchain.agentsand usesagent.ainvoke(). These APIs are available in LangChain v1.0+ (released October 2025), but the pip install command must pin to v1.0 or later. Without explicit version constraints, users with older LangChain installations will encounter import errors. Verify that the pip install command specifieslangchain>=1.0and ensurelangchain-google-genaiis compatible with the pinned version.en/includes/quick-starts/mcp-auth-server-py.md (2)
156-179: JWT validator JWKS fetching and caching is well-implemented.The
JWTValidatorclass properly handles JWKS retrieval (async fetch), caching for performance (line 181–185), and comprehensive JWT validation with explicit options (line 230–237). Error handling covers all major JWT failure modes (ExpiredSignatureError, InvalidAudienceError, InvalidIssuerError, InvalidSignatureError).
347-365: Defensive environment variable validation is a good practice.Line 352 validates that required environment variables are present before proceeding, raising a clear error if any are missing. This prevents runtime failures later.
en/asgardeo/mkdocs.yml (1)
231-236: Navigation structure additions are consistent and well-placed.The navigation updates correctly add:
- Python quick-start under the existing "Secure MCP Servers" section (line 233)
- A new "Secure Your AI Agents" subsection with Python agent authentication (lines 235–236)
This aligns with the existing navigation structure and logically groups related content. Ensure that the referenced files
quick-starts/mcp-auth-server-py.mdandquick-starts/agent-auth-py.mdexist and are correctly placed.en/asgardeo/docs/quick-starts/agent-auth-py.md (1)
1-25: Quick-start wrapper page includes helpful cross-reference to MCP server guide.The page structure is complete and well-organized. The prerequisites section (lines 13–20) thoughtfully includes a link to the MCP Auth Server quickstart as an alternative, which helps users understand the full workflow and provides escape hatches if they already have a secured MCP server.
Note: The referenced include file (
../../../includes/quick-starts/agent-auth-py.md), template rendering, and GitHub repository link could not be verified in this environment due to repository access limitations.en/asgardeo/docs/quick-starts/mcp-auth-server-py.md (1)
1-23: Quick-start wrapper page is properly structured with complete metadata.The page correctly uses the quick-start template system with all required metadata fields: learning objectives (lines 7–11), prerequisites (lines 12–18), and source code reference (line 19). The include directive (line 23) properly references the corresponding content partial. The GitHub repository link is publicly accessible and correctly points to the MCP Auth Python sample.
The referenced template file
templates/quick-start.htmland include file../../../includes/quick-starts/mcp-auth-server-py.mdshould be verified to exist in the repository and that the include file contains content.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
en/includes/quick-starts/agent-auth-py.md (1)
254-327: Potential HTTP handler logging bypass in oauth_callback.py.The
_Handlerclass in the OAuthCallbackServer logs HTTP requests and responses (implicitly through inheritedSimpleHTTPRequestHandler). While the implementation handles the OAuth flow correctly, consider that FastMCP requires Python 3.10+ for the package itself. However, the documentation doesn't explicitly state a Python version requirement at the beginning of the guide, which could cause confusion for users on older Python versions.Recommend adding a Python version prerequisite section at the start of the guide.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
en/includes/quick-starts/agent-auth-py.md(1 hunks)en/includes/quick-starts/mcp-auth-server-py.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
en/includes/quick-starts/mcp-auth-server-py.md
[style] ~422-~422: Using many exclamation marks might seem excessive (in this case: 19 exclamation marks for a text that’s 5229 characters long)
Context: ...propriate WWW-Authenticate header. !!! Important With CORS enabled, browse...
(EN_EXCESSIVE_EXCLAMATION)
en/includes/quick-starts/agent-auth-py.md
[style] ~469-~469: Using many exclamation marks might seem excessive (in this case: 16 exclamation marks for a text that’s 6617 characters long)
Context: ...our browser and log in as a test user. !!! Info You need to create a test user...
(EN_EXCESSIVE_EXCLAMATION)
🔇 Additional comments (4)
en/includes/quick-starts/agent-auth-py.md (2)
340-439: OBO flow implementation looks solid but verify token lifecycle.The OBO flow correctly implements PKCE and token exchange (lines 375-401). Ensure that
auth_managercontext remains active during the MCP client connection phase (lines 404-415). The current code structure appears correct since the context manager is maintained during the MCP client creation and invocation.
88-162: The agent token itself remains accessible outside the context manager—variable scope in Python persists beyond theasync withblock. Theagent_tokenreturned byget_agent_token()is a data object designed for use by callers after the context exits, not a resource bound to the manager's lifetime.However, if token refresh or lifecycle management is required during agent invocation, the context manager should remain active. Verify whether the auth_manager needs to stay open for the full agent execution; if so, move the MCP client and agent invocation inside the context.
en/includes/quick-starts/mcp-auth-server-py.md (2)
139-276: JWT validator implementation is solid; minor security consideration for SSL verification.The
JWTValidatorclass correctly fetches and caches JWKS, validates tokens with proper error handling (lines 247-259). Line 314 setsssl_verify=Truein production context, which is correct. However, the comment on line 163 mentions development usage where SSL might be disabled—ensure this is only for local testing and never deployed to production.The implementation properly uses RSAAlgorithm.from_jwk() to parse JWK keys, which is the correct approach for PyJWT.
317-317: Type hint usesOptionalfor backward compatibility—good choice.Line 317 correctly uses
Optional[AccessToken]fromtypingmodule (imported at line 290) instead of the Python 3.10+ union syntax (AccessToken | None), ensuring compatibility with Python 3.9 and earlier. This aligns with the past review comment's recommendation.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
en/includes/quick-starts/mcp-auth-server-py.md (1)
1-61: Add Python version prerequisite to the introduction (duplicate of prior review).This issue was previously flagged but remains unresolved. FastMCP requires Python 3.10 or later, but the guide lacks a prominent "Prerequisites" section before the setup instructions. Users on Python 3.9 or earlier will encounter errors during
pip installor runtime (e.g., unsupported syntax in FastMCP dependencies).Add a "Prerequisites" section immediately after the introduction (after line 12) that explicitly states: "Requires Python 3.10 or later" and lists minimal tool requirements (Python, pip, Node.js/npm for MCP Inspector).
What are the officially documented Python version requirements for the FastMCP framework?
🧹 Nitpick comments (1)
en/includes/quick-starts/mcp-auth-server-py.md (1)
306-315: Clarify SSL verification comment to discourage disabling in production.Line 314 includes the comment "Set to False for development if needed", which could mislead developers to disable SSL verification in production. While the code correctly defaults to
ssl_verify=True, the comment should be more cautious.Suggest refining the comment to:
ssl_verify=True # Always verify SSL in production; only disable for local dev with self-signed certsThis makes the production safety requirement explicit and discourages casual misuse.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
en/asgardeo/docs/quick-starts/agent-auth-py.md(1 hunks)en/asgardeo/docs/quick-starts/mcp-auth-server-py.md(1 hunks)en/includes/quick-starts/mcp-auth-server-py.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- en/asgardeo/docs/quick-starts/agent-auth-py.md
- en/asgardeo/docs/quick-starts/mcp-auth-server-py.md
🧰 Additional context used
🪛 LanguageTool
en/includes/quick-starts/mcp-auth-server-py.md
[style] ~422-~422: Using many exclamation marks might seem excessive (in this case: 19 exclamation marks for a text that’s 5230 characters long)
Context: ...propriate WWW-Authenticate header. !!! Important With CORS enabled, browse...
(EN_EXCESSIVE_EXCLAMATION)
🔇 Additional comments (3)
en/includes/quick-starts/mcp-auth-server-py.md (3)
317-348: Union syntax fix from prior review is correctly applied.The previous critical issue flagging the Python 3.10+ union syntax (
AccessToken | Noneat line 315) has been appropriately resolved. Line 317 now correctly usesOptional[AccessToken]with the proper import at line 290. This maintains compatibility with Python 3.9+.Exception handling, token payload extraction, and AccessToken construction are all solid.
65-86: Approve initial MCP server example.The simple MCP server without authentication is well-structured and serves as a good foundation before adding authentication. The async
addtool and FastMCP setup are correct, and the streamable-http transport is appropriate for testing with MCP Inspector.
132-278: JWT validator implementation is production-ready.The
JWTValidatorclass is well-implemented with:
- Async JWKS fetching with error handling
- Efficient JWKS caching to reduce network calls
- Proper RSA key extraction and token validation
- Specific exception handling for JWT errors
- Comprehensive logging for debugging
This is a solid foundation for MCP server authentication.
Pratheesha97
changed the title
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
en/includes/quick-starts/mcp-auth-server-py.md (1)
132-278: JWT validator implementation is well-structured; consider documenting JWKS cache behavior.The
JWTValidatorclass (lines 149–275) demonstrates solid JWT validation practices: proper JWKS fetching, caching, signature verification, and comprehensive error handling. However, the cache (line 169,_jwks_cache) has no TTL or refresh mechanism, so it will use stale keys if the authorization server rotates them. This is typically acceptable for short-lived processes, but it's worth a brief comment in the code or docs noting when manual cache refresh might be needed.Consider adding an optional TTL parameter to the
__init__method and a cache invalidation mechanism if long-running servers are expected to handle key rotations. For now, a docstring note suffices:class JWTValidator: """ A class to handle JWT token validation using JWKS. Fetches and caches JWKS keys for performance. Note: JWKS is cached in memory indefinitely. For long-running servers, consider implementing cache invalidation on key rotation errors. """en/includes/quick-starts/agent-auth-py.md (1)
353-443: OBO flow design with oauth_callback.py is robust; verify timeout handling.The OAuth callback server (lines 379–441) is well-implemented:
- Threaded HTTP server to capture redirect (lines 420–427)
- Proper handling of error, success, and invalid callback cases (lines 395–418)
- Async polling with configurable timeout (lines 433–440, default 120 seconds)
- Graceful shutdown (line 429–431)
The timeout logic (lines 435–438) polls every 0.1 seconds, which is appropriate. One minor note: if the timeout expires,
wait_for_code()returns(None, None, None), and the calling code checksif auth_code is None(lines 511, 613) to catch both timeout and user-cancellation scenarios—this is fine but consider whether a more explicit timeout error message would improve UX.For better diagnostics, consider returning a tuple with an explicit timeout flag:
async def wait_for_code(self): """Returns (auth_code, state, error, is_timeout).""" elapsed = 0 while self.auth_code is None and self._error is None and elapsed < self.timeout: await asyncio.sleep(0.1) elapsed += 0.1 is_timeout = elapsed >= self.timeout and self.auth_code is None and self._error is None return (self.auth_code, self.state, self._error, is_timeout)Then update the calling code to handle timeouts explicitly:
auth_code, returned_state, error, is_timeout = await callback.wait_for_code() if is_timeout: print("Authorization timed out. Please try again.") return elif error: print(f"Authorization failed: {error}") return
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
en/includes/quick-starts/agent-auth-py.md(1 hunks)en/includes/quick-starts/mcp-auth-server-py.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
en/includes/quick-starts/mcp-auth-server-py.md
[style] ~422-~422: Using many exclamation marks might seem excessive (in this case: 19 exclamation marks for a text that’s 5230 characters long)
Context: ...propriate WWW-Authenticate header. !!! Important With CORS enabled, browse...
(EN_EXCESSIVE_EXCLAMATION)
en/includes/quick-starts/agent-auth-py.md
[style] ~703-~703: Using many exclamation marks might seem excessive (in this case: 16 exclamation marks for a text that’s 7011 characters long)
Context: ...our browser and log in as a test user. !!! Info You need to create a test user...
(EN_EXCESSIVE_EXCLAMATION)
🔇 Additional comments (8)
en/includes/quick-starts/mcp-auth-server-py.md (2)
1-62: Verify Python version prerequisite is clearly documented.The setup section (lines 33–62) does not explicitly state a Python version requirement before the pip install step. The code uses modern syntax (
dict[str, float]on line 74, 373), which requires Python 3.9+, and FastMCP requires Python 3.10+. Ensure the prerequisites section is visible early in the guide so users with Python 3.8 or earlier fail fast rather than during installation.Check that a clear "Prerequisites: Python 3.10 or later required" statement appears before line 33 (before "Create a Simple MCP server"). If not already added, a prominent prerequisites section should be inserted near the top of the guide.
286-384: FastMCP authentication integration is clear and correct.The authenticated
main.py(lines 286–384) properly:
- Loads environment variables and validates required fields (lines 351–357)
- Implements the
TokenVerifierprotocol viaJWTTokenVerifier(lines 306–348)- Logs validated claims with production-aware warnings (lines 330–335)
- Integrates auth settings into FastMCP (lines 360–369)
- Protects tools via token verification before execution
The code is production-ready. One minor note: the log level (line 302) is set to
INFOglobally, which may be verbose in production; consider documenting how to adjust log levels.en/includes/quick-starts/agent-auth-py.md (6)
96-172: LangChain Agent Credentials flow is correct and clear.The LangChain implementation (lines 96–172) correctly demonstrates:
- Loading Asgardeo and agent configuration (lines 116–125)
- Obtaining an agent token (line 133)
- Passing the token in the Authorization header to the MCP server (lines 142–143)
- Creating a LangChain agent with Gemini LLM (lines 150–156)
- Invoking the agent with user input (lines 161–165)
Code is production-ready and properly asynchronous. The pattern is clear for users unfamiliar with agent frameworks.
174-262: Google ADK Agent Credentials flow mirrors LangChain pattern well.The Google ADK variant (lines 174–262) follows the same logical flow as LangChain:
- Config loading and agent token retrieval (lines 194–208)
- McpToolset with Bearer token (lines 211–216)
- LLM agent definition and runner setup (lines 223–237)
- Session creation and async invocation (lines 234–257)
The dual-implementation approach ensures developers can pick their framework without learning two entirely different patterns. Excellent consistency.
455-556: LangChain OBO flow is well-documented and logically sound.The OBO implementation for LangChain (lines 455–556) correctly:
- Obtains agent token (line 494)
- Generates authorization URL with PKCE (line 497)
- Starts callback server and waits for code (lines 502–509)
- Exchanges auth code for OBO token (line 518)
- Calls MCP server with OBO token (lines 528–529)
The flow is clearly documented with inline comments (lines 491–520). Code is production-ready.
558-673: Google ADK OBO flow maintains consistency with LangChain variant.The Google ADK OBO implementation (lines 558–673) follows the same authentication sequence as LangChain:
- Agent token retrieval (line 596)
- PKCE-based authorization URL generation (line 599)
- OAuth callback server setup (lines 604–605)
- Auth code exchange for OBO token (line 620)
- McpToolset initialization with OBO token (lines 626–627)
Both framework implementations are logically equivalent, which is excellent for maintainability and user confidence.
268-282: Environment configuration template is clear and comprehensive.The
.envtemplate (lines 270–282) includes all necessary configuration:
- Asgardeo OAuth2 settings (ASGARDEO_BASE_URL, CLIENT_ID, REDIRECT_URI)
- Agent credentials (AGENT_ID, AGENT_SECRET)
- Google Gemini API key (GOOGLE_API_KEY)
Placeholders are well-marked (
<your-tenant>,<your-client-id>, etc.), and the supplementary notes (lines 284–291) clearly explain where to obtain each value. This reduces setup friction significantly.
1-16: Guide introduction and objectives are compelling and clear.The opening (lines 1–16) effectively frames the purpose: authenticating AI agents with Asgardeo and integrating with secure MCP servers. The "By the end of this guide, you will have" section (lines 7–12) sets clear expectations and references the broader Agent Authentication Guide, helping users understand context and next steps.
Updated the AI Agent Authentication Quickstart to Agent Identity Quickstart, enhancing clarity on agent identity establishment and authentication scenarios.
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
en/includes/quick-starts/agent-auth-py.md (1)
90-90: Update google-genai to version 1.54.0 (already flagged in previous review).Line 90 pins
google-genai==1.53.0. Per the previous review, google-genai 1.54.0 was released December 8, 2025 and should be used instead.Apply this diff:
- pip install asgardeo asgardeo_ai python-dotenv google-adk==1.20.0 google-genai==1.53.0 + pip install asgardeo asgardeo_ai python-dotenv google-adk==1.20.0 google-genai==1.54.0
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
en/includes/quick-starts/agent-auth-py.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
en/includes/quick-starts/agent-auth-py.md
[style] ~702-~702: Using many exclamation marks might seem excessive (in this case: 16 exclamation marks for a text that’s 7034 characters long)
Context: ...our browser and log in as a test user. !!! Info You need to create a test user...
(EN_EXCESSIVE_EXCLAMATION)
🔇 Additional comments (1)
en/includes/quick-starts/agent-auth-py.md (1)
1-3: Terminology aligns with feedback—"Agent Identity Quickstart" is appropriate.The document title uses "Agent Identity Quickstart," which addresses the feedback to use consistent terminology. The guide maintains this terminology throughout.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
en/includes/quick-starts/agent-auth-py.md (2)
157-160: Clarify implicit GOOGLE_API_KEY environment variable usage.The
ChatGoogleGenerativeAIinitialization does not explicitly pass the API key parameter; it relies on thelangchain_google_genailibrary readingGOOGLE_API_KEYfrom the environment. While this is documented in the .env template (line 287–288), it may be helpful to add an inline comment in the code examples noting that the API key is sourced from the environment variable to reduce ambiguity for users following the guide.🔎 Suggested improvement (optional)
Add a clarifying comment in both LangChain examples:
# LLM (Gemini) + LangChain Agent + # Note: ChatGoogleGenerativeAI reads GOOGLE_API_KEY from the environment llm = ChatGoogleGenerativeAI( model="gemini-2.0-flash", temperature=0.9 )Also applies to: 542-545
714-715: Minor: Consider moderating tone in info blocks (optional).Static analysis flagged the overall document for a high exclamation mark density. While this is purely stylistic and does not affect the guide's technical accuracy or usability, you may consider rephrasing a few exclamatory statements as assertions for a more neutral tone. This is entirely optional and a matter of documentation style preference.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
en/includes/quick-starts/agent-auth-py.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
en/includes/quick-starts/agent-auth-py.md
[style] ~713-~713: Using many exclamation marks might seem excessive (in this case: 19 exclamation marks for a text that’s 7364 characters long)
Context: ...our browser and log in as a test user. !!! Info You need to create a test user...
(EN_EXCESSIVE_EXCLAMATION)
🔇 Additional comments (1)
en/includes/quick-starts/agent-auth-py.md (1)
13-13: Verify terminology consistency for linked guide reference.Line 13 references "[Agent Authentication Guide]" while the quickstart title uses "Agent Identity". Per past feedback, the documentation should use "Agent Identity" consistently across labels, URLs, and guide references. Verify whether the linked guide has been renamed from "Agent Authentication" to "Agent Identity", and update this reference accordingly if needed.
2 participants
Purpose
Agent Authentication Quickstart guide walks through authenticating AI agents with Asgardeo using Python, covering agent registration, application setup, and both agent-credential and OBO authentication flows. This includes examples of securely calling MCP servers from modern agent frameworks such as LangChain.
MCP Auth Quickstart guide covers building a basic MCP server in Python using FastMCP and configuring OAuth-based authentication with Asgardeo, including token verification and testing with MCP Inspector.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.