vv-pilot-mcp

MCP server for accessing QA databases, k8s logs, and Kafka via Amazon Q / Copilot.

Installation

Option 1: uvx (no install required)

Add to your MCP config (~/.aws/amazonq/mcp.json or .amazonq/mcp.json in your workspace):

{
  "mcpServers": {
    "qa-server": {
      "command": "uvx",
      "args": ["vv-pilot-mcp"],
      "timeout": 60000,
      "disabled": false
    }
  }
}

This auto-downloads and runs the server on demand. Requires uv installed.

Option 2: pipx (global install)

pipx install vv-pilot-mcp

Then add to your MCP config:

{
  "mcpServers": {
    "qa-server": {
      "command": "vv-pilot-mcp",
      "timeout": 60000,
      "disabled": false
    }
  }
}

To update later:

pipx upgrade vv-pilot-mcp

First-Time Setup

On first use, the server will prompt you for:

1. SSH password — your jump host password
2. DB jump host — SSH alias for the DB jump host (e.g. qa-psql-1.qa-new)
3. Vault forward host — SSH alias for the vault tunnel (e.g. vault-np-forward-new)

All values are saved securely to ~/.config/qa-mcp/.env (chmod 600) and reused automatically on subsequent sessions.

Usage

Database

1. Open Amazon Q chat and say: "Connect to QA database"
2. The server will:
   • SSH to the DB jump host (opens browser for OIDC approval on first session)
   • Start the vault forward tunnel
   • Open the Vault UI in your browser
3. Copy the vault token from your profile and paste it in chat
4. You're connected! Now ask things like:
   • "List all schemas"
   • "Find the latest visit from retrobranch1"
   • "Update discharge date for visit id 1234"

Kafka

1. Say: "Connect to Kafka"
2. The server will SSH to the Kafka jump host and launch the kafka-utils container
3. Set your client (e.g. "Set client to retrobranch1")
4. Now ask things like:
   • "List all visit topics"
   • "Check connector status for retrobranch1-qa-retrobranch1iodine1-visit"
   • "Consume 5 messages from retrobranch1-qa-visit"
   • "List consumer groups"
   • "Restart the visit connector"

Available Tools

Database

Kubernetes

Kafka

General

Configuration

All config is stored in ~/.config/qa-mcp/.env:

QA_SSH_PASSWORD=<your-password>
QA_DB_JUMP_HOST=qa-psql-1.qa-new
QA_VAULT_JUMP_HOST=vault-np-forward-new
QA_VAULT_URL=https://localhost:18200
QA_VAULT_OIDC_ACCOUNT=you@iodinesoftware.com
QA_DEFAULT_CLUSTER=qa-cluster-1
QA_DEFAULT_DB=iodine
QA_DEFAULT_USER_TYPE=dba

You can also set these as environment variables to override the file.

Prerequisites

• SSH config with aliases for your jump hosts
• Access to the QA environment (OIDC)
• uv (for Option 1) or pipx (for Option 2)

Development

git clone git@github.com:vijayveeramani/vv-pilot-mcp.git
cd vv-pilot-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .

Release Workflow

1. Bump version in pyproject.toml
2. Commit, tag, and push:

   git add -A && git commit -m "v0.x.0: description"
   git tag v0.x.0
   git push origin main --tags
   

3. Build and publish to PyPI:

   rm -rf dist/
   python -m build
   twine upload dist/*