Vertica MCP Server

Transform your Vertica Analytics Database into an AI-powered intelligence layer

Quick Start • Documentation • Features • Contributing • Community

Why Vertica MCP?

The Vertica MCP Server is a production-ready implementation of the Model Context Protocol that transforms your Vertica Analytics Database into an intelligent, AI-accessible data platform. Built with enterprise security and performance in mind, it enables AI assistants like Claude, ChatGPT, and Cursor to directly query, analyze, and optimize your Vertica databases through natural language.

What is MCP?

The Model Context Protocol (MCP) is an open standard developed by Anthropic that provides a universal way for AI assistants to connect with external tools and data sources. Think of it as "USB-C for AI" - a standardized interface that allows any MCP-compatible AI to interact with your systems without custom integrations.

Key Benefits

• Universal AI Connectivity: Connect any MCP-compatible AI to your Vertica database without custom integrations

• Enterprise Security: Fine-grained permissions at schema and operation levels with SSL/TLS support

• High Performance: Connection pooling, query streaming, and automatic pagination for handling massive datasets

• AI-Optimized: Built-in prompts and tools specifically designed for database analysis and optimization

• Multiple Transports: Support for STDIO, HTTP, and SSE to fit any deployment scenario

• Production Ready: Battle-tested with comprehensive error handling, logging, and monitoring

Prerequisites

• Python 3.11 or higher

• Vertica Database (accessible instance)

• uv (Python package manager) - Installation guide

• Docker (optional, for containerized deployment)

• Claude Desktop or another MCP-compatible client

Quick Start

Method 1: Local Installation (Development Environment)

This method is recommended when you want to modify the code or work with the development version.

Method 2: PyPI Installation (Production Environment)

This method is recommended for production deployments and when you want to use the stable release.

Configuration File

After running vertica-mcp --init, edit the generated .env file with your specific settings:

Testing with MCP Inspector

The MCP Inspector is a valuable tool for testing and debugging your server configuration:

The inspector will open at http://localhost:6274 where you can:

• View available database tools and their schemas

• Test tool execution interactively with real data

• Validate MCP protocol compliance

• Debug connection issues and error responses

For STDIO testing (not recommended due to command complexity), use HTTP transport which provides identical functionality validation with better debugging capabilities.

Method 3: Docker Deployment

Docker deployment is ideal for containerized environments and consistent deployments across different systems.

Build Docker Image

Run with Docker Compose

Compose automatically reads a .env file if present. Vertica credentials and configuration are loaded from .env, while network binding and transport options have Docker-safe defaults (HTTP_BIND=0.0.0.0, SSE_BIND=0.0.0.0).

Binding behavior

• By default, .env sets BIND=127.0.0.1 (localhost) for safety.

• The Compose file defines service-specific bind variables:

• This means:

  • For local runs, the server binds to localhost.

  • For Docker, HTTP/SSE containers bind to 0.0.0.0 so they’re reachable from your host.

Override on the fly

You can override the bind or port at runtime:

To skip Vertica credential checks (for demo or offline runs):

Manual Docker Run

Features

Core Tools

Query Execution

• run_query_safely - Smart query execution with large result detection and automatic warnings

• execute_query_paginated - Efficient pagination for large datasets with configurable page sizes

• execute_query_stream - Real-time streaming for massive results with memory-efficient processing

Schema Management

• get_database_schemas - Explore database organization and available schemas

• get_schema_tables - List tables with metadata including row counts and storage information

• get_table_structure - Detailed column information, data types, constraints, and indexes

• get_table_projections - Vertica-specific projection analysis and optimization recommendations

• get_schema_views - List all views in a schema with their definitions

Performance Analysis

• profile_query - Query execution plans, performance metrics, and optimization suggestions

• analyze_system_performance - Real-time resource monitoring and system health metrics

• database_status - Comprehensive health metrics including storage usage and connection statistics

AI-Powered Prompts

• SQL Safety Guard - Prevents accidental large queries and suggests safer alternatives

• Performance Analyzer - Deep query optimization analysis with specific recommendations

• SQL Assistant - Intelligent query generation based on natural language descriptions

• Health Dashboard - Visual database insights with key performance indicators

• System Monitor - Real-time performance tracking with alerting capabilities

Security Features

• Multi-Level Permissions: Global and schema-specific access controls with fine-grained operation restrictions

• SSL/TLS Encryption: Secure database connections with certificate validation

• Connection Pooling: Efficient resource management with configurable limits and automatic cleanup

• Read-Only Mode: Default safe configuration for production environments

• OAuth Support: Enterprise authentication integration for remote deployments

Documentation

Configuration

Client Integration

Claude Desktop (STDIO) — Installed Package in a Virtual Environment [Recommended]

This is the best practice approach using a dedicated Python virtual environment and the installed package for maximum stability and isolation.

To install the package and create/configure your .env, follow Method 2: PyPI Installation above.

1. Locate the Claude configuration file

   • Windows: %APPDATA%/Claude/claude_desktop_config.json

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Configure Claude to use your virtual environment executable and configuration

   • Replace the command path with your virtual environment path

   • Keep --transport stdio and --env-file with absolute path for reliability

Windows Configuration Example

macOS/Linux Configuration Example

Verification Test (outside Claude)

Test your configuration before integrating with Claude:

Important Configuration Notes

• --transport stdio runs the server over STDIO (no network ports required)

• --env-file ensures your credentials load correctly even if Claude's working directory differs

• Use absolute paths to avoid path resolution issues

3. Development Alternative: From Source (uv)

This option is suitable for development when you want to work with the source code directly:

4. Docker Configuration Options

Option A — Docker Compose (recommended for containerized environments)

Option B — Direct

5. Remote Transport Configuration (HTTP/SSE) via

For remote deployments or when you prefer HTTP-based communication:

3. Enable MCP in VS Code Settings Add these settings to your VS Code configuration:

1. Create MCP Configuration File Create mcp.json in your Cursor configuration directory:

   • Global Configuration: ~/.cursor/mcp.json (macOS/Linux) or %UserProfile%\.cursor\mcp.json (Windows)

   • Per Project Configuration: <project>/.cursor/mcp.json

2. Restart Cursor IDE Completely restart Cursor and check the Available Tools section to verify the integration is working.

CLI Reference

Usage Examples

Natural Language Queries

Basic Database Operations

Performance Analysis and Monitoring

Complex Analytics Queries

Database Management Tasks

Transport Options

Testing & Validation

Quick Health Check

Verify your database connection and server configuration with this simple test:

MCP Inspector Testing

The MCP Inspector provides comprehensive testing and validation capabilities:

MCP Inspector Configuration:

Set the Transport Type to match your server configuration:

• STDIO Transport Testing

  • Command: uv

  • Arguments: run --with mcp --with starlette --with uvicorn --with pydantic --with vertica-python mcp run vertica_mcp/server.py

• SSE Transport Testing

  • URL: http://localhost:8000/sse

• HTTP Transport Testing

  • URL: http://localhost:8000/mcp

API Endpoint Validation

Test your HTTP server endpoints directly with curl commands:

Advanced Features

Performance Optimization

The server automatically profiles queries and provides comprehensive optimization recommendations:

Automatic Query Analysis:

• Execution plan analysis with detailed step-by-step breakdown

• Join strategy recommendations based on table statistics

• Projection optimization suggestions for improved performance

• ROS container health monitoring and segmentation analysis

Example Usage:

Key Features:

• Real-time performance metrics during query execution

• Historical performance comparison

• Automatic detection of inefficient patterns

• Specific recommendations for index creation and query rewriting

Enterprise Integration

Ensure your production deployment meets enterprise standards:

Security Configuration:

• Configure SSL/TLS for all database connections

• Set appropriate connection pool limits based on workload

• Enable read-only mode for production environments

• Configure schema-specific permissions for different user roles

• Implement proper authentication mechanisms

Monitoring and Maintenance:

• Set up comprehensive monitoring and alerting systems

• Implement rate limiting to prevent resource exhaustion

• Configure log rotation and retention policies

• Set up backup MCP servers for high availability

• Establish disaster recovery procedures

Performance Optimization:

• Tune connection pool parameters for your workload

• Configure appropriate query timeouts

• Set up caching strategies for frequently accessed data

• Monitor and optimize resource usage patterns

Security Configuration

Permission Management Levels

The Vertica MCP Server implements a comprehensive three-tier permission system:

1. Global Permissions: Control operations across all schemas and tables

2. Schema-specific Permissions: Fine-grained control per individual schema

3. Connection Security: SSL/TLS encryption and authentication options

Security Best Practices

Database Access Security:

• Use read-only credentials for production deployments to minimize risk

• Enable SSL/TLS encryption for all database connections

• Implement least-privilege access with minimal required permissions

• Use environment variables instead of hardcoded credentials

Network and Infrastructure Security:

• Restrict network access using firewall rules and security groups

• Monitor access logs for suspicious activity and unauthorized attempts

• Implement connection rate limiting to prevent abuse

• Regular security audits of configuration and access patterns

Operational Security:

• Regular credential rotation following your organization's security policies

• Audit trail maintenance for all database operations

• Secure backup procedures for configuration and credentials

• Incident response procedures for security events

Troubleshooting

Common Issues and Solutions

Database Connection Problems

Test Basic Connectivity:

Common Connection Issues:

• Network connectivity: Verify firewall rules and network routing

• Authentication failures: Check username, password, and database permissions

• SSL configuration: Ensure SSL settings match server requirements

• Connection pool exhaustion: Monitor and adjust connection limits

MCP Client Integration Issues

Troubleshooting Steps:

1. Complete client restart: Fully restart the client application (Claude Desktop, VS Code, etc.)

2. Configuration validation: Verify JSON syntax in all configuration files

3. Server log analysis: Check server logs using -vvv verbose flag

4. Isolation testing: Test with MCP Inspector before client integration

Common Configuration Problems:

• Incorrect file paths in configuration

• Missing environment variables

• Port conflicts with other services

• Permission issues with executable files

Docker Deployment Issues

Container Troubleshooting:

Common Docker Issues:

• Environment file not properly mounted

• Port mapping conflicts

• Network connectivity between containers

• Volume mounting permission problems

Debug Mode and Logging

Enable Maximum Verbosity:

Log Analysis Tips:

• Look for connection establishment messages

• Check for permission denial errors

• Monitor query execution timestamps

• Identify resource exhaustion warnings

Project Structure

Contributing

We welcome and encourage contributions from the community! Please see our Contributing Guide for detailed information on how to get involved.

Development Environment Setup

Set up your local development environment with these steps:

Adding New Tools and Features

When implementing new tools, follow these guidelines:

1. Tool Function Implementation: Add tool functions in server.py with proper @mcp.tool() decorator and comprehensive docstrings

2. Permission Management: Implement appropriate permission checks using the connection manager

3. Error Handling: Add comprehensive error handling with informative error messages and proper logging

4. Testing: Write unit tests and integration tests for new functionality

5. Documentation: Update documentation including README, docstrings, and usage examples

Contribution Guidelines

Getting Started with Contributions:

1. Fork the repository and create your feature branch from main

2. Create a feature branch with a descriptive name: git checkout -b feature/AmazingFeature

3. Make your changes following the existing code style and conventions

4. Add tests for any new functionality to ensure reliability

5. Update documentation as needed for new features or changes

6. Commit your changes with clear, descriptive messages: git commit -m 'Add some AmazingFeature'

7. Push to your branch: git push origin feature/AmazingFeature

8. Open a Pull Request with a detailed description of your changes

Code Quality Standards:

• Follow existing code style and formatting conventions

• Include comprehensive type hints for all functions

• Write clear, descriptive commit messages

• Ensure all tests pass before submitting pull requests

• Update documentation for any user-facing changes

Community & Support

Getting Help and Support

• GitHub Issues - Report bugs and request new features

• Discussions - Ask questions and get community support

• Discord - Real-time chat with the community and maintainers

• Stack Overflow - Technical questions and answers

Community Guidelines

When seeking help or contributing:

• Search existing issues and discussions before creating new ones

• Provide detailed information about your environment and configuration

• Include relevant error messages and log outputs

• Be respectful and constructive in all interactions

• Help others when you can share your knowledge and experience

Resources

Official Documentation and References

• MCP Specification - Complete protocol standard and implementation guidelines

• Vertica Documentation - Comprehensive database reference and best practices

• FastMCP Framework - Server framework documentation and examples

• Claude Desktop Guide - Client setup and configuration instructions

Learning Resources

Understanding MCP:

• Model Context Protocol introduction and concepts

• Best practices for MCP server development

• Security considerations for AI integrations

Vertica Integration:

• Database optimization techniques

• Performance tuning for analytics workloads

• Advanced query optimization strategies

AI and Database Integration:

• Natural language to SQL conversion techniques

• Database security in AI applications

• Performance monitoring for AI-driven queries

Changelog

Version 0.1.0 (2025-08-20) - Initial Release

Core Features Implemented:

• 11 comprehensive database tools for complete database interaction

• 5 AI-optimized prompts for enhanced user experience

• Support for STDIO, HTTP, and SSE transport protocols

• Docker support with complete compose configurations

• Enterprise-grade security features and permission management

Key Capabilities:

• Full schema exploration and metadata access

• Query execution with safety guards and optimization

• Real-time performance monitoring and analysis

• Comprehensive error handling and logging

• Production-ready deployment options

Technical Achievements:

• Connection pooling for optimal resource management

• Automatic query optimization and suggestion engine

• Multi-transport support for flexible deployment scenarios

• Comprehensive testing suite and validation tools

For complete version history and detailed changes, see CHANGELOG.md

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for complete terms and conditions.

License Summary:

• Commercial and non-commercial use permitted

• Modification and distribution allowed

• Patent protection included

• Warranty and liability disclaimers apply

Acknowledgments

This project builds upon mcp-vertica
by @nolleh.

While the original implementation provided a foundation for Vertica MCP support,
this fork introduces significant enhancements, including:

• Caching layers and query result reuse

• Rate limiting and throttling control

• Improved error handling and retry logic

• More advanced parsing and schema extraction

• Connection pooling optimizations and performance tuning

• New tooling and prompt injections tailored to Vertica workflows

Project Recognition

Core Technologies:

• Anthropic for creating and maintaining the Model Context Protocol standard

• Vertica for providing the powerful analytics platform that makes this integration possible

• FastMCP for the excellent framework that simplified server development