MCP server
MCP server is a secure, JWT-authenticated server that implements Model Context Protocol (MCP) for database interactions between your database and AI agents. It provides MCP tools for executing queries, managing job queues, and interacting with the database through APIs.
Prerequisites
System requirements
- Operating System: Linux (Ubuntu/RHEL/CentOS).
- Vertica: Already running and accessible.
- VCluster Web Service running: required to retrieve node and cluster information. When using the default configuration, starting the MCP server automatically starts the VCluster Web Service.
Note
- The MCP server is not supported on Kubernetes in the 26.1 release, but will be supported in later releases.
Network requirements
The following ports must be accessible through the firewall:
- 8667: Default port for MCP server. Must be open for HTTPS connection.
- 8665: Default for VCluster services.
Note
The MCP server must have network access to your database cluster to route SQL queries to your subcluster or sandbox. For optimal operational performance, deploy the MCP server on a dedicated host that does not run Vertica processes.Database access
- Valid database credentials.
- Database user with appropriate permissions to execute intended queries.
- Network connectivity to the database server.
Required files and directories
Ensure the following files and directories exist before starting the MCP server:
- SSL Certificate (default location:
/opt/vertica/config/vcluster_server/):server.pemserver.keyrootca.pem
- Configuration Directory (this is auto-created if it is missing):
/opt/vertica/config//opt/vertica/config/mcp_server/
- Log Directory (this is auto-created if it is missing):
/opt/vertica/log/
Starting the MCP server
Run the following command to start the MCP server:
/opt/vertica/bin/manage_vcluster_server.sh start
This starts both the MCP server and VCluster server.
To start only the MCP server:
/opt/vertica/bin/manage_vcluster_server.sh start mcp_server
Note
You can customize your MCP server configuration by editing/opt/vertica/config/mcp_server.yaml.
Log files for the MCP server are located by default at /opt/vertica/log/mcp_server.log and /opt/vertica/log/mcp_audit.log.
All tools available in the VCluster server are also available through the MCP server.
Obtaining JWT tokens
After starting the MCP server, JWT tokens are required for authentication. Each token contains encrypted database credentials and user information. You can either use the interactive generator to create tokens or input parameters in the command line.
Generating a token using the interactive generator
Run the following and respond to the prompts:
$ /opt/vertica/bin/vertica_mcp_server --generate-token
Missing required parameters for non-interactive mode (--userid and --dbpass).
Falling back to interactive token generation...
═══════════════════════════════════════════════════════════════
JWT Token Generator for MCP Server
(with LevelDB Storage & VCluster)
═══════════════════════════════════════════════════════════════
Enter User ID: mcp_admin
Enter Database User: dbadmin
Enter Database Password:
Enter Expiration (days from now, default 365):
Enter Description (optional):
Enter VCluster Roles (comma-separated, allowed: 'admin', 'operator', 'viewer'; optional): admin
Generating JWT token...
✓ Token generated successfully!
Token Details:
User ID: mcp_admin
DB User: dbadmin
Expires: 2027-06-09 06:03:12 EDT
Valid Days: 365 days
Roles: [admin]
Storage: /opt/vertica/config/mcp_server/userdb
JWT Token:
<JWT_TOKEN>
You can now use this token in your MCP client requests:
curl -k -X POST https://localhost:8667/mcp \
-H "Content-Type: application/json" \
-H "X-Api-Key: <JWT_TOKEN>" \
-d '{...}'
Generating a token using command line inputs
Run (with all parameters specified):
$ /opt/vertica/bin/vertica_mcp_server --generate-token \
> --userid my_mcp_viewer \
> --dbuser mydbuser \
> --dbpass mypassword \
> --description "my viewer" \
> --roles "viewer"
✓ Token generated successfully!
Token Details:
User ID: my_mcp_viewer
DB User: mydbuser
Expires: 2027-06-09 10:35:38 EDT
Valid Days: 365 days
Roles: [viewer]
Storage: /opt/vertica/config/mcp_server/userdb
JWT Token:
<JWT_TOKEN>
You can now use this token in your MCP client requests:
curl -k -X POST https://localhost:8667/mcp \
-H "Content-Type: application/json" \
-H "X-Api-Key: <JWT_TOKEN>" \
-d '{...}'
Multiple tokens per user
A user can have multiple tokens registered in the MCP server. For example, to use different AI clients with separate tokens. Each token requires a unique user_id in the token registry, while sharing the same database username and password. The VCluster server role can be the same or different for each token.
For example, user Bob can register two tokens:
user_id: bob_claude: Mapped to Bob's database credentials with an operator role.user_id: bob_gemini: Mapped to the same credentials with a viewer role.
Admin tokens are an exception. To obtain full admin privileges, the user_id must be set to admin. Only one admin token can be registered at a time, consistent with how database admin privileges are managed. An admin user can still create additional tokens with other user IDs to perform non-admin tasks.
Token security best practices
- Use short expiration times for sensitive environments (30-90 days).
- Store tokens securely - treat them like passwords.
- Never commit tokens to version control.
- Rotate tokens regularly - regenerate before expiration.
- Use HTTPS only - never send tokens over unencrypted connections.
- Monitor audit logs - review authentication attempts.
VCluster server roles and permissions
The MCP server uses VCluster server role-based access control (RBAC) to manage user permissions. Each JWT token is associated with a database user account, and the VCluster server role. MCP user inherits all database privileges from the mapped database user account while VCluster server role assigned to that MCP user determines what VCluster operations they can perform through the MCP server.
Role overview
The following table provides a brief overview of VCluster server roles:
| Role | Description |
|---|---|
| admin | Full access to all VCluster server operations, including query execution, VCluster management, job queue operations, and user management. Inherits all database privileges from the mapped database user. |
| operator | Can view VCluster status, start/stop VCluster, and manage job queue operations. Cannot scale/configure VCluster or manage users. |
| viewer | Read-only access to view VCluster status and monitor job queue operations, providing subcluster and sandbox information that can be used to redirect queries issued via the MCP server to specific subclusters or sandboxes. Cannot perform administrative tasks. |
Note
Assign the operator role only to trusted users, as it allows them to start and stop the cluster.Role permissions overview
The following table summarizes the operations available for each role:
| Operation | admin | operator | viewer |
|---|---|---|---|
| Execute SQL queries | ✓ | ✓ | ✓ |
| View schema/catalog | ✓ | ✓ | ✓ |
| VCluster status / list | ✓ | ✓ | ✓ |
| VCluster start/stop | ✓ | ✓ | ✗ |
| VCluster scale/config | ✓ | ✗ | ✗ |
| Create/manage MCP users | ✓ | ✗ | ✗ |
| Job queue operations | ✓ | ✓ | ✓ |
Post-upgrade steps
If you upgraded from Vertica 26.1 with an existing MCP server configuration, perform the following steps:
- Stop the MCP Server if it was already started.
- Delete the MCP Server configuration directory
/opt/vertica/config/mcp_server. This ensures the new VCluster server roles are enforced in the MCP server. - Generate a new token for each existing MCP server user to apply the updated VCluster server roles included in the MCP token.
- Start the MCP Server.
- Use the new token to connect to the MCP server.