1. 项目定位与目标

mcp-grafana 是一个面向 Grafana 平台的 Model Context Protocol（MCP） 服务器实现。其核心目标是把 Grafana 生态中的资源（仪表盘、告警规则、数据源、事件、Profiling、Provisioning 等）以 工具（Tool） 的形式暴露给符合 MCP 协议的大型语言模型客户端（例如 Claude Desktop、Cursor、Cline 等），让 AI 代理能够以可编程的方式查询、修改并运维 Grafana 实例。

从社区反馈来看，最新版本 v0.15.1 已经引入了 shorten_url、list_provisioning_repositories、validate_provisioning_file 等工具，表明该项目持续在扩展“LLM ↔ Grafana”双向能力。资料来源：v0.15.1 Release Notes

1.1 核心价值主张

2. 系统总体架构

虽然仓库根目录的源码细节不在本次检索范围内，但通过内部 linter 的测试样例，可以反推出项目主要存在 三层结构：

graph TD
    A[LLM 客户端<br/>Claude / Cursor / Cline] -->|MCP JSON-RPC<br/>stdio / SSE / streamable-http| B(MCP-Grafana Server)
    B -->|Tools 注册| C[Tool Registry]
    C --> D1[Datasource Tools<br/>Prometheus / Loki / Tempo / Pyroscope / ES / Influx / Graphite / OpenSearch / Snowflake / Athena / Cloud Monitoring / VictoriaMetrics]
    C --> D2[Dashboard & Panel Tools]
    C --> D3[Alerting & Incident Tools]
    C --> D4[Admin & Provisioning Tools<br/>shorten_url / list_provisioning_repositories / validate_provisioning_file]
    C --> D5[Generic API Request Tool]
    D1 --> E[Grafana HTTP API]
    D2 --> E
    D3 --> E
    D4 --> E
    D5 --> E
    E -->|OpenAPI 生成的 Go 客户端| F[grafana-openapi-client-go]

关键观察：linter 的测试样例明确把 grafana-openapi-client-go 作为项目运行时依赖，证明整个工具层统一通过该 Go 客户端访问 Grafana HTTP API，从而避免散落的手写 net/http 调用。资料来源：internal/linter/openapi/testdata/src/github.com/grafana/grafana-openapi-client-go/client/datasources/fake.go

3. 客户端与 OpenAPI 客户端的约定

internal/linter/openapi/testdata/src/github.com/grafana/grafana-openapi-client-go/client/datasources/fake.go 中定义了 datasources.ClientService 接口。该接口对每个方法都同时暴露了 便利方法 和 WithParams 变体：

type ClientService interface {
    GetDataSources(opts ...ClientOption) (*GetDataSourcesOK, error)
    GetDataSourcesWithParams(params *GetDataSourcesParams, opts ...ClientOption) (*GetDataSourcesOK, error)
    GetDataSourceByUID(uid string, opts ...ClientOption) (*GetDataSourceByUIDOK, error)
    GetDataSourceByUIDWithParams(params *GetDataSourceByUIDParams, opts ...ClientOption) (*GetDataSourceByUIDOK, error)
    // A method with no WithParams variant should not be flagged.
    SomeHelperMethod() error
}

资料来源：internal/linter/openapi/testdata/src/github.com/grafana/grafana-openapi-client-go/client/datasources/fake.go:8-15

3.1 为什么必须使用 `WithParams` 变体？

mcp-grafana 自研的 OpenAPI linter 正是为了强制业务代码使用 WithParams 变体，从而保留：

1. 请求上下文：在 SSE/streamable-http 模式下可读取用户身份；
2. On-Behalf-Of 认证头：v0.11.6 引入的代理身份转发；资料来源：v0.11.6 Release Notes
3. 结构化日志：v0.12.1 引入的 Logger 字段依赖 context 透传；资料来源：v0.12.1 Release Notes

4. OpenAPI Linter 的工作机制

internal/linter/openapi/testdata/src/testpkg/usage.go 模拟了“业务代码直接调用便利方法”的反例：

func badCalls(c datasources.ClientService) {
    c.GetDataSources()            // want "use GetDataSourcesWithParams with a context-aware params object instead of GetDataSources which drops request context"
    c.GetDataSourceByUID("myuid") // want "use GetDataSourceByUIDWithParams with a context-aware params object instead of GetDataSourceByUID which drops request context"
}

func goodCalls(c datasources.ClientService) {
    c.GetDataSourcesWithParams(nil)
    c.GetDataSourceByUIDWithParams(nil)
    c.SomeHelperMethod() // no WithParams variant, should not be flagged
}

资料来源：internal/linter/openapi/testdata/src/testpkg/usage.go:5-16

4.1 关键规则

规则 3 由 internal/linter/openapi/testdata/src/testpkg/usage_test.go 中的负样例支撑：

func testHelper(c datasources.ClientService) {
    // These convenience calls in test files should NOT be flagged.
    c.GetDataSources()
    c.GetDataSourceByUID("myuid")
}

资料来源：internal/linter/openapi/testdata/src/testpkg/usage_test.go:4-9

这种“测试白名单 + 生产强约束”的设计，使得在演进 OpenAPI 客户端版本时既能保留向后兼容的便利方法，又避免在生产路径上引入上下文丢失。

5. JSONSchema Linter 与 Tool Schema 稳定性

MCP 协议要求每个 Tool 必须提供结构化的输入 Schema（基于 JSON Schema 草案）。mcp-grafana 在 Go struct tag 中使用 jsonschema:"description=...,required=...,title=..." 来生成这些 Schema。internal/linter/jsonschema/README.md 解释了为何需要专用的 linter：

In Go struct tags using jsonschema, commas in the description field need to be escaped using \\, syntax. If commas aren't properly escaped, the description is silently truncated at the comma.

资料来源：internal/linter/jsonschema/README.md:7-9

5.1 反例与正例

// Problematic (description will be truncated at the first comma):
type Example struct {
    Field string `jsonschema:"description=This is a description, but it will be truncated here"`
}

// Correct (commas properly escaped):
type Example struct {
    Field string `jsonschema:"description=This is a description\\, and it will be fully included"`
}

资料来源：internal/linter/jsonschema/README.md:13-22

5.2 影响面

资料来源：internal/linter/jsonschema/README.md:31-39

6. 工具分类与版本演进

下表整理了社区 release notes 中披露的工具演进时间线，用以说明项目架构在“广度（数据源）+ 深度（运维能力）”上的扩张路径：

资料来源：v0.11.4 / v0.11.5 / v0.11.6 / v0.12.0 / v0.12.1 / v0.13.0 / v0.13.1 / v0.14.0 / v0.15.0 / v0.15.1

7. 鉴权与会话模型

社区对鉴权模式的关注度非常高（见 Issue #284 与 Issue #151），目前架构支持三种模式：

graph LR
    A[Client] -->|Bearer Token| B(MCP Server)
    A -->|Basic Auth| B
    A -->|SSO Cookie / Authorization| C[SSE/streamable-http Edge]
    C -->|Forward Headers| B
    B -->|Service Account Token| D[Grafana API]
    B -->|On-Behalf-Of Header| D

8. 典型请求处理时序

下面给出一个 tools/call 调用的端到端时序，串起前述所有机制：

sequenceDiagram
    participant LLM as LLM Client
    participant MCP as MCP Server
    participant RT as HTTP RoundTripper
    participant GAPI as Grafana HTTP API

    LLM->>MCP: tools/call (params)
    MCP->>MCP: 解析 jsonschema，校验参数
    MCP->>MCP: 构造 *XxxParams 对象并绑定 context
    MCP->>RT: 调用 WithParams 变体
    RT->>RT: 注入 On-Behalf-Of / Logger / Session config
    RT->>GAPI: HTTP Request
    GAPI-->>RT: Response
    RT-->>MCP: 解码响应
    MCP-->>LLM: MCP Content (text / image)

该时序的 强制前提 正是 OpenAPI linter 所保障的“必须使用 WithParams 变体”——否则 context 在第一步就会丢失。

9. 社区关注的失败模式

10. 开发者视角的关键目录约定

虽然本次检索未直接命中根目录的 cmd/、internal/tools/ 源文件，但综合 linter 的路径布局可以推测出项目的源码组织习惯：

资料来源：internal/linter/jsonschema/README.md:31-39

11. 总结

1. mcp-grafana 把 Grafana 的全部资源抽象为 MCP Tool，并通过统一的 grafana-openapi-client-go 与 Grafana API 交互。
2. 为了让 LLM 调用既稳定又安全，项目引入了两个自研 linter：

• OpenAPI linter 强制 WithParams 变体，保留 context；
• JSONSchema linter 防止 jsonschema 描述被逗号截断。

1. 鉴权与传输从最初的“单 token + stdio”演进到“SSO/On-Behalf-Of + SSE/streamable-http”，并在 context 中携带可观测的 GrafanaConfig。
2. 数据源覆盖、数据模型、Provisioning 工作流持续扩展（v0.11.4 → v0.15.1），但每一步都伴随显式的测试样例与质量门禁。

See Also

• Tool 目录与各数据源适配器（待补）
• 鉴权与部署模式详解（待补）
• 社区 issue 跟踪：On-Behalf-Of、shorten_url、Instructions 字段

安装方式总览

项目入口为 cmd/mcp-grafana/main.go，可作为本地二进制、uvx 启动的 Python 包、容器镜像或 Helm Chart 部署的 Kubernetes 服务运行。main.go 中通过 flag 解析与环境变量回退机制决定运行模式 资料来源：cmd/mcp-grafana/main.go。

graph TD
    A[mcp-grafana 安装入口] --> B[本地二进制]
    A --> C[uvx/PyPI 包]
    A --> D[Docker 镜像]
    A --> E[Helm Chart]
    B --> F[stdio 模式]
    B --> G[SSE / streamable-http 模式]
    C --> F
    D --> F
    D --> G
    E --> G

本地二进制安装

最直接的方式是从源码构建或在 GitHub Releases 中下载预编译产物。install-the-binary.md 文档描述了 go install 与 Releases 双轨方案。资料来源：docs/sources/set-up/install-the-binary.md。

go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest

uvx / PyPI 安装

install-with-uvx.md 描述了通过 uvx 启动 Python 封装的 mcp-grafana 发行版，使 Python 环境下的代理（如 Claude Desktop）可以零本地编译启动。资料来源：docs/sources/set-up/install-with-uvx.md。

uvx mcp-grafana

Docker 镜像安装

install-with-docker.md 与 Dockerfile 共同定义了镜像的构建方式。Dockerfile 使用多阶段构建来得到一个最小的运行时镜像。资料来源：docs/sources/set-up/install-with-docker.md。社区中曾出现对 dockerhub 上仅有 latest 标签、缺少版本标签的反馈（#180），目前已支持基于发布版本的多标签拉取。

docker run --rm -i mcp/grafana:latest

Helm Chart 部署

deploy-with-helm.md 文档描述了将 mcp-grafana 作为 Kubernetes 服务对外暴露的标准方式。Helm Chart 适用于需要 streamable-http 或 SSE 模式并对外提供端点的生产场景。资料来源：docs/sources/set-up/deploy-with-helm.md。

安装方式对比

命令行参数

command-line-flags.md 列出了 main.go 注册的所有 flag。main.go 使用 flag 标准库解析参数，并在缺失时回退到环境变量。资料来源：docs/sources/configure/command-line-flags.md。

警告：根据 issue #919，启用 --log-level=debug 时服务账号 token 可能以明文形式写入日志；建议在生产中关闭 debug 日志，并使用专用日志收集器脱敏。

环境变量

environment-variables.md 定义了与 CLI flag 对应的环境变量入口，便于在容器或 CI 中不修改 entrypoint 的前提下注入配置。资料来源：docs/sources/environment-variables.md。

多实例（Per-Request 配置）

自 v0.12.1 起，GrafanaConfig 结构支持 context 注入的 per-request 配置（#805），允许单个服务进程同时承载多个 Grafana 实例的请求。配置链通过 HTTP RoundTripper 携带，便于代理或网关层动态选择目标。

传输模式

transports-and-addresses.md 详细描述了三种传输层模式。stdio 用于本地代理与进程内通信；sse 与 streamable-http 用于远程客户端（Web IDE、ChatOps 平台等）。资料来源：docs/sources/configure/transports-and-addresses.md。

graph LR
    subgraph Local
        A[MCP Client] -- stdio --> B[mcp-grafana]
    end
    subgraph Remote
        C[Web Client] -- SSE --> B2[mcp-grafana]
        D[ChatOps] -- streamable-http --> B2
    end
    B --> E[Grafana API]
    B2 --> E

SSE 模式

Server-Sent Events 适合长连接场景。main.go 中通过 --transport=sse 选择该模式，并使用 --address 指定监听地址。资料来源：cmd/mcp-grafana/main.go。

streamable-http 模式

streamable-http 在 v0.11.5 中获得对请求头转发（如 Cookie、Authorization）的支持（#659），从而允许通过 ALB/SSO 会话 cookie 复用浏览器身份。该能力对希望避免在服务端预置长期 service account token 的组织尤其重要。

鉴权方式

社区中曾多次反馈希望支持 OAuth/SSO（#284）以及面向终端用户的轻量级身份流（#151）。当前原生支持的鉴权机制包括：

