How grafana/grafana-mcp-agent-datasource works
1. This repository is a Grafana data source plugin that bridges three boundaries: the Grafana UI, a Go backend plugin runtime, and external MCP servers. The project is archived, with the README pointing users to grafana/mcp-grafana as the successor.
2. The architecture is split cleanly into a frontend plugin and a backend plugin:
- src/ contains the Grafana-side TypeScript/React UI and datasource client.
- pkg/ contains the Go backend that Grafana loads to execute queries and manage server connections.
3. The frontend subsystem is centered on the datasource configuration and query editors:
- src/components/ConfigEditor.tsx handles datasource setup.
- src/components/QueryEditor.tsx handles query authoring.
- src/datasource.ts and src/module.ts wire the plugin into Grafana’s datasource API and define how query objects are serialized.
4. The backend entrypoint is pkg/main.go, which boots the plugin process. The plugin implementation lives in pkg/plugin/, where datasource.go appears to own the Grafana datasource behavior, including query execution, health checks, and translation between Grafana requests and backend operations.
5. The MCP integration is isolated in pkg/agent/. This package contains:
- agent.go for orchestration,
- openai_provider.go and anthropic_provider.go for LLM-backed natural-language handling,
- mock_provider.go for tests and local development.
This suggests the backend can route natural-language requests through a provider before invoking MCP tools or resources.
6. External MCP communication is handled via the mcp-go library, as described in the README. That means the plugin is not implementing the protocol from scratch; instead, it relies on a dedicated MCP client layer for transport and protocol handling, with support for MCP server endpoints over multiple connection styles.
7. Shared configuration and query state are modeled in pkg/models/settings.go and src/types.ts. These files form the contract between the Grafana UI and the backend: datasource settings, connection parameters, auth choices, and query options must line up across both halves of the plugin.
8. The main data flow is:
- a user configures the datasource in Grafana,
- the frontend stores connection and auth settings,
- a query is composed in the query editor,
- Grafana sends the query to the Go backend,
- the backend agent connects to the configured MCP server,
- results are transformed into Grafana-compatible data frames and returned to the dashboard.
9. The plugin supports more than one interaction pattern with MCP servers. The README and code structure indicate at least:
- natural-language querying,
- direct tool invocation,
- tool listing/discovery.
This means the backend likely contains query dispatch logic that selects between “LLM-assisted” and “direct MCP call” paths.
10. Provisioning is supported through provisioning/datasources/datasources.yml, which lets Grafana pre-create the datasource in managed environments. This is a deployment-time concern, separate from the runtime query path.
11. Local development and packaging are supported by container and build tooling:
- docker-compose.yaml and .config/Dockerfile suggest a containerized dev/runtime setup,
- .config/webpack/ and package.json indicate the frontend is bundled separately,
- go.mod and the pkg/ tree define the backend build.
This reflects the plugin’s dual-build nature: JavaScript bundle for Grafana UI, Go binary for the datasource backend.
12. Testing is split along the same boundary:
- tests/*.spec.ts and Playwright/Jest configuration cover frontend behavior,
- pkg/plugin/*_test.go and agent tests cover backend logic.
Mocking is explicitly supported in pkg/agent/mock_provider.go, which is useful for validating query behavior without calling live LLM or MCP services.
13. In diagram terms, the important boundaries are:
- Grafana browser UI ↔ plugin frontend,
- plugin frontend ↔ plugin backend process,
- backend ↔ MCP server over the network,
- optional backend ↔ LLM provider APIs for natural-language orchestration.
The repo is primarily an integration layer across these boundaries, not a standalone application server.
Main entry points: agent.go Agent orchestrator · datasource.go Backend datasource · ConfigEditor.tsx Config editor · QueryEditor.tsx Query editor
Components 17
Frontend plugin
Grafana-side TypeScript/React datasource plugin and UI.
- Plugin module · Registers the datasource plugin with Grafana.
src/module.ts - Datasource client · Frontend datasource implementation and request serialization.
src/datasource.ts - Config editor · Datasource configuration form in Grafana.
src/components/ConfigEditor.tsx - Query editor · Query authoring UI for Grafana panels.
src/components/QueryEditor.tsx - UI types · Frontend query and settings types.
src/types.ts
Backend plugin
Go plugin runtime that executes queries and talks to MCP.
- Plugin main · Bootstraps the Grafana backend plugin process.
pkg/main.go - Backend datasource · Implements query execution, health checks, and Grafana request handling.
pkg/plugin/datasource.go - Agent orchestrator · Coordinates MCP access and natural-language routing.
pkg/agent/agent.go - OpenAI provider · LLM-backed provider for natural-language handling.
pkg/agent/openai_provider.go - Anthropic provider · Alternative LLM-backed provider for natural-language handling.
pkg/agent/anthropic_provider.go - Mock provider · Mock provider for tests and local development.
pkg/agent/mock_provider.go
Integration
Cross-boundary protocols, shared models, and deployment wiring.
- Shared settings · Datasource settings and connection/auth options shared with the UI.
pkg/models/settings.go - Provisioning · Managed datasource provisioning for preconfigured environments.
provisioning/datasources/datasources.yml - MCP servers · External MCP endpoints reached through the MCP client library.
- LLM APIs · Provider APIs used for natural-language orchestration.
Tooling
Build, container, and test scaffolding.
- Build config · Frontend bundling, Go module, and container build setup.
- Tests · Frontend Playwright/Jest and backend Go tests.
Connections 22
- Plugin module → Datasource client: registers · Module wires the datasource implementation into Grafana.
- Datasource client → UI types: uses · Datasource request and settings types are shared with the UI.
- Config editor → UI types: edits · Configuration form populates shared datasource settings.
- Query editor → UI types: edits · Query editor builds typed query state.
- Plugin main → Backend datasource: starts · Main entrypoint launches the plugin implementation.
- Backend datasource → Shared settings: reads · Backend reads datasource settings and connection parameters.
- Backend datasource → Agent orchestrator: delegates · Datasource logic hands query work to the agent layer.
- Agent orchestrator → MCP servers: calls · Agent reaches external MCP servers via the client library.
- Agent orchestrator → OpenAI provider: can use · Agent may route natural-language requests through OpenAI.
- Agent orchestrator → Anthropic provider: can use · Agent may route natural-language requests through Anthropic.
- Agent orchestrator → Mock provider: can swap · Mock provider supports testing and local development.
- OpenAI provider → LLM APIs: requests · OpenAI-backed orchestration depends on external LLM APIs.
- Anthropic provider → LLM APIs: requests · Anthropic-backed orchestration depends on external LLM APIs.
- Config editor → Shared settings: matches · Frontend configuration must align with backend settings schema.
- Query editor → Backend datasource: submits · Grafana query editor sends composed queries to the backend.
- Provisioning → Shared settings: preconfigures · Provisioned datasource values map onto the shared settings model.
- Build config → Plugin module: bundles · Webpack and frontend tooling build the Grafana UI bundle.
- Build config → Plugin main: builds · Go module and container tooling build the backend binary.
- Tests → Config editor: covers · Frontend tests exercise datasource configuration behavior.
- Tests → Query editor: covers · Frontend tests exercise query authoring behavior.
- Tests → Backend datasource: covers · Backend tests validate datasource execution and health logic.
- Tests → Agent orchestrator: covers · Backend tests validate agent routing and provider behavior.