Developer on Grafana Labs

Go SDK (programmatic use)

Thu, 23 Apr 2026 10:03:11 +0200

Go SDK (programmatic use)

You can use the Grafana MCP server as a Go library to build custom MCP server contexts, for example with custom TLS or debug settings. The package is available on pkg.go.dev.

What you’ll achieve

You integrate the server into your own Go program, using ComposedStdioContextFunc and GrafanaConfig (and optionally TLSConfig) so the server runs with your chosen configuration.

Before you begin

A Go toolchain and the module in your project: go get github.com/grafana/mcp-grafana.

Compose a stdio context with config

Create a GrafanaConfig with your Grafana URL, credentials (or token), and options such as Debug. For TLS to Grafana, set TLSConfig with CertFile, KeyFile, and CAFile. Then build the context function with mcpgrafana.ComposedStdioContextFunc(grafanaConfig) and pass it to your MCP server setup so the server uses this context when handling requests.

Example (structure only):

grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug: true,
    TLSConfig: &mcpgrafana.TLSConfig{
        CertFile: "/path/to/client.crt",
        KeyFile:  "/path/to/client.key",
        CAFile:   "/path/to/ca.crt",
    },
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

Refer to the package documentation for the exact types and constructors.

Next steps

Observability (metrics and tracing) for Prometheus and OTLP.
Client TLS (Grafana connection) for TLS flag reference.

Observability (metrics and tracing)

Thu, 23 Apr 2026 10:03:11 +0200

Observability (metrics and tracing)

The MCP server can expose Prometheus metrics and supports OpenTelemetry distributed tracing, following the OTel MCP semantic conventions.

Metrics require the SSE or streamable-http transport. Tracing uses standard OTEL_* environment variables and works independently of --metrics.

What you’ll achieve

You can scrape MCP operation metrics or export traces to Tempo or Grafana Cloud while the server runs over HTTP transports.

Before you begin

The server running with SSE or streamable-http (metrics are not available with stdio).

Enable Prometheus metrics

When using SSE or streamable HTTP transports, enable Prometheus metrics with --metrics:

# Metrics on the main server at /metrics
./mcp-grafana -t streamable-http --metrics

# Metrics on a separate listen address
./mcp-grafana -t streamable-http --metrics --metrics-address :9090

Available metrics:

Metric	Type	Description
`mcp_server_operation_duration_seconds`	Histogram	MCP operation duration (labels: `mcp_method_name`, `gen_ai_tool_name`, `error_type`, `network_transport`, `mcp_protocol_version`)
`mcp_server_session_duration_seconds`	Histogram	MCP client session duration (labels: `network_transport`, `mcp_protocol_version`)
`http_server_request_duration_seconds`	Histogram	HTTP server request duration (from otelhttp)

Note: Metrics are only available when using SSE or streamable HTTP transports. They are not available with stdio transport.

Enable OpenTelemetry tracing

When OTEL_EXPORTER_OTLP_ENDPOINT is set, the server exports traces via OTLP/gRPC.

Local example:

# Send traces to a local Tempo instance
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_EXPORTER_OTLP_INSECURE=true \
./mcp-grafana -t streamable-http

Grafana Cloud example:

# Send traces to Grafana Cloud with authentication
OTEL_EXPORTER_OTLP_ENDPOINT=https://tempo-us-central1.grafana.net:443 \
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ..." \
./mcp-grafana -t streamable-http

Tool call spans follow naming like tools/call <tool_name> and include attributes such as gen_ai.tool.name, mcp.method.name, and mcp.session.id. The server supports W3C trace context propagation from the _meta field of tool call requests.

Run with Docker (metrics and tracing)

docker run --rm -p 8000:8000 \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your token> \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://tempo:4317 \
  -e OTEL_EXPORTER_OTLP_INSECURE=true \
  grafana/mcp-grafana \
  -t streamable-http --metrics

Next steps

Build, test, and lint

Thu, 23 Apr 2026 10:03:11 +0200

Build, test, and lint

Contributions are welcome. Open an issue or pull request on GitHub. This project is written in Go.

What you’ll achieve

You can run the server from source, execute the test suites, and run linters locally.

Before you begin

Go installed for your platform.
Optional: Docker for integration tests.

Run the server locally

STDIO (default for local development):

make run

SSE:

go run ./cmd/mcp-grafana --transport sse

Build and run the Docker image

Build the image:

make build-image

Run in SSE mode (image default):

docker run -it --rm -p 8000:8000 mcp-grafana:latest

Run in stdio mode:

docker run -it --rm mcp-grafana:latest -t stdio

Run tests

There are three types of tests available: unit tests, integration tests, and cloud tests.

Unit tests (no external dependencies required):

make test-unit

You can also run:

make test

Integration tests (requires Docker containers):

make test-integration

Cloud tests (requires Grafana Cloud instance and credentials):

make test-cloud

Note: Cloud tests are automatically configured in CI. For local development, you’ll need to set up your own Grafana Cloud instance and credentials.

For the full integration suite, start the supporting services first (Grafana and its dependencies on port 3000):

make run-test-services
make test-integration

If you add tools, add integration tests; existing tests are a good template.

Run linters

make lint

The repository includes a custom linter for unescaped commas in jsonschema struct tags (description fields must be escaped with \\, to avoid truncation). Run only that linter:

make lint-jsonschema

Refer to the JSONSchema linter README in the repository.