MCP server

The OpenText Analytics Database MCP server is a secure, JWT-authenticated server that implements Model Context Protocol (MCP) for database interactions between your database and AI agents.

The OpenText™ Analytics Database 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 a tool for executing queries, managing job queues, and interacting with the database through APIs.

Prerequisites

System requirements

  • Operating System: Linux (Ubuntu/RHEL/CentOS).
  • OpenText™ Analytics Database: 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.

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.

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.pem
    • server.key
    • rootca.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

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:

/opt/vertica/bin/vertica_mcp_server --generate-token

The following are the prompts (with example inputs):

Enter user ID: dbadmin
Enter database name: mydb
Enter password: ********
Enter description (optional): Database Administrator
Enter expiration days (default 365): 365

Generating a token using command line inputs

Run (with all parameters specified):

./mcp_server --generate-token \
  --userid dbadmin \
  --dbname mydb \
  --dbpass mypassword \
  --description "Data Analyst" \
  --expiration-days 90

Token output

Regardless of the method used, the output will be a JWT token string that can be used for authenticating requests to the MCP server:

Generated JWT Token:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyaWQiOiJkYmFkbWluIiwiZGJfbmFtZSI6Im15ZGIiLCJwYXNzd29yZCI6ImVuY3J5cHRlZF9wYXNzd29yZCIsImlhdCI6MTczMjI0MzYzMSwibmJmIjoxNzMyMjQzNjMxLCJleHAiOjE3NjM3Nzk2MzF9.abc123...

Client added to /opt/vertica/config/mcp_server/client.yaml
Status: active

Token signatures are stored in /opt/vertica/config/mcp_server/client.yaml and you can manage them there.

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.

Roles and permissions

The MCP server supports role-based access control (RBAC) to manage user permissions. Each JWT token is associated with a database user account, and the permissions granted to that user in the database determine what operations they can perform through the MCP server.

Role overview

The following table provides a brief overview of MCP server roles:

Role Description
admin Full access to all MCP server operations, including query execution, VCluster management, job queue operations, and user management. Inherits all database privileges from the mapped database user.
operator Can execute SQL queries, view schema/catalog and VCluster status, start/stop VCluster, and manage job queue operations. Cannot scale/configure VCluster or manage users.
viewer Read-only access to execute queries, view schema/catalog, view VCluster status, and monitor job queue operations. Cannot perform administrative tasks.

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 OpenText™ Analytics Database 26.1 with an existing MCP server configuration, perform the following steps:

  1. Stop the MCP Server if it was already started.
  2. Delete the MCP Server configuration directory /opt/vertica/config/mcp_server. This ensures the new VCluster server roles are enforced in the MCP server.
  3. Generate a new token for each existing MCP server user to apply the updated VCluster server roles included in the MCP token.
  4. Start the MCP Server.
  5. Use the new token to connect to the MCP server.

In this section