MCP Server (Experimental)

The vvctlCLI includes a built-in Model Context Protocol (MCP) server that lets AI coding assistants manage your Ververica Cloud infrastructure directly. The server enables Large Language Models (LLMs) to interact with Managed Service, Self-Managed, and BYOC deployment options through the creation and management of deployments and SQL scripts.

All MCP traffic uses local stdio (vvctl mcp start), so no extra ports are opened.

Key Features

• SQL script drafts management
• Deployment management for Java, Python, and SQL
• Artifact management
• Secrets management
• Deployment logs for debugging
• Script executions
• Context management

Architecture

The MCP server communicates over stdio — the AI assistant spawns vvctl mcp start as a subprocess, sends JSON-RPC requests to stdin, and reads responses from stdout. No network server is required.

1AI Assistant  ←── stdio (stdin/stdout) ──→  vvctl mcp start
2                                                │
3                                                ├── Settings (config/contexts/users/servers)
4                                                └── Ververica Cloud REST API

Protocol: MCP v2024-11-05

Prerequisites

Before configuring the MCP server:

• vvctl installed and on your PATH. See the installation guide.
• An active Ververica Cloud account with an API token or email/password credentials.
• An existing vvctl configuration. Run vvctl login at least once before starting the MCP server.

Get Started

To use the MCP server, configure it in your AI client using the vvctl mcp start command.

Standard Configuration

This configuration works in most MCP clients:

1{
2  "mcpServers": {
3    "ververica": {
4      "command": "vvctl",
5      "args": ["mcp", "start"]
6    }
7  }
8}

See the per-client instructions below for specific setup steps.

Amp

Add the server through the Amp VS Code extension Settings screen or by updating your settings.json file:

1"amp.mcpServers": {
2  "ververica": {
3    "command": "vvctl",
4    "args": ["mcp", "start"]
5  }
6}

Amp CLI

Add the server using the amp mcp add command:

1amp mcp add ververica -- vvctl mcp start

Claude Code

Add the MCP server to your project or global settings:

1# Project-scoped (recommended)
2claude mcp add ververica -- vvctl mcp start
3
4# Global (available in all projects)
5claude mcp add --scope user ververica -- vvctl mcp start

Or add it manually to .claude/settings.json or ~/.claude/settings.json:

1{
2  "mcpServers": {
3    "ververica": {
4      "command": "vvctl",
5      "args": ["mcp", "start"]
6    }
7  }
8}

Claude Desktop

Follow the MCP installation guide and use the standard configuration provided above.

Cline

Follow the instructions in Configuring MCP Servers.

