Token generation and configuration

Vertica AI Assist authenticates requests to the MCP server using JWTs. The system uses these tokens to authenticate all MCP requests during the session. Before generating user tokens, a super administrator must configure the MCP Administrator JWT.

Prerequisites

Before configuring tokens:

1. Create a VCluster database. For more information, see Database management with VCluster UI.
2. Start the MCP server. For more information, see MCP server. During its initial startup, the MCP server creates the file /opt/vertica/config/mcp_server.yaml with the default setting token_api_enabled: false. For information about setting token_api_enabled to true, see Enable the MCP token generation API.

Initial MCP administrator token setup

For security reasons, manually generate the first administrator token. This ensures that only an authorized administrator can create and receive the initial token. Run:

   /opt/vertica/bin/mcp_server --generate-token \ 

 --user <db_user> \ 

 --dbname <database_name> \ 

 --dbpass '<password>' \ 

 --description "UMC Integration Token" \ 

 --expiration-days <N> 

Sample output:

   User ID:      mcp_superuser 

   DB User:      release 

   Expires:      2027-06-05 02:34:43 EDT 

   Valid Days:   365 days 

   Roles:        [admin] 

   Storage:      /opt/vertica/config/mcp_server/userdb 

   JWT Token:    <generated JWT>

Store this JWT in a secure location. Vertica AI Assist uses it to generate user access tokens.

Enable the MCP token generation API

The token generation endpoint is disabled by default. To enable it:

1. Stop the MCP server.
2. Open /opt/vertica/config/mcp_server.yaml.
3. Set token_api_enabled to true.
4. Save the file.
5. Restart the MCP server.
   After you enable the endpoint, Vertica AI Assist can request user-specific access tokens from the MCP server.

Configure the MCP administrator JWT

Configure the administrator JWT in the database configuration file.

1. Open config/dbconfigs/<cluster>-<database>.yaml.

2. Locate jwt_key.

3. Copy the generated administrator JWT to jwt_key.

4. Save the configuration file.

   Note

      Vertica AI Assist can generate user access tokens only if the MCP administrator JWT is configured. If `jwt_key` is missing or invalid, users who attempt to use Vertica AI Assist receive an authentication error.  
   

Token scoping and role-based access

From this release, Vertica AI Assist generates user-specific access tokens. Each generated token is scoped to the user's MC role, ensuring that users can perform only the operations they are authorized to perform.

MCP role capabilities

MCP roles and their capabilities are summarized in this table.

Role summary

The summary of MCP roles is given below.

• Admin
• Operator
• Viewer

Admin

Admin provides unrestricted MCP access, including the following:

• Cluster administration
• Security management
• Backup and restore
• Database administration
• User management
• All MCP tools

Operator

Operator provides operational capabilities, including the following:

• Cluster monitoring
• Start and stop the cluster
• Query management
• Job queue operations
• Performance troubleshooting

Operators cannot modify cluster configuration or manage users.

   Assign the `Operator` role only to trusted users as it allows cluster start and stop operations.

Viewer

Viewer provides read-only access to monitoring information, including the following:

• Database schemas
• User sessions
• System metrics
• Cluster status

Viewers cannot perform administrative or operational changes.

Token lifecycle

Vertica AI Assist automatically manages user access tokens throughout the user session. Note the following:

• User tokens remain valid for 1 day.
• Tokens are automatically refreshed while the session is active.
• Tokens are permanently deleted when the user logs out.
• After configuration, no manual token management is required.

Permission enforcement

Vertica AI Assist enforces the permissions associated with the MC role of the authenticated user. If a user requests an action that exceeds their assigned permissions, Vertica AI Assist:

• Rejects the request.
• Informs the user that they do not have the required permissions to perform the action.
• Does not execute any unauthorized action.

This behavior helps ensure that users can perform only the actions permitted by their assigned role.

Compatibility with earlier Vertica versions

Per-user access tokens are available in Vertica 26.3 and later versions. When Vertica AI Assist connects to an earlier Vertica version, it automatically uses a compatible authentication method. For Vertica versions earlier than 26.3:

• The user token generation endpoint is not available.
• Vertica AI Assist automatically detects the Vertica version.
• Vertica AI Assist uses a shared administrator connection for compatibility.
• No additional configuration is required.

This fallback behavior allows Vertica AI Assist to operate with earlier Vertica versions and automatically use per-user access tokens in Vertica 26.3 and later versions.