MCP Vega
A Model Context Protocol (MCP) server enabling LLMs to safely inspect PostgreSQL databases and generate Vega-Lite visualizations — built with Java 21, Spring Boot 4, and Spring AI.
Overview
MCP Vega bridges MCP-aware AI clients (Open Web UI, Claude Desktop, Cursor, Continue, autonomous agents) with your PostgreSQL database. It provides an opinionated, read-only toolchain for answering analytical questions and returning immediate, structured charts without exposing data to mutation or exfiltration risks.
Key Guardrails
- Strict AST Validation: Uses JSqlParser to enforce purely read-only
SELECTstatements (blocking multi-statement injection, DDL, and DML). - Transaction-Level Safety: Executes all queries within a read-only transactional boundary (
@Transactional(readOnly = true)). - Hard Row Limits: Enforces a hard cap of 50 rows per query, nudging LLMs toward aggregate bucketing, percentiles, and top-N ranking.
Tools Reference
Database Introspection
Chart Generation
Prerequisites
-
Java 21 (or newer)
-
Maven 3.9+ (or use the bundled
./mvnw) -
A reachable PostgreSQL instance
-
An MCP-aware client (Claude Desktop, etc.)
Configuration
Set your credentials in src/main/resources/application.properties or configure via environment variables:
server.port=8080
spring.datasource.url=jdbc:postgresql://localhost:5432/analytics
spring.datasource.username=your-user-name
spring.datasource.password=secret_password
spring.ai.mcp.server.name=vega-mcp
spring.ai.mcp.server.version=1.0.0
spring.ai.mcp.server.protocol=STREAMABLE
By default the server listens for MCP streamable-HTTP traffic on the configured port (uncomment server.port=8080 in application.properties to set it explicitly).
Switching to stdio transport
If you'd rather run the server as a stdio process — spawned by an MCP client like Claude Desktop — create a sibling config file (e.g. src/main/resources/application-stdio.properties) with all transport settings baked in. No extra command-line flags are needed at launch time.
application-stdio.properties
# --- Activate this profile with --spring.profiles.active=stdio ---
spring.config.activate.on-profile=stdio
# --- Web stack disabled: no HTTP listener, no port 8080 ---
spring.main.web-application-type=none
spring.main.banner-mode=off
# --- MCP transport: stdio (parent process pipes JSON-RPC over stdin/stdout) ---
spring.ai.mcp.server.stdio=true
spring.ai.mcp.server.name=vega-mcp
spring.ai.mcp.server.version=1.0.0
# protocol must stay STREAMABLE for stdio over the Spring AI transport
spring.ai.mcp.server.protocol=STREAMABLE
# --- Keep stdout clean: route all logs to a file ---
logging.file.name=vega-mcp.log
logging.file.path=${user.home}/.mcp-vega/logs
logging.pattern.console=
logging.level.root=INFO
logging.level.com.andrei.mcpvega=INFO
# --- PostgreSQL connection ---
spring.datasource.url=jdbc:postgresql://localhost:5432/analytics
spring.datasource.username=mcp_reader
spring.datasource.password=strong_password
Build & run
# build
./mvnw clean package
# run tests
./mvnw test
# run the server
./mvnw spring-boot:run
# or
java -jar target/mcpvega-0.0.1-SNAPSHOT.jar
Docker
The repository does not ship an
application.properties— it is git-ignored to keep credentials out of source control. You must create your own before starting the container.
1. Build the image
docker build -t mcp-vega:latest .
2. Create the configuration file
Save the following as src/main/resources/application.properties (the standard Spring Boot config location):
server.port=8080
spring.datasource.url=${SPRING_DATASOURCE_URL:jdbc:postgresql://host.docker.internal:5432/analytics}
spring.datasource.username=${SPRING_DATASOURCE_USERNAME:mcp_reader}
spring.datasource.password=${SPRING_DATASOURCE_PASSWORD:strong_password}
spring.ai.mcp.server.name=vega-mcp
spring.ai.mcp.server.version=1.0.0
spring.ai.mcp.server.protocol=STREAMABLE
spring.ai.mcp.server.stdio=false
3. Run the container
The boot jar is built with src/main/resources/ on the classpath, so any application.properties you have locally is baked into the image. You only need environment variables for the values you want to override (typically just the PostgreSQL credentials):
docker run --rm -d \
--name mcp-vega \
-p 8080:8080 \
-e SPRING_DATASOURCE_URL=jdbc:postgresql://host.docker.internal:5432/analytics \
-e SPRING_DATASOURCE_USERNAME=mcp_reader \
-e SPRING_DATASOURCE_PASSWORD=strong_password \
mcp-vega:latest
If you ever want to reconfigure a running container without rebuilding the image, mount a properties file at /app/application.properties — it overrides the one bundled in the jar:
docker run --rm -d \
--name mcp-vega \
-p 8080:8080 \
-v "$(pwd)/src/main/resources/application.properties:/app/application.properties:ro" \
mcp-vega:latest
Your MCP client can then target http://localhost:8080 with transport: streamable-http — see the client configs above.
stdio transport: not recommended in Docker — keeping stdin/stdout attached to a parent MCP client process is fragile. Stick with the streamable-HTTP transport shown above.
Screenshots
Bar chart — monthly sales revenue
Pie chart — order status distribution
Line chart — daily orders over time
Scatter plot — property size vs. sale price
Connecting to AI Clients
Once the server is running on http://localhost:8080 (streamable-HTTP transport), point any MCP-compatible client at it. Below are configs for the most popular clients.
Open Web UI
Open Web UI talks to MCP servers over the streamable-HTTP transport, so you only need the server running locally — no stdio plumbing or extra flags.
-
Make sure the server is up on
http://localhost:8080(the defaultSTREAMABLEconfig fromapplication.propertiesis enough — do not activate thestdioprofile here). -
Open Settings → Integrations → External Tool Servers, and add a new MCP server:
- Name:
vega-mcp - URL:
http://localhost:8080 - Transport:
streamable-http
- Name:
-
Alternatively, edit the Open Web UI data volume's
config.json(~/.open-webui/data/config.jsonin the default Docker setup) and add:
{
"mcp_servers": {
"vega-mcp": {
"url": "http://localhost:8080",
"transport": "streamable-http"
}
}
}
- Restart Open Web UI (if you edited
config.json) and start a new chat. The Vega MCP tools (list-all-tables,describe-table,query-database,generate-vega-lite-chart, …) should appear in the tool picker.
Tip: if you exposed the Spring Boot app on a different host/port (or behind a reverse proxy with TLS), replace
http://localhost:8080with the reachable endpoint and make sure the URL is reachable from the container/host running Open Web UI.
Claude Desktop
Claude Desktop supports MCP servers via claude_desktop_config.json.
Claude Desktop launches the Spring Boot jar as a child process and talks to it over stdin/stdout. No separate server, no open port.
-
Build the boot jar:
./mvnw clean packageThis produces
target/mcpvega-0.0.1-SNAPSHOT.jar. -
Edit
claude_desktop_config.json:
{
"mcpServers": {
"vega-mcp": {
"command": "java",
"args": [
"-jar",
"/absolute/path/to/mcpvega-0.0.1-SNAPSHOT.jar",
"--spring.profiles.active=stdio"
]
}
}
}
On Windows, use:
{
"mcpServers": {
"vega-mcp": {
"command": "C:\\Program Files\\Java\\jdk-21\\bin\\java.exe",
"args": [
"-jar",
"C:\\absolute\\path\\to\\mcpvega-0.0.1-SNAPSHOT.jar",
"--spring.profiles.active=stdio"
]
}
}
}
Tip: the
-D...flags can be replaced with environment variables in theenvblock to keep credentials out of the config file:{ "mcpServers": { "vega-mcp": { "command": "java", "args": ["-Dspring.ai.mcp.server.stdio=true", "-Dspring.main.web-application-type=none", "-jar", "/abs/path/to/mcpvega-0.0.1-SNAPSHOT.jar"], "env": { "SPRING_DATASOURCE_URL": "jdbc:postgresql://localhost:5432/analytics", "SPRING_DATASOURCE_USERNAME": "mcp_reader", "SPRING_DATASOURCE_PASSWORD": "strong_password" } } } }
Cursor
Add to ~/.cursor/mcp.json (or use Settings → Features → Model Context Protocol → Add new global MCP server):
{
"mcpServers": {
"vega-mcp": {
"url": "http://localhost:8080"
}
}
}
Restart Cursor, then enable vega-mcp from the MCP servers panel. Tools are callable via @vega-mcp in the composer.
VS Code (Copilot Chat / MCP extension)
Add to .vscode/mcp.json in your workspace, or to your user settings.json:
{
"servers": {
"vega-mcp": {
"type": "http",
"url": "http://localhost:8080"
}
}
}
For the GitHub Copilot Chat MCP extension, the equivalent block lives under mcp.servers in settings.json.
Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"vega-mcp": {
"url": "http://localhost:8080"
}
}
}
Cline (VS Code)
In the Cline panel, click MCP Servers → Edit MCP Settings, then add:
{
"mcpServers": {
"vega-mcp": {
"url": "http://localhost:8080",
"disabled": false
}
}
}
Security Best Practices
- Principle of Least Privilege: Always point MCP Vega to a dedicated read-only database user:
CREATE USER mcp_reader WITH PASSWORD 'strong_password';
GRANT CONNECT ON DATABASE analytics TO mcp_reader;
GRANT USAGE ON SCHEMA public TO mcp_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_reader;
- Network Isolation: Keep the MCP server inside your private VPC/network; avoid exposing port
8080to the public internet without an authenticating reverse proxy. - Data Anonymization: Use database views to mask PII (emails, names, billing details) before exposing schemas to LLM tools.
License
Distributed under the Apache License, Version 2.0. See LICENSE.md for more information.