9.2. The VoltDB MCP Server

An MCP server provides access to data not normally accessible to large language models (LLMs), either because the information is in a format (such as a database) that the LLM is not familiar with or because it is protected by a firewall or user authentication. The MCP server acts as a conduit and translation layer, extending the scope of the content that the AI agent can use to build its context. In the case of VoltDB, it gives the agent controlled access to the content, structure, and status of the VoltDB database. What information the AI agent can access depends on how you set up the security for the database and the account the server uses.

The current MCP server supports the stdio transport mode only. That is, it can be installed and run on the development system where the AI agent is installed. Other transport modes, most notably HTTP, may be supported in the future.

9.2.1. Installing the VoltDB MCP Server

The VoltDB MCP server is licensed software and will only work with a VoltDB database where the license includes the feature "Active(MCP)". Contact your Volt Active Data sales representative to get access to the VoltDB MCP software and a license with the Active(MCP) feature included.

The VoltDB MCP server software comes as a JAR file that the AI agent will use to invoke the server. In addition to the MCP server JAR, you will need:

An AI agent, such as Claude Code
A running VoltDB database with a license including the "Active(MCP)" feature
The associated VMC service for that database so the server can access the JSON/HTTP API

Follow the instructions you receive to download and install the VoltDB MCP JAR file on your system.

9.2.1.1. Adding the MCP Server to the AI Agent's List of Resources

To use an MCP server, the next step is to add it to the AI agent's list of known content sources. In the case of Claude Code you do this with the mcp add command, giving it instructions for starting the MCP server. For example:

$ claude mcp add voltdb -- 
     java --jar ~/voltmcp/volt-mcp-server.jar \
          --url http://vmcserver:8080

The command line includes:

The command itself, claude mcp add.
A name for the server. In this example, the name is voltdb although you can call it whatever is meaningful to you.
Two dashes to separate any claude arguments from the command to invoke the MCP server.
The command to invoke the MCP server and its arguments. In this case, the command is java specifying the JAR file containing the VoltDB MCP server software.

You only need to issue this command once; the MCP server content becomes available to any subsequent Claude Code sessions. If you only have one VoltDB database to connect to, then voltdb is a useful moniker. However, if you have multiple databases, you need to define separate servers for each with separate names. In which case, naming the servers after the content — such as personneldb or inventorydb — may prove more effective.

9.2.2. Configuring the MCP Server

There are a number of arguments to the java command you can use to the configure the MCP server. By default, if you only specify the JAR file location, the server assumes a database running without security enabled, with the VMC service running locally on the default port without TLS/SSL encryption.

However, there are three primary aspects of the VoltDB database that are critical to configure to use the MCP server effectively. Those attributes are the location of the database, the account the MCP server uses to access the database, and the TLS/SSL settings for the JSON/HTTP interface.

The database location
You use the --url argument to specify the URL of the JSON/HTTP interface to the database. This is the server address and port where the VMC service is running. The MCP server uses the HTTP interface to communicate with the database. In the example in the preceding section it used the -url argument to specify a database accessible through the VMC service at http://vmcserver:8080.
The VoltDB account to use
You can specify the username and password of the account for the MCP server to use on the command line using the -u and -p arguments. However, specifying security information on the command line is a bad practice. So the preferred method is to use the --credentials argument to specify the location of a text file containing the username and password. For example, the following two commands assign the same account and password, using the two different methods:
```
$ claude mcp add voltdb -- 
     java --jar ~/voltmcp/volt-mcp-server.jar \
          --url http://vmcserver:8080 \
          -u=jdoe -p=parsnip
$ cat $HOME/voltcred.txt
username: jdoe
password: parsnip
$ claude mcp add voltdb -- 
     java --jar ~/voltmcp/volt-mcp-server.jar \
          --url http://vmcserver:8080 \
          --credentials=$HOME/voltcred.txt
```
The TLS/SSL settings for the JSON/HTTP interface
If the URL for the JSON/HTTP interface uses the https protocol (rather than the plain text http) then communication with the VMC service is encrypted using TLS/SSL. When TLS/SSL encryption is enabled, you must decide whether the MCP server, acting as a client, will authenticate the VMC server or not. You can choose to ignore the VMC service certificate, by adding the --no-hostname-verification argument. Or, to authenticate the VMC service certificate, you must provide the truststore and keystore credentials for the VMC certificate in a properties file specified by the --ssl argument. For example:
```
$ claude mcp add voltdb -- 
     java --jar ~/voltmcp/volt-mcp-server.jar \
          --url http://vmcserver:8080 \
          --credentials=$HOME/vmcssl.txt
$ cat $HOME/vmcssl.txt
keyStore=mydb.keystore.jks
keyStorePassword=mypasswd
trustStore=mydb.truststore.jks
trustStorePassword=mypasswd
$
```

