StarRocks MCP Server Interaction Guide

Overview

The StarRocks MCP (Model Context Protocol) Server is a middleware service that exposes management, query, and monitoring capabilities for StarRocks clusters via a unified API. It lets developer tools and automation systems interact programmatically with StarRocks: submitting SQL, retrieving query status and results, managing cluster lifecycle operations (scaling, health checks), and collecting performance metrics for observability pipelines.

This guide walks new developers through installing and configuring the MCP server, explains available resources (REST endpoints, CLI, Prometheus metrics), and provides practical examples for common tasks like running queries and monitoring performance. The examples assume a standard deployment (local Docker or binary) and show typical HTTP requests and sample configuration snippets you can adapt to CI/CD or operator tooling.

Features

• HTTP REST API for submitting SQL queries and managing cluster operations
• Query lifecycle management: submit, poll status, fetch results
• Cluster management endpoints: health, topology, scaling actions
• Metrics and observability: Prometheus-compatible /metrics endpoint
• Token/API-key based authentication and configurable TLS
• Lightweight CLI and simple SDK-friendly JSON API for integration

Installation / Configuration

Prerequisites:

• Docker (recommended for local testing) or Go 1.18+ to build from source
• Network access to your StarRocks FE/BE nodes

Clone and run with Docker (quickstart)

git clone https://github.com/StarRocks/mcp-server-starrocks.git
cd mcp-server-starrocks
docker build -t starrocks-mcp .
docker run -d --name starrocks-mcp \
  -p 8080:8080 \
  -e MCP_API_KEY="replace-with-secret" \
  -e STARROCKS_FE="fe-host:8030" \
  -e STARROCKS_USER="admin" \
  -e STARROCKS_PASSWORD="password" \
  starrocks-mcp

Build and run from source

git clone https://github.com/StarRocks/mcp-server-starrocks.git
cd mcp-server-starrocks
go build -o mcp-server ./cmd/server
./mcp-server --config ./configs/config.yaml

Example minimal config.yaml

server:
  address: ":8080"
  tls:
    enabled: false

auth:
  api_keys:
    - "replace-with-secret"

starrocks:
  fe_host: "fe-host:8030"
  user: "admin"
  password: "password"

observability:
  prometheus_metrics: true
  metrics_path: "/metrics"

For production, enable TLS and store secrets in a secure vault. The repository includes more complete config examples and a docker-compose file for multi-service setups.

Available Resources

Common REST endpoints (default base: http://localhost:8080)

Authentication

• Use an API key in the Authorization header: Authorization: Bearer <API_KEY>
• TLS endpoints supported when configured

Tools

• REST API (primary integration point)
• Optional lightweight CLI (if included in repo) for quick operations
• Prometheus scraping of /metrics for dashboards and alerts

Use Cases

1. Run a SQL query and poll for results

# Submit a query
curl -s -X POST http://localhost:8080/api/v1/query \
  -H "Authorization: Bearer replace-with-secret" \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT COUNT(*) FROM sales WHERE dt = \"2024-01-01\";","catalog":"default_catalog","timeout_ms":60000}' \
  | jq .

# Response:
# { "query_id": "q_abc123", "status": "running" }

# Poll for completion and fetch results
curl -s -H "Authorization: Bearer replace-with-secret" \
  http://localhost:8080/api/v1/query/q_abc123 | jq .

2. Check cluster health and topology

curl -s -H "Authorization: Bearer replace-with-secret" \
  http://localhost:8080/api/v1/cluster | jq .
# Returns node list, roles (FE/BE), and health flags

3. Integrate with Prometheus for metrics

• Configure Prometheus scrape:

scrape_configs:
  - job_name: 'starrocks_mcp'
    static_configs:
      - targets: ['mcp-host:8080']
    metrics_path: /metrics

• Metrics exposed include query_latencies, active_queries, node_cpu_usage, and connection_errors.

4. Automate scaling (example)

curl -X POST http://localhost:8080/api/v1/cluster/scale \
  -H "Authorization: Bearer replace-with-secret" \
  -H "Content-Type: application/json" \
  -d '{"action":"scale_up","nodes":2}' | jq .

This triggers a configured orchestration hook—actual scaling behavior depends on your deployment hooks (Kubernetes, cloud autoscaler, etc.).

Tips and Next Steps

• Start by deploying locally with Docker and try the query and metrics endpoints.
• Secure API keys and enable TLS in production.
• Wire /metrics to Prometheus and create dashboards (Grafana) for query latency and cluster health.
• Inspect the repo’s examples and configs for advanced features like multi-tenant catalogs, query resource limits, and custom orchestration hooks.

For detailed API schemas and advanced configuration, see the repository README and API documentation in the project source.