注意：所有鉴权凭证都应通过 secret 管理（Kubernetes Secret、Vault 等）注入；docker-compose.yaml 中默认包含环境变量注入模板，请勿将真实 token 提交到版本控制。资料来源：docker-compose.yaml。

通用 API 工具

tools/generic-api.md 描述了自 v0.14.0 引入的通用 HTTP 请求工具（#841），可在不引入新工具的前提下访问任意 Grafana REST 端点。资料来源：docs/sources/tools/generic-api.md。该工具对运维集成（如短链生成 #820、自定义插件调用）尤其有用，部署时应评估其暴露面并通过 GRAFANA_DISABLE_TOOLS 之类的 flag 收缩权限。

Docker 部署细节

Dockerfile 使用多阶段构建，第一阶段编译二进制，第二阶段以 distroless 或 alpine 为基础镜像以缩减攻击面。docker-compose.yaml 提供本地一键启动模板，默认将服务暴露在 127.0.0.1:8000，并通过环境变量注入 Grafana URL 与 API key。资料来源：Dockerfile、docker-compose.yaml。

graph TD
    A[docker-compose up] --> B[启动 mcp-grafana 容器]
    B --> C{Transport}
    C -->|stdio| D[由宿主机 MCP 客户端 attach]
    C -->|sse / http| E[监听 0.0.0.0:8000]
    E --> F[Grafana API via HTTPS]

健康检查与日志

建议结合 HEALTHCHECK 指令在镜像中暴露 /healthz，并在编排文件中设置：

healthcheck:
  test: ["CMD", "wget", "-qO-", "http://localhost:8000/healthz"]
  interval: 30s
  retries: 3

Kubernetes / Helm 部署

deploy-with-helm.md 给出了 Helm Chart 字段约定。生产部署关键点：

• Service 类型：SSE/streamable-http 模式建议使用 ClusterIP 并由 Ingress 暴露，避免直接对外。
• ConfigMap：通过 GRAFANA_CONFIG 挂载多实例配置。
• Secret：仅将 GRAFANA_API_KEY 等敏感字段放入 Secret。
• HPA：根据 mcp_session_active 等自定义指标伸缩。
• NetworkPolicy：限制 mcp-grafana 出口到 Grafana API 端点。

graph TD
    A[Ingress] --> B[mcp-grafana Deployment]
    B --> C[Grafana API]
    B --> D[ConfigMap: 多实例配置]
    B --> E[Secret: GRAFANA_API_KEY]
    B --> F[ServiceMonitor / Prometheus]

常见故障与排查

配置最佳实践清单

1. 优先使用环境变量而非 CLI 参数，便于在容器编排中覆盖。
2. 生产关闭 debug 日志，避免凭证泄漏（#919）。
3. 多 Grafana 实例使用 per-request context 模式（v0.12.1+）。
4. SSE/HTTP 模式启用请求头转发以兼容 SSO（v0.11.5+）。
5. Helm 部署使用 Secret 注入 service account token，并配置 NetworkPolicy。
6. 审计 instructions 字段——MCP 协议层提示，避免 issue #680 所述的提示注入风险。
7. 选择合适的传输模式：本地代理使用 stdio，远程客户端使用 streamable-http。
8. 通用 API 工具按需开启，避免暴露面扩大。

See Also

• Authentication & Security
• Tools Overview
• Troubleshooting
• Release Notes

概述

mcp-grafana 将 Grafana 平台的众多能力（仪表板、告警、事件、可观测性数据源）暴露为 MCP（Model Context Protocol）工具，使大语言模型客户端能够以结构化方式查询与操作 Grafana。社区的讨论表明，工具生态主要集中在两大方向：

1. 核心资源工具：仪表板、告警规则、事件、SLO、OnCall 等 Grafana 内置对象的管理；
2. 数据源集成（datasource integrations）：Prometheus、Loki、InfluxDB、CloudWatch、Athena、Snowflake、Elasticsearch、OpenSearch、Pyroscope 等后端数据源的查询、Schema 发现与宏变量替换。

随着数据源集成的不断扩展，仓库引入了一组 内部静态检查（linters） 来保障核心工具与数据源集成的代码质量与运行时正确性。这两个 linter（jsonschema 与 openapi）是本仓库源码中可直接观察到的"核心工具与集成"基础设施层。下面分别介绍。

工具描述规范：jsonschema Linter

问题背景

MCP 工具的输入参数通常由 Go 结构体上的 jsonschema 标签描述。当标签中的 description 字段含有未转义的英文逗号时，jsonschema 解析器会在第一个逗号处截断描述，导致模型看到的工具说明被静默截断。

资料来源：internal/linter/jsonschema/README.md:5-19

// 错误写法：description 会在第一个逗号处被截断
type Example struct {
    Field string `jsonschema:"description=This is a description, but it will be truncated here"`
}

// 正确写法：逗号使用反斜杠转义
type Example struct {
    Field string `jsonschema:"description=This is a description\, and it will be fully included"`
}

运行方式与自动修复

该 linter 已被纳入默认的 make lint 流程，确保任何 PR 都不会引入被截断的 jsonschema 描述。

资料来源：internal/linter/jsonschema/README.md:21-43

Grafana OpenAPI 客户端使用规范：openapi Linter

为什么需要这个 Linter

mcp-grafana 大量依赖 grafana-openapi-client-go 与 Grafana HTTP API 交互。该客户端为每个端点提供两种调用形式：

• 便捷方法（如 GetDataSources()、GetDataSourceByUID(uid)）：不接受 context.Context，因此会丢失 MCP 框架下注入的请求作用域（例如 trace、超时、on-behalf-of 头）；
• WithParams 方法（如 GetDataSourcesWithParams(params, opts...)、GetDataSourceByUIDWithParams(params, opts...)）：允许传入 context，是 MCP 服务器调用 Grafana API 的正确方式。

资料来源：internal/linter/openapi/testdata/src/github.com/grafana/grafana-openapi-client-go/client/datasources/fake.go:1-13

Linter 行为

openapi linter 通过在 fake 客户端接口上为每个便捷方法匹配其 WithParams 变体来识别"会丢失请求上下文"的调用点：

• 当便捷方法存在对应的 WithParams 变体时，linter 会在生产代码中发出 use ...WithParams with a context-aware params object instead of ... which drops request context 警告；
• 当便捷方法没有 WithParams 变体（例如 SomeHelperMethod）时，linter 不会发出警告。

资料来源：internal/linter/openapi/testdata/src/testpkg/usage.go:1-13

测试代码豁免

测试文件中的便捷方法调用不会被标记。这一规则以 usage_test.go 中的 fixture 表示：

func testHelper(c datasources.ClientService) {
    // 测试文件中的便捷调用不应被标记
    c.GetDataSources()
    c.GetDataSourceByUID("myuid")
}

资料来源：internal/linter/openapi/testdata/src/testpkg/usage_test.go:1-7

工作流程图

graph TD
    A[工具调用到达 MCP Server] --> B[使用 context 构造请求]
    B --> C[选择 Grafana OpenAPI 客户端方法]
    C --> D{是否存在 WithParams 变体?}
    D -- 是 --> E[调用 WithParams 并传入 context]
    D -- 否 --> F[可调用便捷方法]
    E --> G[Grafana API 收到带 trace/timeout/on-behalf-of 头的请求]
    F --> G
    G --> H[响应回传给 LLM 客户端]

核心工具与数据源集成的生态全景

虽然仓库的内部 linter 测试数据仅展示 datasources 客户端的有限接口，但社区的发布记录与 Issue 表明，mcp-grafana 的"核心工具 + 数据源集成"已经形成较完整的生态。下表汇总了社区近几个版本中持续扩展的集成：

社区关注的重点与常见失败模式

安全：调试日志中明文泄露服务账号令牌

Issue #919 报告：当调试日志开启时，Grafana 服务账号令牌会以明文形式出现在日志输出中。在集中式日志系统中，这意味着令牌可能被广泛访问者获取。建议在生产环境中关闭调试日志或配置日志脱敏。

资料来源：Issue #919

鉴权模式局限

社区长期关注的两大主题：

• OAuth/SSO 支持（Issue #284）：现有鉴权主要依赖服务账号令牌与 Basic Auth；v0.11.5 引入了在 SSE/streamable-http 模式下转发 Cookie 与 Authorization 头的能力，使 SSO 落地成为可能，但完整 OAuth 流仍不在范围内。
• 普通用户工作流（Issue #151）：服务账号需要高权限，阻碍普通用户直接使用 MCP 客户端。

资料来源：Issue #284 | Issue #151

数据源发现失败

Issue #398 报告在 Grafana 服务运行正常、API 单独可访问的情况下，mcp-grafana 调用 GetDataSources 时返回 EOF 错误。这通常与上文提到的"便捷方法丢失请求上下文"问题相关——通过 openapi linter 强制使用 WithParams 变体可降低此类连接问题的发生概率。

资料来源：Issue #398

MCP `Instructions` 缺失

Issue #908 提出当前的 MCP initialize 响应未携带非空的 Instructions 字段，导致智能体难以了解工具能做什么、不能做什么。该问题在引入 Instructions 后可改善 LLM 路由与工具选择。

资料来源：Issue #908

长 Explore 链接的可用性

generate_deeplink 工具生成的链接中包含几百字符的 URL 编码 JSON，对嵌入聊天消息不友好。v0.15.1 引入 shorten_url 工具（基于 /api/short-urls）用于解决此问题。

资料来源：Issue #820 | Release v0.15.1

常见配置项参考

下表整理了与"核心工具与数据源集成"行为密切相关的几个核心配置项（基于仓库 v0.12.x 起的发布说明与社区讨论）：

See Also

• 项目主页：grafana/mcp-grafana
• 发布说明：v0.15.0 · v0.14.0 · v0.13.1 · v0.12.0 · v0.11.6 · v0.11.5 · v0.11.4 · v0.15.1
• 社区 Issue：#284 OAuth/SSO · #151 普通用户工作流 · #146 SQL 数据源 · #176 InfluxDB · #180 Docker 镜像标签 · #398 数据源发现 EOF · #820 短链接 · #908 Instructions · #919 调试日志令牌泄露

本页系统梳理 mcp-grafana 项目的认证、安全、基于角色的访问控制（RBAC）与故障排除相关内容。mcp-grafana 是一个 Model Context Protocol (MCP) 服务器，允许 LLM 代理通过标准化工具接口与 Grafana 实例进行交互。由于 LLM 工具调用通常涉及企业级数据，认证凭据保护、传输加密、最小权限原则以及常见运行错误的处理便成为生产部署的关键。

1. 认证（Authentication）

1.1 支持的认证方式

mcp-grafana 当前原生支持以下两种 Grafana 认证机制：

资料来源：docs/sources/configure/authentication.md

社区中曾多次讨论是否需要扩展到 OAuth/SSO（Okta、Google、Azure AD 等）支持（参见 Issue #284），但截至 v0.15.1 版本仍未内置 OAuth 流程。当前的推荐做法是使用最小权限的服务账号令牌（参见 Issue #151 中关于"常规用户工作流"的讨论）。

1.2 客户端配置缓存

服务器通过一个客户端缓存复用 Grafana HTTP 客户端，避免每次工具调用都建立新连接。客户端缓存按 (URL, AuthProfile) 维度组织，并支持向后端 Grafana 实例转发现有的请求头（如 Cookie、Authorization）。

资料来源：client_cache.go

1.3 多租户与请求头转发

当通过 SSE 或 streamable-http 模式部署 mcp-grafana 时，服务器可以选择性地将传入的请求头转发到 Grafana，从而支持以下场景：

• ALB / 反向代理会话 Cookie 透传
• SSO 登录态（即 Cookie 中的会话信息）传递
• 应用负载均衡器 的身份保持

可通过 --disable-headers-forwarding CLI 标志关闭该行为。请求头转发是 v0.11.5 引入的特性。

资料来源：docs/sources/configure/multi-organization-and-headers.md

1.4 On-Behalf-Of 身份委托

v0.11.6 起，Grafana 客户端传输链路会注入 on-behalf-of 头，允许 Grafana 服务端识别最终用户身份，而不仅仅使用服务账号身份。该能力与多组织/请求头转发配合，可在审计日志中区分"是哪个用户通过 LLM 代理触发了该操作"。

资料来源：tools/fallback_transport.go

1.5 认证流程

graph TD
    A[MCP 客户端/LLM 代理] -->|stdio / SSE / streamable-http| B[mcp-grafana 服务器]
    B --> C{传输模式}
    C -->|stdio| D[使用环境变量中的服务账号令牌]
    C -->|SSE/HTTP| E[读取传入请求头]
    E --> F{是否存在 Cookie/Authorization?}
    F -->|是| G[转发到 Grafana 后端]
    F -->|否| D
    D --> H[Grafana HTTP API]
    G --> H
    H --> I[返回结果]
    I --> B
    B --> J[返回 MCP 工具结果给 LLM]

2. 安全（Security）

2.1 调试日志中的凭据泄露

社区曾报告一个严重安全问题（Issue #919）：当启用调试日志（debug logging）时，Grafana 服务账号令牌会以明文形式写入日志输出。由于日志通常会被转发到集中式日志系统（如 Loki、ELK），这会扩大凭据泄露面。

缓解措施：

• 生产环境严禁开启 DEBUG 级别日志
• 使用专用最小权限令牌（参见 §3 RBAC）
• 在集中式日志系统中配置敏感字段脱敏规则
• 通过 GrafanaConfig.Logger（v0.12.1 引入）注入自定义 logger，便于在结构化日志中过滤 Authorization 字段

资料来源：observability/logs.go

2.2 传输加密（TLS）

#### 2.2.1 客户端到 Grafana 的 TLS

mcp-grafana 连接到 Grafana 后端时支持自定义 CA 证书，便于接入自签名证书或私有 CA 签发的 Grafana 实例。

资料来源：docs/sources/configure/client-tls-grafana-connection.md

#### 2.2.2 服务器到 MCP 客户端的 TLS

当以 streamable-http 模式部署时，服务器自身也可以启用 TLS，确保 LLM 代理到 mcp-grafana 之间的链路加密。

资料来源：docs/sources/configure/server-tls-streamable-http.md

2.3 会话与超时

为降低长会话被劫持的风险，v0.11.4 引入了 --session-idle-timeout-minutes CLI 标志，自动清理空闲会话。

资料来源：session.go

2.4 LLM 提示注入防护

社区曾有担忧（Issue #680、Issue #908）：在 MCP Instructions 中返回的描述可能被构造为"提示注入"载体，从而操纵 LLM 行为。运营建议：

• 将 mcp-grafana 部署在受信网络
• 限制可调用工具的 LLM 客户端
• 监控异常工具调用模式

3. RBAC（基于角色的访问控制）

3.1 工具级别的启用/禁用

mcp-grafana 允许运维人员按类别启用或禁用整组工具，从而实现粗粒度的 RBAC。例如，可关闭所有修改类工具（mutation_*），只暴露只读工具（search_*、get_*、list_*）。

可用的工具类别包括但不限于：

通过 disable_<category> 系列配置项或 CLI 标志进行管理。

资料来源：docs/sources/configure/enable-and-disable-tools.md

3.2 Grafana 侧的角色与权限

mcp-grafana 不维护自己的权限模型，而是完全依赖 Grafana 服务账号的角色与权限配置。当使用服务账号令牌访问 Grafana 时，Grafana 服务端会按该服务账号的角色（Admin / Editor / Viewer）做授权。

最佳实践：

1. 为不同 LLM 用例创建独立的服务账号，每个账号授予 Grafana 端的最小必要角色
2. 在 Grafana 的 Folder / Dashboard ACL 上做更细粒度的访问控制
3. 定期轮换服务账号令牌

3.3 多组织（Multi-Org）支持

对于多组织 Grafana 部署（如 Grafana Cloud），可通过 X-Grafana-Org-Id 请求头在不同组织之间切换，这同样受 §1.3 中所述的请求头转发机制控制。

资料来源：docs/sources/configure/multi-organization-and-headers.md

4. 故障排除（Troubleshooting）

4.1 Grafana 版本兼容性

mcp-grafana 与 Grafana 的 OpenAPI 客户端强绑定，因此存在 Grafana 版本下限。请始终以官方兼容性矩阵为准；不满足最低版本要求时，OpenAPI 调用可能返回 404 或 schema 解析错误。

资料来源：docs/sources/troubleshooting/grafana-version-compatibility.md

4.2 常见错误与排查

最后一行提到的"OpenAPI 便捷方法"对应项目内置的 openapi linter 规则：当调用 grafana-openapi-client-go 提供的便捷方法（如 GetDataSources()）时会丢失请求上下文（context.Context），而 mcp-grafana 强依赖上下文进行取消、超时与请求头注入。该 linter 会强制使用 GetDataSourcesWithParams(nil) 等变体。

资料来源：internal/linter/openapi/testdata/src/testpkg/usage.go

4.3 JSONSchema 描述截断问题

mcp-grafana 大量使用 jsonschema 标签生成 MCP 工具输入 schema。当 description 字段包含未转义的逗号时，schema 会被静默截断——这会导致 LLM 看到的工具描述不完整，从而产生幻觉或参数缺失错误。

修复方式：

// 错误（描述被截断）
Field string `jsonschema:"description=查询时间范围, 单位秒"`

// 正确（逗号转义）
Field string `jsonschema:"description=查询时间范围\, 单位秒"`

可通过 make lint-jsonschema 检查，make lint-jsonschema-fix 自动修复。

资料来源：internal/linter/jsonschema/README.md

4.4 故障排除流程图