9.2.3. How to Use the VoltDB MCP Server

MCP servers are normally used to provide access to otherwise closed or proprietary information, extending the knowledge base available to the model. For example, if you are looking to reorganize your shipping routes to minimize delivery times, you may use an MCP server to give the AI agent access to your warehouse locations and inventory in addition to its existing knowledge of geography, highways, and mileage.

The MCP server is a very powerful tool. It gives the LLM access to the database, its structure and status, including the ability to execute SQL statements to add and delete records; create, modify, and delete tables through DDL statements, or even change the configuration or shutdown the database by invoking system procedures. This, obviously, could be either a good or a bad thing, depending on the context.

If security is not enabled on the database, the MCP server has full access to execute any SQL statements, including DDL, and any stored procedures, including system procedures. In fact, the server can execute any of the following MCP functions:

execute_sql — execute any SQL statement, including DDL statements
get_tables — list all the database tables and views
get_table_schema — list all the columns in a table, including their datatype and whether they are declared as NOT NULL
get_procedures — List available stored procedures
call_procedure — call a stored procedure with arguments
get_system_information — list cluster version, node status, and deployment configuration
get_statistics — get statistics for cluster components (TABLE, MEMORY, CPU, etc.)
get_user_profile — get the profile of the authenticated VoltDB user

If you are using a scratch or prototype database, giving the sMCP server full access may be extremely useful. However, if you are connecting the MCP server to a production server, you almost certainly do not want the AI agent modifying the database configuration or changing the database state by calling system procedures such as @Pause, @StopNode, or @Shutdown. To avoid this situation, you must enable security on the database and assign the MCP server to an account that has only read-only access to the database.

Important

It is strongly recommended that when using an MCP server, you do the following:

Enable security for the associated database
Create a separate user account for the MCP server
Start by assigning the MCP user limited (e.g. read-only) permissions

Furthermore, even when using a non-critical development database, it may be best to start by using a read-only account until you see what sort of instructions the agent chooses to execute. For example, you can create a separate MCP role and user account and assign it limited permissions:

$ sqlcmd
1> CREATE ROLE mcp WITH SQLREAD;
2> exit
$ cat security.yaml
deployment:
  users:
  - name: "admin"
    roles: "ADMINISTRATOR"
    password: "dwkued767de"
  - name: "mcpserver"
    roles: "mcp"
    password: "marigold"
$ voltadmin set --file=security.yaml

Once you are comfortable with the behavior of the agent, you may choose to increase the permissions for the MCP user account by reassigning the permissions available to the mcp role. Once you set up the appropriate security settings in the database configuration, you can then add the MCP server to the user agent, providing it the credentials of the account you created:

$ claude mcp add voltdb -- 
     java --jar ~/voltmcp/volt-mcp-server.jar \
          --url http://vmcserver:8080 \
          -u=mcpserver -p=marigold

See the Security chapter in the Using VoltDB guide for more information about enabling security and assigning permissions to user accounts.