Skip to content

Conversation

@yczhang-nv
Copy link
Contributor

@yczhang-nv yczhang-nv commented Sep 30, 2025

Description

Enable optional token storage for MCP OAuth2 with in-memory or external object-store backends (e.g., S3/MinIO), which are persistent and also more secure. Also enabled users to implement their own external object-store interface.

Closes AIQ-1965

By Submitting this PR I confirm:

  • I am familiar with the Contributing Guidelines.
  • We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
    • Any contribution which contains commits that are not Signed-Off will not be accepted.
  • When the PR is ready for review, new or existing tests cover these changes.
  • When the PR is ready for review, the documentation is up to date with these changes.

Summary by CodeRabbit

  • New Features

    • Secure token storage for MCP OAuth2: in-memory default with optional external object-store backing, persistent across restarts, multi-user isolation, automatic refresh, and graceful fallback.
  • Documentation

    • Added “Secure Token Storage” guide with examples and deployment guidance; MCP auth docs and index updated to reference it.
  • Tests

    • Extensive tests covering token storage backends, key hashing/serialization, provider integration, lazy object-store resolution, and persistence.

Signed-off-by: Yuchen Zhang <[email protected]>
@yczhang-nv yczhang-nv self-assigned this Sep 30, 2025
@coderabbitai
Copy link

coderabbitai bot commented Sep 30, 2025

Walkthrough

Adds secure token storage for MCP OAuth2: introduces async token storage interfaces and implementations (object-store and in-memory), integrates token storage into OAuth2AuthCodeFlowProvider and MCPOAuth2Provider with lazy object-store resolution via a builder, updates config/registration, adds docs and tests.

Changes

