VictoriaTraces MCP Server: Distributed Tracing APIs

Overview

The VictoriaTraces MCP Server connects VictoriaTraces APIs to an MCP (Model Context Protocol) server layer so developer tools, automation agents, and LLM-based integrations can discover and call distributed-tracing endpoints in a consistent way. It acts as a lightweight adapter that exposes documentation (OpenAPI/mcp metadata) and proxy endpoints for common VictoriaTraces operations—such as searching traces, examining spans, and inspecting service/topology data—so tracing data can be used by chatbots, debugging assistants, and CI/CD automation.

For developers new to the project, the server is intended to be deployed alongside your VictoriaTraces instance (or pointed at an existing remote instance). It provides a small set of configuration options (endpoint, credentials, TLS) and an MCP manifest/OpenAPI surface so tooling can automatically read the API schema and invoke tracing APIs for diagnostics, root-cause analysis, and observability workflows.

Features

• Exposes VictoriaTraces API surface via an MCP-compatible server manifest
• Serves OpenAPI/Swagger documentation for automated tooling and UIs
• Proxies requests to a configured VictoriaTraces backend with optional authentication
• Lightweight, easy to run as a container or binary
• Configurable TLS and access controls for secure integration
• Example cURL/agent-friendly endpoints for retrieving traces, spans, services, and topology data

Installation / Configuration

Prerequisites: Go 1.18+ (if building from source), Docker (optional).

Clone and build from source:

git clone https://github.com/VictoriaMetrics-Community/mcp-victoriatraces.git
cd mcp-victoriatraces
# build the server binary (path may vary depending on repo layout)
go build -o mcp-victoriatraces ./cmd/mcp-victoriatraces
./mcp-victoriatraces --config ./config.yml

Run with Docker (build and run):

# Build local image
docker build -t mcp-victoriatraces:latest .

# Run container, pointing at your VictoriaTraces instance
docker run -d \
  -e VTRACES_URL="http://victoriatraces.local:8080" \
  -e PORT=8080 \
  -e LOG_LEVEL=info \
  -p 8080:8080 \
  mcp-victoriatraces:latest

Example YAML configuration (config.yml):

server:
  port: 8080
  tls: false

victoriatraces:
  url: "http://victoriatraces.local:8080"
  api_key: ""         # optional
  timeout_seconds: 30

access:
  allowed_origins:
    - "http://localhost:3000"

Environment variables supported (examples): VTRACES_URL, PORT, LOG_LEVEL, VTRACES_API_KEY.

MCP manifest (mcp.json) example for discovery by LLM tools:

{
  "name": "victoriatraces-mcp",
  "version": "0.1.0",
  "description": "MCP wrapper for VictoriaTraces APIs",
  "schema_url": "/openapi.json",
  "entrypoint": "/mcp"
}

Available Resources

The server typically exposes:

• OpenAPI/Swagger specification (e.g. /openapi.json) so tools can introspect available endpoints and models
• MCP manifest (mcp.json) describing the integration for model-based tooling
• Proxy endpoints that forward requests to VictoriaTraces (examples below)
• Static documentation pages generated from API metadata

Typical (example) endpoints you might find after deployment:

Note: Exact paths depend on the configured routing and VictoriaTraces API surface. The server forwards calls to the configured backend endpoint.

Use Cases

1. Troubleshooting slow requests

   • Use the MCP server to fetch recent traces for a service and identify long-duration spans.
   • Example: cURL the proxy to retrieve traces for service “orders” in the last 15 minutes and inspect span durations.

   Example (illustrative):

   curl "http://localhost:8080/api/v1/traces/search?service=orders&lookback=15m&limit=50"
   

2. Correlating errors across services

   • Query traces containing an error flag or a specific exception name, then follow parent/child span relationships to determine impacted upstream services.

3. Integrating with LLM-based assistants

   • An assistant can read the MCP manifest and OpenAPI spec to automatically generate API calls for diagnostic workflows (for example: “show top 10 longest traces in the last hour for service X”).

4. CI/CD pre-deployment checks

   • Automation can call the MCP endpoints to validate that no high-error-rate traces exist for critical services immediately before a blue/green switch.

5. Building dashboards and custom UIs

   • Use the OpenAPI spec for automatic client generation (TypeScript/Go) and fetch spans/traces to populate custom tracing views.

Getting Help and Next Steps

• Start by configuring VTRACES_URL to point at your VictoriaTraces instance and verifying /openapi.json is reachable.
• Use