graph TD
    Start[工具调用失败] --> Q1{错误码是什么?}
    Q1 -->|401| A1[检查/轮换服务账号令牌]
    Q1 -->|403| A2[调整 Grafana 侧服务账号角色]
    Q1 -->|404| A3[检查 Grafana 版本兼容性]
    Q1 -->|EOF / 连接错误| A4[检查网络/TLS/反向代理]
    Q1 -->|500/Schema 异常| A5[运行 make lint-jsonschema 检查 schema 截断]
    Q1 -->|其他| A6[查看调试日志并脱敏后提交 Issue]
    A1 --> Verify[重试]
    A2 --> Verify
    A3 --> Verify
    A4 --> Verify
    A5 --> Verify
    A6 --> Verify

4.5 已知限制

• OAuth/SSO 直连尚未支持（Issue #284）。当前仅能通过请求头转发（§1.3）配合 ALB/反向代理间接实现 SSO 上下文传递。
• 服务账号创建需要 Grafana 管理员权限，对常规用户不友好（Issue #151）。建议由 Grafana 管理员统一预置最小权限服务账号。

5. 安全最佳实践清单

部署 mcp-grafana 到生产环境前，请逐项确认：

• [ ] 使用最小权限服务账号令牌（仅授予 LLM 实际需要的角色与文件夹 ACL）
• [ ] 不启用 DEBUG 日志；若必须启用，确保日志存储支持字段级脱敏
• [ ] 客户端到 Grafana 的连接启用 TLS，并正确配置 CA 证书
• [ ] 以 streamable-http 部署时，服务器自身启用 TLS（MCP_TLS_CERT_FILE / MCP_TLS_KEY_FILE）
• [ ] 通过 disable_* 配置关闭不必要的写操作工具
• [ ] 定期轮换服务账号令牌
• [ ] 设置 --session-idle-timeout-minutes 避免会话无限期驻留
• [ ] 在 Grafana 侧开启审计日志，并通过 on-behalf-of 头（v0.11.6）追溯到具体最终用户

See Also

• 配置：认证方式
• 配置：多组织与请求头转发
• 配置：客户端 TLS
• 配置：服务器 TLS（streamable-http）
• 配置：启用/禁用工具
• 故障排除：Grafana 版本兼容性
• Issue #284: OAuth/SSO 支持请求
• Issue #919: 调试日志泄露令牌
• Issue #398: 数据源发现失败
• Issue #151: 常规用户工作流

Pitfall Log / 踩坑日志

项目：grafana/mcp-grafana

摘要：发现 12 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：维护坑 - 来源证据：Insturctions。

1. 维护坑 · 来源证据：Insturctions

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Insturctions
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/grafana/mcp-grafana/issues/908 | 来源类型 github_issue 暴露的待验证使用条件。

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | github_repo:907869862 | https://github.com/grafana/mcp-grafana | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:907869862 | https://github.com/grafana/mcp-grafana | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:907869862 | https://github.com/grafana/mcp-grafana | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:907869862 | https://github.com/grafana/mcp-grafana | no_demo; severity=medium

6. 安全/权限坑 · 来源证据：Add tool to create Grafana short URLs (/goto/<uid>) via /api/short-urls

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add tool to create Grafana short URLs (/goto/<uid>) via /api/short-urls
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/grafana/mcp-grafana/issues/820 | 来源类型 github_issue 暴露的待验证使用条件。

7. 安全/权限坑 · 来源证据：Feature Request: Add BigQuery Support to `run_panel_query` Tool

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: Add BigQuery Support to run_panel_query Tool
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/grafana/mcp-grafana/issues/922 | 来源类型 github_issue 暴露的待验证使用条件。

8. 安全/权限坑 · 来源证据：Fix the docker build workflow

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Fix the docker build workflow
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/grafana/mcp-grafana/issues/923 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

9. 安全/权限坑 · 来源证据：Grafana MCP Server Fails to Discover Datasources

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Grafana MCP Server Fails to Discover Datasources
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/grafana/mcp-grafana/issues/398 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

10. 安全/权限坑 · 来源证据：[Security] Debug logging exposes Grafana service account token in plaintext logs

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Security] Debug logging exposes Grafana service account token in plaintext logs
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/grafana/mcp-grafana/issues/919 | 来源类型 github_issue 暴露的待验证使用条件。

11. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:907869862 | https://github.com/grafana/mcp-grafana | issue_or_pr_quality=unknown

12. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:907869862 | https://github.com/grafana/mcp-grafana | release_recency=unknown