Cohort / File(s) Summary
Docs — MCP auth and token storage
docs/source/workflows/mcp/index.md, docs/source/workflows/mcp/mcp-auth-token-storage.md, docs/source/workflows/mcp/mcp-auth.md
Added a new "Secure Token Storage" documentation page, linked it in the MCP index and MCP auth docs, and added production guidance and related-doc references.
MCP OAuth2 provider + wiring
packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider.py, packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/register.py, packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider_config.py
MCPOAuth2Provider constructor now accepts an optional builder; supports resolving a configured token_storage_object_store to an object-store-backed TokenStorage with lazy resolution and in-memory fallback; registration callsite passes builder; config gains `token_storage_object_store: str
Token storage implementations
packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/token_storage.py
New async TokenStorageBase plus ObjectStoreTokenStorage and InMemoryTokenStorage with CRUD methods, URL-safe hashed keys, JSON (de)serialization of AuthResult, metadata/expiry handling, and error handling for missing keys.
Core OAuth2 flow provider
src/nat/authentication/oauth2/oauth2_auth_code_flow_provider.py
OAuth2AuthCodeFlowProvider gains optional token_storage constructor param; authentication now retrieves, refreshes, and persists AuthResult through token storage (replacing prior in-memory dict); custom auth callback typing updated to expect Awaitable.
Tests
tests/nat/mcp/test_mcp_token_storage.py, tests/nat/authentication/test_oauth_exchanger.py
Added comprehensive tests for token storage backends and provider integration, including lazy object-store resolution, persistence, key hashing, serialization; updated oauth exchanger tests to use async token storage store calls instead of direct in-memory dict mutation.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User
  participant Client as MCP Client
  participant MCPProv as MCPOAuth2Provider
  participant Flow as OAuth2AuthCodeFlowProvider
  participant Store as TokenStorage
  participant Obj as ObjectStore

  Note over MCPProv,Flow: Init & config
  MCPProv->>MCPProv: read config.token_storage_object_store
  alt object-store configured but not resolved
    MCPProv->>MCPProv: defer resolution until first auth
  else no object-store configured
    MCPProv->>Store: create InMemoryTokenStorage
  end
  MCPProv->>Flow: instantiate Flow (pass token_storage if ready)

  Note over Client,Flow: Authentication
  Client->>MCPProv: authenticate()
  MCPProv->>Flow: authenticate()
  alt storage available
    Flow->>Store: retrieve(user_id)
    alt valid token
      Store-->>Flow: AuthResult
      Flow-->>MCPProv: return AuthResult
    else missing or expired
      Flow->>Flow: attempt refresh / interactive flow
      alt refresh/flow success
        Flow->>Store: store(user_id, AuthResult)
        Flow-->>MCPProv: AuthResult
      else failure
        Flow-->>MCPProv: Auth failure
      end
    end
  else no storage
    Flow->>Flow: in-memory handling
    Flow-->>MCPProv: AuthResult
  end

  Note over MCPProv,Obj: Lazy object-store resolution on first auth
  MCPProv->>Obj: builder.get_object_store(name)
  alt success
    MCPProv->>Store: create ObjectStoreTokenStorage(Obj)
    MCPProv->>Flow: inject storage
  else failure
    MCPProv->>Store: fallback InMemoryTokenStorage
  end
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Suggested labels

external

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)
Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. You can run @coderabbitai generate docstrings to improve docstring coverage.
✅ Passed checks (2 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check ✅ Passed The title clearly summarizes the main change by indicating the addition of configurable token storage for MCP authentication, uses the imperative mood, is descriptive, and stays within the recommended character limit.
✨ Finishing touches
  • 📝 Generate Docstrings
🧪 Generate unit tests
  • Create PR with unit tests
  • Post copyable unit tests in a comment

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8186325 and fa4fc31.

📒 Files selected for processing (2)
  • docs/source/workflows/mcp/mcp-auth-token-storage.md (1 hunks)
  • tests/nat/authentication/test_oauth_exchanger.py (2 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
  • docs/source/workflows/mcp/mcp-auth-token-storage.md
🧰 Additional context used
📓 Path-based instructions (5)
**/*.{py,yaml,yml}

📄 CodeRabbit inference engine (.cursor/rules/nat-test-llm.mdc)

**/*.{py,yaml,yml}: Configure response_seq as a list of strings; values cycle per call, and [] yields an empty string.
Configure delay_ms to inject per-call artificial latency in milliseconds for nat_test_llm.

Files:

  • tests/nat/authentication/test_oauth_exchanger.py
**/*.py

📄 CodeRabbit inference engine (.cursor/rules/nat-test-llm.mdc)

**/*.py: Programmatic use: create TestLLMConfig(response_seq=[...], delay_ms=...), add with builder.add_llm("", cfg).
When retrieving the test LLM wrapper, use builder.get_llm(name, wrapper_type=LLMFrameworkEnum.) and call the framework’s method (e.g., ainvoke, achat, call).

**/*.py: In code comments/identifiers use NAT abbreviations as specified: nat for API namespace/CLI, nvidia-nat for package name, NAT for env var prefixes; do not use these abbreviations in documentation
Follow PEP 20 and PEP 8; run yapf with column_limit=120; use 4-space indentation; end files with a single trailing newline
Run ruff check --fix as linter (not formatter) using pyproject.toml config; fix warnings unless explicitly ignored
Respect naming: snake_case for functions/variables, PascalCase for classes, UPPER_CASE for constants
Treat pyright warnings as errors during development
Exception handling: use bare raise to re-raise; log with logger.error() when re-raising to avoid duplicate stack traces; use logger.exception() when catching without re-raising
Provide Google-style docstrings for every public module, class, function, and CLI command; first line concise and ending with a period; surround code entities with backticks
Validate and sanitize all user input, especially in web or CLI interfaces
Prefer httpx with SSL verification enabled by default and follow OWASP Top-10 recommendations
Use async/await for I/O-bound work; profile CPU-heavy paths with cProfile or mprof before optimizing; cache expensive computations with functools.lru_cache or external cache; leverage NumPy vectorized operations when beneficial

Files:

  • tests/nat/authentication/test_oauth_exchanger.py
tests/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/general.mdc)

Unit tests reside under tests/ and should use markers defined in pyproject.toml (e.g., integration)

Files:

  • tests/nat/authentication/test_oauth_exchanger.py

⚙️ CodeRabbit configuration file

tests/**/*.py: - Ensure that tests are comprehensive, cover edge cases, and validate the functionality of the code. - Test functions should be named using the test_ prefix, using snake_case. - Any frequently repeated code should be extracted into pytest fixtures. - Pytest fixtures should define the name argument when applying the pytest.fixture decorator. The fixture
function being decorated should be named using the fixture_ prefix, using snake_case. Example:
@pytest.fixture(name="my_fixture")
def fixture_my_fixture():
pass

Files:

  • tests/nat/authentication/test_oauth_exchanger.py
{tests/**/*.py,examples/*/tests/**/*.py}

📄 CodeRabbit inference engine (.cursor/rules/general.mdc)

{tests/**/*.py,examples/*/tests/**/*.py}: Use pytest (with pytest-asyncio for async); name test files test_*.py; test functions start with test_; extract repeated code into fixtures; fixtures must set name in decorator and be named with fixture_ prefix
Mock external services with pytest_httpserver or unittest.mock; do not hit live endpoints
Mark expensive tests with @pytest.mark.slow or @pytest.mark.integration

Files:

  • tests/nat/authentication/test_oauth_exchanger.py
**/*

⚙️ CodeRabbit configuration file

**/*: # Code Review Instructions

  • Ensure the code follows best practices and coding standards. - For Python code, follow
    PEP 20 and
    PEP 8 for style guidelines.
  • Check for security vulnerabilities and potential issues. - Python methods should use type hints for all parameters and return values.
    Example:
    def my_function(param1: int, param2: str) -> bool:
        pass
  • For Python exception handling, ensure proper stack trace preservation:
    • When re-raising exceptions: use bare raise statements to maintain the original stack trace,
      and use logger.error() (not logger.exception()) to avoid duplicate stack trace output.
    • When catching and logging exceptions without re-raising: always use logger.exception()
      to capture the full stack trace information.

Documentation Review Instructions - Verify that documentation and comments are clear and comprehensive. - Verify that the documentation doesn't contain any TODOs, FIXMEs or placeholder text like "lorem ipsum". - Verify that the documentation doesn't contain any offensive or outdated terms. - Verify that documentation and comments are free of spelling mistakes, ensure the documentation doesn't contain any

words listed in the ci/vale/styles/config/vocabularies/nat/reject.txt file, words that might appear to be
spelling mistakes but are listed in the ci/vale/styles/config/vocabularies/nat/accept.txt file are OK.

Misc. - All code (except .mdc files that contain Cursor rules) should be licensed under the Apache License 2.0,

and should contain an Apache License 2.0 header comment at the top of each file.

  • Confirm that copyright years are up-to date whenever a file is changed.

Files:

  • tests/nat/authentication/test_oauth_exchanger.py
🧬 Code graph analysis (1)
tests/nat/authentication/test_oauth_exchanger.py (1)
src/nat/data_models/authentication.py (2)
  • AuthResult (194-245)
  • BearerTokenCred (158-165)
🪛 Ruff (0.13.2)
tests/nat/authentication/test_oauth_exchanger.py

179-179: Possible hardcoded password assigned to argument: "token"

(S106)


230-230: Possible hardcoded password assigned to argument: "token"

(S106)

🔇 Additional comments (2)
tests/nat/authentication/test_oauth_exchanger.py (2)

176-182: LGTM! Correct transition to async token storage.

The change from direct dict assignment to await client._token_storage.store(...) properly aligns the test with the new token storage abstraction. The test logic remains correct and continues to verify token refresh behavior for expired tokens.

Note: The static analysis warning (S106) on line 179 is a false positive—token="stale" is a test fixture value, not a hardcoded credential.


227-233: LGTM! Consistent use of async token storage.

The change mirrors the pattern from the previous test, correctly using await client._token_storage.store(...) to set up the test scenario. The test continues to verify the fallback-to-callback behavior when token refresh fails.

Note: The static analysis warning (S106) on line 230 is a false positive—token="old" is a test fixture value, not a hardcoded credential.


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.

❤️ Share

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

@yczhang-nv yczhang-nv changed the base branch from develop to release/1.3 October 1, 2025 18:02
@dagardner-nv dagardner-nv deleted the branch NVIDIA:release/1.3 October 1, 2025 20:06
@willkill07 willkill07 reopened this Oct 1, 2025
Signed-off-by: Yuchen Zhang <[email protected]>
Signed-off-by: Yuchen Zhang <[email protected]>
Signed-off-by: Yuchen Zhang <[email protected]>
@yczhang-nv
Copy link
Contributor Author

@CodeRabbit review full

@coderabbitai
Copy link

coderabbitai bot commented Oct 1, 2025

@yczhang-nv: I'll perform a full review of the PR changes.

✅ Actions performed

Full review triggered.

@coderabbitai coderabbitai bot added feature request New feature or request non-breaking Non-breaking change labels Oct 1, 2025
Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (1)
packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/token_storage.py (1)

177-179: Use logger.exception when swallowing the error

Per our logging guideline, when catching an exception and not re-raising, call logger.exception to capture the stack trace instead of logger.error(..., exc_info=True). Please adjust accordingly. As per coding guidelines.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 30639a0 and 3eff069.

📒 Files selected for processing (9)
  • docs/source/workflows/mcp/index.md (1 hunks)
  • docs/source/workflows/mcp/mcp-auth-token-storage.md (1 hunks)
  • docs/source/workflows/mcp/mcp-auth.md (2 hunks)
  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider.py (7 hunks)
  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider_config.py (1 hunks)
  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/register.py (1 hunks)
  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/token_storage.py (1 hunks)
  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/client_base.py (0 hunks)
  • src/nat/authentication/oauth2/oauth2_auth_code_flow_provider.py (5 hunks)
💤 Files with no reviewable changes (1)
  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/client_base.py
🧰 Additional context used
📓 Path-based instructions (4)
**/*

⚙️ CodeRabbit configuration file

**/*: # Code Review Instructions

  • Ensure the code follows best practices and coding standards. - For Python code, follow
    PEP 20 and
    PEP 8 for style guidelines.
  • Check for security vulnerabilities and potential issues. - Python methods should use type hints for all parameters and return values.
    Example:
    def my_function(param1: int, param2: str) -> bool:
        pass
  • For Python exception handling, ensure proper stack trace preservation:
    • When re-raising exceptions: use bare raise statements to maintain the original stack trace,
      and use logger.error() (not logger.exception()) to avoid duplicate stack trace output.
    • When catching and logging exceptions without re-raising: always use logger.exception()
      to capture the full stack trace information.

Documentation Review Instructions - Verify that documentation and comments are clear and comprehensive. - Verify that the documentation doesn't contain any TODOs, FIXMEs or placeholder text like "lorem ipsum". - Verify that the documentation doesn't contain any offensive or outdated terms. - Verify that documentation and comments are free of spelling mistakes, ensure the documentation doesn't contain any

words listed in the ci/vale/styles/config/vocabularies/nat/reject.txt file, words that might appear to be
spelling mistakes but are listed in the ci/vale/styles/config/vocabularies/nat/accept.txt file are OK.

Misc. - All code (except .mdc files that contain Cursor rules) should be licensed under the Apache License 2.0,

and should contain an Apache License 2.0 header comment at the top of each file.

  • Confirm that copyright years are up-to date whenever a file is changed.

Files:

  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/register.py
  • docs/source/workflows/mcp/mcp-auth.md
  • docs/source/workflows/mcp/mcp-auth-token-storage.md
  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider_config.py
  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/token_storage.py
  • docs/source/workflows/mcp/index.md
  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider.py
  • src/nat/authentication/oauth2/oauth2_auth_code_flow_provider.py
packages/**/*

⚙️ CodeRabbit configuration file

packages/**/*: - This directory contains optional plugin packages for the toolkit, each should contain a pyproject.toml file. - The pyproject.toml file should declare a dependency on nvidia-nat or another package with a name starting
with nvidia-nat-. This dependency should be declared using ~=<version>, and the version should be a two
digit version (ex: ~=1.0).

  • Not all packages contain Python code, if they do they should also contain their own set of tests, in a
    tests/ directory at the same level as the pyproject.toml file.

Files:

  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/register.py
  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider_config.py
  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/token_storage.py
  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider.py
docs/source/**/*

⚙️ CodeRabbit configuration file

This directory contains the source code for the documentation. All documentation should be written in Markdown format. Any image files should be placed in the docs/source/_static directory.

Files:

  • docs/source/workflows/mcp/mcp-auth.md
  • docs/source/workflows/mcp/mcp-auth-token-storage.md
  • docs/source/workflows/mcp/index.md
src/nat/**/*

⚙️ CodeRabbit configuration file

This directory contains the core functionality of the toolkit. Changes should prioritize backward compatibility.

Files:

  • src/nat/authentication/oauth2/oauth2_auth_code_flow_provider.py
🪛 Ruff (0.13.2)
packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/token_storage.py

174-174: Consider moving this statement to an else block

(TRY300)

packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider.py

393-393: Abstract raise to an inner function

(TRY301)


393-393: Avoid specifying long messages outside the exception class

(TRY003)


398-398: Do not catch blind exception: Exception

(BLE001)

src/nat/authentication/oauth2/oauth2_auth_code_flow_provider.py

85-85: Unused method argument: kwargs

(ARG002)


91-91: Avoid specifying long messages outside the exception class

(TRY003)


127-127: Avoid specifying long messages outside the exception class

(TRY003)

⏰ 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). (1)
  • GitHub Check: CI Pipeline / Check

Signed-off-by: Yuchen Zhang <[email protected]>
Signed-off-by: Yuchen Zhang <[email protected]>
@yczhang-nv yczhang-nv marked this pull request as ready for review October 1, 2025 23:58
@yczhang-nv yczhang-nv requested a review from a team as a code owner October 1, 2025 23:58
Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider.py (1)

288-318: Add a type hint for builder.

Public APIs must expose complete type hints. Please annotate the builder parameter (and import the corresponding type under TYPE_CHECKING) so callers know which builder interface is expected.

-from nat.plugins.mcp.auth.auth_provider_config import MCPOAuth2ProviderConfig
+from nat.plugins.mcp.auth.auth_provider_config import MCPOAuth2ProviderConfig
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from nat.builder.builder import Builder
@@
-    def __init__(self, config: MCPOAuth2ProviderConfig, builder=None):
+    def __init__(self, config: MCPOAuth2ProviderConfig, builder: "Builder | None" = None):

As per coding guidelines.

♻️ Duplicate comments (1)
src/nat/authentication/oauth2/oauth2_auth_code_flow_provider.py (1)

87-95: Guard Context.get() before accessing it.

Calling Context.get() unconditionally still raises RuntimeError whenever no NAT context is active—even when a caller supplies user_id. That regresses previously working flows and matches the outstanding review note. Wrap the lookup in a try/except RuntimeError and only inspect cookies when the context is available.

-        context = Context.get()
-        if user_id is None and hasattr(context, "metadata") and hasattr(
-                context.metadata, "cookies") and context.metadata.cookies is not None:
+        context = None
+        if user_id is None:
+            try:
+                context = Context.get()
+            except RuntimeError:
+                context = None
+
+        if user_id is None and context and hasattr(context, "metadata") and hasattr(
+                context.metadata, "cookies") and context.metadata.cookies is not None:
📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3eff069 and 8186325.

📒 Files selected for processing (3)
  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider.py (7 hunks)
  • src/nat/authentication/oauth2/oauth2_auth_code_flow_provider.py (5 hunks)
  • tests/nat/mcp/test_mcp_token_storage.py (1 hunks)
🧰 Additional context used
📓 Path-based instructions (10)
**/*.{py,yaml,yml}

📄 CodeRabbit inference engine (.cursor/rules/nat-test-llm.mdc)

**/*.{py,yaml,yml}: Configure response_seq as a list of strings; values cycle per call, and [] yields an empty string.
Configure delay_ms to inject per-call artificial latency in milliseconds for nat_test_llm.

Files:

  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider.py
  • src/nat/authentication/oauth2/oauth2_auth_code_flow_provider.py
  • tests/nat/mcp/test_mcp_token_storage.py
**/*.py

📄 CodeRabbit inference engine (.cursor/rules/nat-test-llm.mdc)

**/*.py: Programmatic use: create TestLLMConfig(response_seq=[...], delay_ms=...), add with builder.add_llm("", cfg).
When retrieving the test LLM wrapper, use builder.get_llm(name, wrapper_type=LLMFrameworkEnum.) and call the framework’s method (e.g., ainvoke, achat, call).

**/*.py: In code comments/identifiers use NAT abbreviations as specified: nat for API namespace/CLI, nvidia-nat for package name, NAT for env var prefixes; do not use these abbreviations in documentation
Follow PEP 20 and PEP 8; run yapf with column_limit=120; use 4-space indentation; end files with a single trailing newline
Run ruff check --fix as linter (not formatter) using pyproject.toml config; fix warnings unless explicitly ignored
Respect naming: snake_case for functions/variables, PascalCase for classes, UPPER_CASE for constants
Treat pyright warnings as errors during development
Exception handling: use bare raise to re-raise; log with logger.error() when re-raising to avoid duplicate stack traces; use logger.exception() when catching without re-raising
Provide Google-style docstrings for every public module, class, function, and CLI command; first line concise and ending with a period; surround code entities with backticks
Validate and sanitize all user input, especially in web or CLI interfaces
Prefer httpx with SSL verification enabled by default and follow OWASP Top-10 recommendations
Use async/await for I/O-bound work; profile CPU-heavy paths with cProfile or mprof before optimizing; cache expensive computations with functools.lru_cache or external cache; leverage NumPy vectorized operations when beneficial

Files:

  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider.py
  • src/nat/authentication/oauth2/oauth2_auth_code_flow_provider.py
  • tests/nat/mcp/test_mcp_token_storage.py
packages/*/src/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/general.mdc)

Importable Python code inside packages must live under packages//src/

Files:

  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider.py
{src/**/*.py,packages/*/src/**/*.py}

📄 CodeRabbit inference engine (.cursor/rules/general.mdc)

All public APIs must have Python 3.11+ type hints on parameters and return values; prefer typing/collections.abc abstractions; use typing.Annotated when useful

Files:

  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider.py
  • src/nat/authentication/oauth2/oauth2_auth_code_flow_provider.py
**/*

⚙️ CodeRabbit configuration file

**/*: # Code Review Instructions

  • Ensure the code follows best practices and coding standards. - For Python code, follow
    PEP 20 and
    PEP 8 for style guidelines.
  • Check for security vulnerabilities and potential issues. - Python methods should use type hints for all parameters and return values.
    Example:
    def my_function(param1: int, param2: str) -> bool:
        pass
  • For Python exception handling, ensure proper stack trace preservation:
    • When re-raising exceptions: use bare raise statements to maintain the original stack trace,
      and use logger.error() (not logger.exception()) to avoid duplicate stack trace output.
    • When catching and logging exceptions without re-raising: always use logger.exception()
      to capture the full stack trace information.

Documentation Review Instructions - Verify that documentation and comments are clear and comprehensive. - Verify that the documentation doesn't contain any TODOs, FIXMEs or placeholder text like "lorem ipsum". - Verify that the documentation doesn't contain any offensive or outdated terms. - Verify that documentation and comments are free of spelling mistakes, ensure the documentation doesn't contain any

words listed in the ci/vale/styles/config/vocabularies/nat/reject.txt file, words that might appear to be
spelling mistakes but are listed in the ci/vale/styles/config/vocabularies/nat/accept.txt file are OK.

Misc. - All code (except .mdc files that contain Cursor rules) should be licensed under the Apache License 2.0,

and should contain an Apache License 2.0 header comment at the top of each file.

  • Confirm that copyright years are up-to date whenever a file is changed.

Files:

  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider.py
  • src/nat/authentication/oauth2/oauth2_auth_code_flow_provider.py
  • tests/nat/mcp/test_mcp_token_storage.py
packages/**/*

⚙️ CodeRabbit configuration file

packages/**/*: - This directory contains optional plugin packages for the toolkit, each should contain a pyproject.toml file. - The pyproject.toml file should declare a dependency on nvidia-nat or another package with a name starting
with nvidia-nat-. This dependency should be declared using ~=<version>, and the version should be a two
digit version (ex: ~=1.0).

  • Not all packages contain Python code, if they do they should also contain their own set of tests, in a
    tests/ directory at the same level as the pyproject.toml file.

Files:

  • packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider.py
src/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/general.mdc)

All importable Python code must live under src/ (or packages//src/)

Files:

  • src/nat/authentication/oauth2/oauth2_auth_code_flow_provider.py
src/nat/**/*

📄 CodeRabbit inference engine (.cursor/rules/general.mdc)

Changes in src/nat should prioritize backward compatibility

Files:

  • src/nat/authentication/oauth2/oauth2_auth_code_flow_provider.py

⚙️ CodeRabbit configuration file

This directory contains the core functionality of the toolkit. Changes should prioritize backward compatibility.

Files:

  • src/nat/authentication/oauth2/oauth2_auth_code_flow_provider.py
tests/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/general.mdc)

Unit tests reside under tests/ and should use markers defined in pyproject.toml (e.g., integration)

Files:

  • tests/nat/mcp/test_mcp_token_storage.py

⚙️ CodeRabbit configuration file

tests/**/*.py: - Ensure that tests are comprehensive, cover edge cases, and validate the functionality of the code. - Test functions should be named using the test_ prefix, using snake_case. - Any frequently repeated code should be extracted into pytest fixtures. - Pytest fixtures should define the name argument when applying the pytest.fixture decorator. The fixture
function being decorated should be named using the fixture_ prefix, using snake_case. Example:
@pytest.fixture(name="my_fixture")
def fixture_my_fixture():
pass

Files:

  • tests/nat/mcp/test_mcp_token_storage.py
{tests/**/*.py,examples/*/tests/**/*.py}

📄 CodeRabbit inference engine (.cursor/rules/general.mdc)

{tests/**/*.py,examples/*/tests/**/*.py}: Use pytest (with pytest-asyncio for async); name test files test_*.py; test functions start with test_; extract repeated code into fixtures; fixtures must set name in decorator and be named with fixture_ prefix
Mock external services with pytest_httpserver or unittest.mock; do not hit live endpoints
Mark expensive tests with @pytest.mark.slow or @pytest.mark.integration

Files:

  • tests/nat/mcp/test_mcp_token_storage.py
🧬 Code graph analysis (3)
packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider.py (4)
packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider_config.py (1)
  • MCPOAuth2ProviderConfig (23-84)
packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/token_storage.py (2)
  • InMemoryTokenStorage (207-265)
  • ObjectStoreTokenStorage (86-204)
src/nat/authentication/oauth2/oauth2_auth_code_flow_provider.py (3)
  • _set_custom_auth_callback (81-84)
  • OAuth2AuthCodeFlowProvider (37-140)
  • authenticate (86-140)
src/nat/builder/builder.py (1)
  • get_object_store_client (174-175)
src/nat/authentication/oauth2/oauth2_auth_code_flow_provider.py (3)
packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/token_storage.py (7)
  • InMemoryTokenStorage (207-265)
  • store (45-53)
  • store (121-156)
  • store (229-237)
  • retrieve (56-66)
  • retrieve (158-179)
  • retrieve (239-249)
src/nat/data_models/authentication.py (4)
  • AuthenticatedContext (66-77)
  • AuthResult (194-245)
  • is_expired (206-210)
  • BearerTokenCred (158-165)
src/nat/builder/context.py (5)
  • Context (115-299)
  • get (111-112)
  • get (289-299)
  • metadata (87-90)
  • metadata (149-158)
tests/nat/mcp/test_mcp_token_storage.py (5)
src/nat/data_models/authentication.py (2)
  • AuthResult (194-245)
  • BearerTokenCred (158-165)
src/nat/object_store/models.py (1)
  • ObjectStoreItem (21-38)
packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider.py (2)
  • MCPOAuth2Provider (285-430)
  • _nat_oauth2_authenticate (382-430)
packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/token_storage.py (2)
  • InMemoryTokenStorage (207-265)
  • ObjectStoreTokenStorage (86-204)
packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider_config.py (1)
  • MCPOAuth2ProviderConfig (23-84)
🪛 Ruff (0.13.2)
packages/nvidia_nat_mcp/src/nat/plugins/mcp/auth/auth_provider.py

397-397: Abstract raise to an inner function

(TRY301)


397-397: Avoid specifying long messages outside the exception class

(TRY003)


402-402: Do not catch blind exception: Exception

(BLE001)

src/nat/authentication/oauth2/oauth2_auth_code_flow_provider.py

86-86: Unused method argument: kwargs

(ARG002)


92-92: Avoid specifying long messages outside the exception class

(TRY003)


125-125: Avoid specifying long messages outside the exception class

(TRY003)

tests/nat/mcp/test_mcp_token_storage.py

275-275: Unused method argument: sample_auth_result

(ARG002)


314-314: Possible hardcoded password assigned to: "token_storage_object_store"

(S105)


322-322: Possible hardcoded password assigned to: "_token_storage_object_store_name"

(S105)


327-327: Possible hardcoded password assigned to: "token_storage_object_store"

(S105)


338-338: Possible hardcoded password assigned to argument: "token_url"

(S106)


340-340: Possible hardcoded password assigned to argument: "client_secret"

(S106)

@AnuradhaKaruppiah
Copy link
Contributor

@yczhang-nv looks good. we may need to add more doc to show how to use custom storage but that can be done in a separate PR.

Signed-off-by: Yuchen Zhang <[email protected]>
@coderabbitai coderabbitai bot added the external This issue was filed by someone outside of the NeMo Agent toolkit team label Oct 2, 2025
@yczhang-nv yczhang-nv removed the external This issue was filed by someone outside of the NeMo Agent toolkit team label Oct 2, 2025
@yczhang-nv
Copy link
Contributor Author

/merge

@rapids-bot rapids-bot bot merged commit 19a4f53 into NVIDIA:release/1.3 Oct 2, 2025
17 checks passed
@yczhang-nv yczhang-nv deleted the yuchen-add-token-storage branch October 2, 2025 18:17
yczhang-nv added a commit to yczhang-nv/NeMo-Agent-Toolkit that referenced this pull request Oct 2, 2025
Enable optional token storage for MCP OAuth2 with in-memory or external object-store backends (e.g., S3/MinIO), which are persistent and also more secure. Also enabled users to implement their own external object-store interface.

Closes AIQ-1965

## By Submitting this PR I confirm:
- I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/NeMo-Agent-Toolkit/blob/develop/docs/source/resources/contributing.md).
- We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
  - Any contribution which contains commits that are not Signed-Off will not be accepted.
- When the PR is ready for review, new or existing tests cover these changes.
- When the PR is ready for review, the documentation is up to date with these changes.

## Summary by CodeRabbit

- New Features
  - Secure token storage for MCP OAuth2: in-memory default with optional external object-store backing, persistent across restarts, multi-user isolation, automatic refresh, and graceful fallback.

- Documentation
  - Added “Secure Token Storage” guide with examples and deployment guidance; MCP auth docs and index updated to reference it.

- Tests
  - Extensive tests covering token storage backends, key hashing/serialization, provider integration, lazy object-store resolution, and persistence.

Authors:
  - Yuchen Zhang (https://github.com/yczhang-nv)

Approvers:
  - Eric Evans II (https://github.com/ericevans-nv)

URL: NVIDIA#883
Signed-off-by: Yuchen Zhang <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature request New feature or request non-breaking Non-breaking change

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants