NVIDIA · rapids-bot · Oct 10, 2025 · Oct 10, 2025
@@ -15,18 +15,18 @@ See the License for the specific language governing permissions and
 limitations under the License.
 -->
 
-# Secure Token Storage for MCP Authentication
+# Secure Token Storage for Model Context Protocol (MCP) Authentication
 
-The NeMo Agent toolkit provides a configurable, secure token storage mechanism for Model Context Protocol (MCP) OAuth2 authentication. You can store tokens securely using the object store infrastructure, which provides encryption at rest, access controls, and persistence across service restarts.
+The NVIDIA NeMo Agent toolkit provides a configurable, secure token storage mechanism for Model Context Protocol (MCP) OAuth2 authentication. You can store tokens securely using the object store infrastructure, which provides encryption at rest, access controls, and persistence across service restarts.
 
 ## Overview
 
 When using MCP with OAuth2 authentication, the toolkit needs to store authentication tokens for each user. The secure token storage feature provides:
 
-- **Encryption at rest**: Tokens are stored in object stores that support encryption
-- **Flexible backends**: Choose from in-memory (default), S3, MySQL, Redis, or custom object stores
-- **Persistence**: Tokens persist across restarts when using external storage backends
-- **Multi-user support**: Tokens are isolated per user with proper access controls
+- **Encryption at rest**: Stores tokens in object stores that support encryption
+- **Flexible backends**: Allows you to choose from in-memory (default), S3, MySQL, Redis, or custom object stores
+- **Persistence**: Persists tokens across restarts when using external storage backends
+- **Multi-user support**: Isolates tokens per user with proper access controls
 - **Automatic refresh**: Supports OAuth2 token refresh flows
 
 ### Components
@@ -38,10 +38,14 @@ The token storage system includes three main components:
 3. **ObjectStoreTokenStorage**: Implementation backed by configurable object stores such as S3, MySQL, and Redis.
 
 ## Configuration
+This section describes the ways you can configure your token storage.
 
 ### Default Configuration (In-Memory Storage)
 
-By default, MCP OAuth2 authentication uses in-memory storage. No additional configuration is required:
+By default, MCP OAuth2 authentication uses in-memory storage. The following is the default configuration with no additional configuration required.
+:::{note}
+This setup is suitable only for development and testing environments because it uses in-memory storage that is not persistent and unsafe.
+:::
 
 ```yaml
 authentication:
@@ -53,15 +57,12 @@ authentication:
     allow_default_user_id_for_tool_calls: ${ALLOW_DEFAULT_USER_ID_FOR_TOOL_CALLS:-true}
 ```
 
-This setup is **ONLY suitable for development and testing environments** since it uses in-memory storage that is not
-persistent and also unsafe.
-
 ### External Object Store Configuration
 
-For production environments, configure an external object store to persist tokens across restarts. The NeMo Agent toolkit supports S3-compatible storage (MinIO, AWS S3), MySQL, and Redis backends.
+For production environments, configure an external object store to persist tokens across restarts. The NeMo Agent toolkit supports S3-compatible storage (for example, MinIO and AWS S3), MySQL, and Redis backends.
 
 :::{note}
-For detailed object store setup instructions including MinIO, MySQL, and Redis installation and configuration examples, see the `examples/object_store/user_report/README.md` guide (under the "Choose an Object Store" section).
+For detailed object store setup instructions including MinIO, MySQL, and Redis installation and configuration examples, refer to the `examples/object_store/user_report/README.md` guide, under the **Choose an Object Store** section.
 :::
 
 The following example shows token storage configuration using S3-compatible storage (MinIO):
@@ -141,22 +142,22 @@ Example stored token:
 
 ## Token Lifecycle
 
-### 1. Initial Authentication
+### Initial Authentication
 
 When a user first authenticates, the system completes the following steps:
 1. The OAuth2 flow completes and returns an access token.
 2. The token is serialized and stored using the configured storage backend.
 3. The token is associated with the user's session ID.
 
-### 2. Token Retrieval
+### Token Retrieval
 
 On subsequent requests, the system completes the following steps:
 1. The user's session ID is extracted from cookies.
 2. The stored token is retrieved from the storage backend.
 3. The token expiration is checked.
 4. If expired, a token refresh is attempted.
 
-### 3. Token Refresh
+### Token Refresh
 
 When a token expires, the system completes the following steps:
 1. The refresh token is extracted from the stored token.
@@ -167,7 +168,7 @@ When a token expires, the system completes the following steps:
 
 ## Custom Token Storage
 
-You can implement custom token storage by extending the `TokenStorageBase` abstract class:
+Create custom token storage by extending the `TokenStorageBase` abstract class:
 
 ```python
 from nat.plugins.mcp.auth.token_storage import TokenStorageBase

@@ -15,7 +15,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 -->
 
-# MCP Authentication for the NVIDIA NeMo Agent Toolkit
+# Model Context Protocol (MCP) Authentication for the NVIDIA NeMo Agent Toolkit
 MCP provides authorization capabilities at the transport level, enabling MCP clients to make requests to restricted MCP servers on behalf of resource owners. The NVIDIA NeMo Agent toolkit provides a set of built-in authentication providers for accessing servers that require authentication. The `mcp_oauth2` provider is the default authentication provider in the NeMo Agent toolkit for MCP servers. It conforms to the [MCP OAuth2](https://modelcontextprotocol.io/specification/draft/basic/authorization) specification.
 
 ## Supported Capabilities
@@ -58,7 +58,7 @@ export NAT_USER_ID="dev-user"
 export ALLOW_DEFAULT_USER_ID_FOR_TOOL_CALLS=true
 ```
 ## Referencing Auth Providers in Clients
-The authentication provider is referenced by name via the `auth_provider` parameter in the MCP client configuration.
+The authentication provider is referenced by name through the `auth_provider` parameter in the MCP client configuration.
 ```yaml
 function_groups:
   mcp_tools:
@@ -69,12 +69,12 @@ function_groups:
       auth_provider: auth_provider_mcp
 ```
 
-## Limitations & Supported Transports
+## Limitations and Supported Transports
 - MCP Authentication is only supported for `streamable-http` transport. It is not supported for local `stdio` transport or for `sse` transport.
 - Authentication configuration is only available with `mcp_client` style configuration, not with `mcp_tool_wrapper` style configuration.
 
 ## Example Workflow
-The MCP Authentication Example Workflow, `examples/MCP/simple_auth_mcp/README.md`, provides an example of how to use the `mcp_oauth2` authentication provider to authenticate with a MCP server.
+The MCP Authentication Example Workflow, `examples/MCP/simple_auth_mcp/README.md`, provides an example of how to use the `mcp_oauth2` authentication provider to authenticate with an MCP server.
 ### Example Configuration
 ```yaml
 function_groups:
@@ -120,7 +120,7 @@ nat run --config_file examples/MCP/simple_auth_mcp/configs/config-mcp-auth-jira.
 ```
 
 ### Running the Workflow in Multi-User Mode (FastAPI)
-In this mode the workflow is served via a FastAPI frontend. Multiple users can access the workflow concurrently using a UI with `WebSocket` mode enabled.
+In this mode, the workflow is served through a FastAPI frontend. Multiple users can access the workflow concurrently using a UI with `WebSocket` mode enabled.
 
 ```mermaid
 flowchart LR
@@ -137,53 +137,55 @@ flowchart LR
   C2 --> S2
 ```
 
+Follow the steps below to run the workflow in multi-user mode.
 1. Set the environment variables to access the protected MCP server:
 ```bash
 export CORPORATE_MCP_JIRA_URL="https://your-jira-server.com/mcp"
 export NAT_USER_ID="dev-user"
 export ALLOW_DEFAULT_USER_ID_FOR_TOOL_CALLS=false
 ```
-2. **Start the workflow**:
+2. Start the workflow:
 ```bash
 nat serve --config_file examples/MCP/simple_auth_mcp/configs/config-mcp-auth-jira.yml
 ```
 At this point, a consent window is displayed to the user. The user must authorize the workflow to access the MCP server. This user's information is cached as the default user ID. The `default_user_id` credentials are only used for the initial setup and for populating the tools in the workflow or agent prompt at startup.
 
 Subsequent tool calls can be disabled for the default user ID by setting `allow_default_user_id_for_tool_calls` to `false` in the authentication configuration. This is recommended for multi-user workflows to avoid accidental tool calls by unauthorized users.
 
-3. **Start the UI**:
-- Start the UI by following the instructions in the [Launching the UI](../../quick-start/launching-ui.md) documentation.
-- Connect to the UI at http://localhost:3000
+3. Launch the UI:
+- Launch the UI by following the instructions in the [User Interface](../../quick-start/launching-ui.md) documentation.
+- Connect to the UI at `http://localhost:3000`
 
 :::important
 Ensure that `WebSocket` mode is enabled by navigating to the top-right corner and selecting the `WebSocket` option in the arrow pop-out. WebSocket connections are required for OAuth authentication workflows.
 :::
 
-4. **Send the input to the workflow via the UI**:
+4. Send the input to the workflow using the UI:
 ```text
 What is ticket AIQ-1935 about
 ```
 At this point, a consent window is displayed again. The `UI` user must authorize the workflow to access the MCP server and call the tool. This user's information is cached separately using the `WebSocket` session cookie as the user ID.
 
-## Displaying Protected MCP Tools via CLI
+## Displaying Protected MCP Tools through the CLI
 MCP client CLI can be used to display and call MCP tools on a remote MCP server. To use a protected MCP server, you need to provide the `--auth` flag:
 ```bash
 nat mcp client tool list --url http://example.com/mcp --auth
 ```
-This will use the `mcp_oauth2` authentication provider to authenticate the user. For more information, see the [MCP Client](./mcp-client.md) documentation.
+This will use the `mcp_oauth2` authentication provider to authenticate the user. For more information, refer to [MCP Client](./mcp-client.md).
 
 ## Security Considerations
+When using MCP authentication, consider the following security recommendations:
 - The `default_user_id` is used to cache the authenticating user during setup and optionally for tool calls. It is recommended to set `allow_default_user_id_for_tool_calls` to `false` in the authentication configuration for multi-user workflows to avoid accidental tool calls by unauthorized users.
 - Use HTTPS redirect URIs in production environments.
 - Scope OAuth2 tokens to the minimum required permissions.
 - For production deployments, configure [secure token storage](./mcp-auth-token-storage.md) using an external object store (S3, MySQL, or Redis) with encryption enabled.
 
 ## Troubleshooting
-1.  **Setup fails** - This can happen if:
+Setup may fail if one of the following happens:
 - The user identified by `default_user_id` did not complete the authentication flow through the pop-up UI, or
 - The user did not authorize the workflow to access the MCP server
 
-2. **Tool calls fail** - This can happen if:
+Tool calls may fail if one of the following happens:
 - The workflow was not accessed in `WebSocket` mode, or
 - The user did not complete the authentication flow through the `WebSocket` UI, or
 - The user is not authorized to call the tool