Add the following to your cline_mcp_settings.json (https://docs.cline.bot/mcp/configuring-mcp-servers#editing-mcp-settings-files) file:

1{
2  "mcpServers": {
3    "ververica": {
4      "type": "stdio",
5      "command": "vvctl",
6      "timeout": 30,
7      "args": ["mcp", "start"],
8      "disabled": false
9    }
10  }
11}

Codex

Use the Codex CLI to add the MCP server:

1codex mcp add ververica vvctl mcp start

Or create or edit ~/.codex/config.toml and add:

1[mcp_servers.ververica]
2command = "vvctl"
3args = ["mcp", "start"]

For more information, see the Codex MCP documentation.

Copilot

Use the Copilot CLI to interactively add the MCP server:

1/mcp add

Or create or edit ~/.copilot/mcp-config.json and add:

1{
2  "mcpServers": {
3    "ververica": {
4      "type": "local",
5      "command": "vvctl",
6      "tools": ["*"],
7      "args": ["mcp", "start"]
8    }
9  }
10}

For more information, see the Copilot CLI documentation.

Cursor

1. Go to Cursor Settings > MCP > Add new MCP Server.

1. Enter a name for the server.

1. Select the command type.

1. Enter the command vvctl mcp start.

You can also verify the configuration or add command-line arguments by clicking Edit.

Alternatively, edit .cursor/mcp.json in your project root:

1{
2  "mcpServers": {
3    "ververica": {
4      "command": "vvctl",
5      "args": ["mcp", "start"]
6    }
7  }
8}

Factory

Use the Factory CLI to add the MCP server:

1droid mcp add ververica "vvctl mcp start"

Or type /mcp within Factory Droid to open an interactive UI for managing MCP servers.

For more information, see the Factory MCP documentation.

Gemini CLI

Follow the MCP installation guide and use the standard configuration provided above.

Goose

1. Go to Advanced settings > Extensions > Add custom extension.

1. Enter a name for the extension.

1. Select the STDIO type.

1. Set the command to vvctl mcp start.

1. Click Add Extension.

Kiro

Follow the Kiro MCP documentation. For example, add the following to .kiro/settings/mcp.json:

1{
2  "mcpServers": {
3    "ververica": {
4      "command": "vvctl",
5      "args": ["mcp", "start"]
6    }
7  }
8}

LM Studio

1. Go to Program in the right sidebar.

1. Select Install > Edit mcp.json.

1. Use the standard configuration provided above.

opencode

Follow the MCP Servers documentation. For example, add the following to ~/.config/opencode/opencode.json:

1{
2  "$schema": "https://opencode.ai/config.json",
3  "mcp": {
4    "ververica": {
5      "type": "local",
6      "command": ["vvctl", "mcp", "start"],
7      "enabled": true
8    }
9  }
10}

Qodo Gen

1. Open the Qodo Gen chat panel in VS Code or IntelliJ.

1. Select Connect more tools > + Add new MCP.

1. Paste the standard configuration provided above.

1. Click Save.

VS Code

Follow the MCP installation guide and use the standard configuration provided above.

You can also install the MCP server using the VS Code CLI:

1code --add-mcp '{"name":"ververica","command":"vvctl","args":["mcp","start"]}'

After installation, the MCP server is available for use with GitHub Copilot in VS Code.

Warp

1. Go to Settings > AI > Manage MCP Servers > + Add.

1. Use the standard configuration provided above.

Or use the slash command /add-mcpin the Warp prompt and paste the standard configuration. For more information, see adding an MCP server.

Windsurf

Follow the Windsurf MCP documentation and use the standard configuration provided above.

Verify the Connection

Once configured, ask your AI assistant:

"List my Ververica workspaces"

The assistant should call the list_workspaces tool and return your workspace list. If authentication fails, ask it to run login with your credentials or API token first.

Authentication

The MCP server includes tools to manage contexts, letting the LLM switch between workspaces or accounts. This is useful when working across multiple environments.

For initial authentication, the MCP server supports API token and email/password login through the login tool. You can also pass credentials using the VV_API_TOKEN, VV_EMAIL, and VV_PASSWORD environment variables.

Tool Reference

The MCP server exposes 66 tools across 12 domains.

Account

login parameters

Provide either token alone, or email and password.

Workspaces

list_engines requires a workspace parameter (workspace ID).

Deployments

create_sql_deployment parameters

Provide one of draft, file, or query.

stop_deployment parameters

Drafts

create_draft parameters

Provide either path or query.

validate_draft parameters

Returns: Validation result with valid flag and message.

Jobs

list_jobs parameters

Task Managers

Use list_task_managers first to discover taskmanager_id values needed by log tools.

Logs

The log tools cover both running and stopped (archived) deployments. For running deployments, use the live log tools. For stopped deployments, list the archived logs first, then fetch their contents.

Running deployment logs

Archived logs (stopped deployments)

Artifacts

Secrets

Resource Queues

Agents

Configuration

These tools manage the local vvctl configuration file, which stores servers, users, and contexts (similar to kubectl config).

Common Workflows

Investigate a Failed Deployment

1User: "My deployment abc123 in workspace ws-456 failed. What happened?"

The AI assistant will typically:

1. get_deployment(workspace="ws-456", deployment_id="abc123")
2. list_jobs(workspace="ws-456", deployment_id="abc123", status="FAILED")
3. get_startup_log(workspace="ws-456", deployment_id="abc123")
4. get_jobmanager_log(workspace="ws-456", job_id="<from step 2>")

Check Logs for a Running Deployment

1User: "Show me the logs for deployment abc123"

The AI assistant will typically:

1. list_jobs(workspace="ws-456", deployment_id="abc123", status="RUNNING")
2. get_jobmanager_log(workspace="ws-456", job_id="<job_id>")
3. list_task_managers(workspace="ws-456", job_id="<job_id>")
4. get_taskmanager_log(workspace="ws-456", job_id="<job_id>", taskmanager_id="<tm_id>")

Review Logs for a Stopped Deployment

1User: "Get me the logs from the last run of deployment abc123"

The AI assistant will typically:

1. list_jobs(workspace="ws-456", deployment_id="abc123")
2. list_archived_jobmanager_logs(workspace="ws-456", job_id="<job_id>")
3. get_archived_jobmanager_log(workspace="ws-456", job_id="<job_id>", log_name="<name>")
4. list_archived_taskmanagers(workspace="ws-456", job_id="<job_id>")
5. list_archived_taskmanager_logs(workspace="ws-456", job_id="<job_id>", taskmanager_id="<tm_id>")
6. get_archived_taskmanager_log(...)

Deploy a SQL Query

1User: "Deploy this SQL to workspace ws-456: SELECT * FROM orders WHERE amount > 100"

The AI assistant will use one of these approaches:

Option A — Direct deployment:

1. create_sql_deployment(workspace="ws-456", query="SELECT * FROM orders WHERE amount > 100")

Option B — Draft, validate, then execute:

1. create_draft(workspace="ws-456", name="orders-filter", query="...")
2. validate_draft(workspace="ws-456", draft="<draft_id>")
3. execute_draft(workspace="ws-456", draft="<draft_id>")

Set Up a New Context

1User: "Configure vvctl for our production environment"

The AI assistant will typically:

1. set_server(name="prod", host="https://api.ververica.com")
2. set_user(name="prod-user", token="<token>")
3. set_context(name="production", server="prod", user="prod-user")
4. use_context(name="production")

Tool Summary