# grafana/grafana-mcp-agent-datasource architecture

> Architecture diagram of the GitHub repository grafana/grafana-mcp-agent-datasource, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/grafana/grafana-mcp-agent-datasource
- Repository: https://github.com/grafana/grafana-mcp-agent-datasource

## Overview

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: [`pkg/agent/agent.go`](https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/pkg/agent/agent.go) (Agent orchestrator), [`pkg/plugin/datasource.go`](https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/pkg/plugin/datasource.go) (Backend datasource), [`src/components/ConfigEditor.tsx`](https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/src/components/ConfigEditor.tsx) (Config editor), [`src/components/QueryEditor.tsx`](https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/src/components/QueryEditor.tsx) (Query editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend plugin"]
  node_src_module["Plugin module<br/>grafana entry<br/>[module.ts]"]
  node_src_datasource["Datasource client<br/>grafana datasource<br/>[datasource.ts]"]
  node_src_config_editor["Config editor<br/>react UI<br/>[ConfigEditor.tsx]"]
  node_src_query_editor["Query editor<br/>react UI<br/>[QueryEditor.tsx]"]
  node_src_types["UI types<br/>ts models<br/>[types.ts]"]
end

subgraph group_backend["Backend plugin"]
  node_pkg_main["Plugin main<br/>go entrypoint<br/>[main.go]"]
  node_pkg_datasource["Backend datasource<br/>go plugin<br/>[datasource.go]"]
  node_pkg_agent["Agent orchestrator<br/>go agent<br/>[agent.go]"]
  node_pkg_openai["OpenAI provider<br/>llm adapter<br/>[openai_provider.go]"]
  node_pkg_anthropic["Anthropic provider<br/>llm adapter"]
  node_pkg_mock["Mock provider<br/>test adapter<br/>[mock_provider.go]"]
end

subgraph group_integration["Integration"]
  node_pkg_settings["Shared settings<br/>go models<br/>[settings.go]"]
  node_provisioning["Provisioning<br/>grafana config<br/>[datasources.yml]"]
  node_mcp_server[("MCP servers<br/>external service")]
  node_llm_apis[("LLM APIs<br/>external api")]
end

subgraph group_tooling["Tooling"]
  node_build_config["Build config<br/>tooling"]
  node_tests["Tests<br/>test suites"]
end

node_src_module -->|"registers"| node_src_datasource
node_src_datasource -->|"uses"| node_src_types
node_src_config_editor -->|"edits"| node_src_types
node_src_query_editor -->|"edits"| node_src_types
node_pkg_main -->|"starts"| node_pkg_datasource
node_pkg_datasource -->|"reads"| node_pkg_settings
node_pkg_datasource -->|"delegates"| node_pkg_agent
node_pkg_agent -->|"calls"| node_mcp_server
node_pkg_agent -->|"can use"| node_pkg_openai
node_pkg_agent -->|"can use"| node_pkg_anthropic
node_pkg_agent -->|"can swap"| node_pkg_mock
node_pkg_openai -->|"requests"| node_llm_apis
node_pkg_anthropic -->|"requests"| node_llm_apis
node_src_config_editor -->|"matches"| node_pkg_settings
node_src_query_editor -->|"submits"| node_pkg_datasource
node_provisioning -->|"preconfigures"| node_pkg_settings
node_build_config -->|"bundles"| node_src_module
node_build_config -->|"builds"| node_pkg_main
node_tests -->|"covers"| node_src_config_editor
node_tests -->|"covers"| node_src_query_editor
node_tests -->|"covers"| node_pkg_datasource
node_tests -->|"covers"| node_pkg_agent

click node_src_module "https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/src/module.ts"
click node_src_datasource "https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/src/datasource.ts"
click node_src_config_editor "https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/src/components/ConfigEditor.tsx"
click node_src_query_editor "https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/src/components/QueryEditor.tsx"
click node_src_types "https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/src/types.ts"
click node_pkg_main "https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/pkg/main.go"
click node_pkg_datasource "https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/pkg/plugin/datasource.go"
click node_pkg_agent "https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/pkg/agent/agent.go"
click node_pkg_openai "https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/pkg/agent/openai_provider.go"
click node_pkg_anthropic "https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/pkg/agent/anthropic_provider.go"
click node_pkg_mock "https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/pkg/agent/mock_provider.go"
click node_pkg_settings "https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/pkg/models/settings.go"
click node_provisioning "https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/provisioning/datasources/datasources.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_module,node_src_datasource,node_src_config_editor,node_src_query_editor,node_src_types toneBlue
class node_pkg_main,node_pkg_datasource,node_pkg_agent,node_pkg_openai,node_pkg_anthropic,node_pkg_mock toneAmber
class node_pkg_settings,node_provisioning,node_mcp_server,node_llm_apis toneMint
class node_build_config,node_tests toneRose
```

## Components

### Frontend plugin

Grafana-side TypeScript/React datasource plugin and UI.

- [Plugin module](https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/src/module.ts): grafana entry · Registers the datasource plugin with Grafana. · `src/module.ts`
- [Datasource client](https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/src/datasource.ts): grafana datasource · Frontend datasource implementation and request serialization. · `src/datasource.ts`
- [Config editor](https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/src/components/ConfigEditor.tsx): react UI · Datasource configuration form in Grafana. · `src/components/ConfigEditor.tsx`
- [Query editor](https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/src/components/QueryEditor.tsx): react UI · Query authoring UI for Grafana panels. · `src/components/QueryEditor.tsx`
- [UI types](https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/src/types.ts): ts models · Frontend query and settings types. · `src/types.ts`

### Backend plugin

Go plugin runtime that executes queries and talks to MCP.

- [Plugin main](https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/pkg/main.go): go entrypoint · Bootstraps the Grafana backend plugin process. · `pkg/main.go`
- [Backend datasource](https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/pkg/plugin/datasource.go): go plugin · Implements query execution, health checks, and Grafana request handling. · `pkg/plugin/datasource.go`
- [Agent orchestrator](https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/pkg/agent/agent.go): go agent · Coordinates MCP access and natural-language routing. · `pkg/agent/agent.go`
- [OpenAI provider](https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/pkg/agent/openai_provider.go): llm adapter · LLM-backed provider for natural-language handling. · `pkg/agent/openai_provider.go`
- [Anthropic provider](https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/pkg/agent/anthropic_provider.go): llm adapter · Alternative LLM-backed provider for natural-language handling. · `pkg/agent/anthropic_provider.go`
- [Mock provider](https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/pkg/agent/mock_provider.go): test adapter · Mock provider for tests and local development. · `pkg/agent/mock_provider.go`

### Integration

Cross-boundary protocols, shared models, and deployment wiring.

- [Shared settings](https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/pkg/models/settings.go): go models · Datasource settings and connection/auth options shared with the UI. · `pkg/models/settings.go`
- [Provisioning](https://github.com/grafana/grafana-mcp-agent-datasource/blob/main/provisioning/datasources/datasources.yml): grafana config · Managed datasource provisioning for preconfigured environments. · `provisioning/datasources/datasources.yml`
- **MCP servers**: external service · External MCP endpoints reached through the MCP client library.
- **LLM APIs**: external api · Provider APIs used for natural-language orchestration.

### Tooling

Build, container, and test scaffolding.

- **Build config**: tooling · Frontend bundling, Go module, and container build setup.
- **Tests**: test suites · Frontend Playwright/Jest and backend Go tests.

## Connections

- 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.
