MCP server

The Vertica 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.

Starting in release 26.3, the Vertica MCP server is installed separately as a standalone RPM with its own release cadence. Each MCP server release supports the most recent release of Vertica.

The Vertica MCP server has the following installation and network requirements:

• The Vertica MCP server RPM cannot be installed on a host that has Vertica installed, whether Vertica is running or not.
• There is a limit of one MCP server per database. If you have multiple databases, you must install the MCP server on a separate host for each database.
• AI agents can connect to multiple MCP servers, allowing a single agent to query multiple Vertica databases. Each MCP server connection uses a unique JWT token.

See Network requirements for more specifics.

Prerequisites

System requirements

Operating System: Linux (RHEL/CentOS).

The MCP server host system cannot have Vertica installed.

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.

The MCP server and must have network access to your database cluster to route SQL queries to your subcluster or sandbox.

Database access

• Valid database credentials.
• Database user with appropriate permissions to execute intended queries.
• Network connectivity to the database server.

Installing the MCP server

See Installing the MCP server RPM for more information.

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 permissions overview

The following table summarizes the operations available for each role: