명령줄 플래그

명령줄 플래그

mcp-grafana 바이너리는 전송(transport), 도구, TLS, 관측성(observability) 관련 플래그를 받아요. 설치된 빌드의 정확한 목록은 mcp-grafana --help를 실행해서 확인하세요.

출처: 문서

본문

무엇을 얻을 수 있을까요

소스를 다시 읽지 않고도 기본값을 찾아보고, --disable-* 플래그를 고르고, TLS를 구성할 수 있어요.

시작하기 전에

  • mcp-grafana를 내 머신에서 실행할 방법이 필요해요 — 예를 들어 릴리스 바이너리, uvx, 컨테이너 같은 것요.

전송(transport)과 HTTP 옵션 구성하기

  • -t / --transport: 전송 유형 (stdio, sse, streamable-http). 기본: stdio.
  • --address: SSE 또는 streamable-http 서버의 호스트와 포트. 기본: localhost:8000.
  • --base-path: SSE 또는 streamable-http 서버의 기본 경로. --base-path /my-base로 설정하면 SSE는 /my-base/sse, streamable-http는 /my-base/mcp가 돼요. /healthz와 /metrics는 프로브와 스크래퍼 전용 내부 엔드포인트라 항상 서버 루트에 남고, 이 프리픽스 아래로 내려가지 않아요.
  • --endpoint-path: streamable-http MCP 엔드포인트의 HTTP 경로로, --base-path 뒤에 붙어요. 기본: /mcp.
  • --session-idle-timeout-minutes: streamable-http 세션의 유휴 타임아웃(분 단위). 이 시간 동안 활동이 없으면 세션이 자동으로 정리돼요. 0으로 설정하면 비활성화돼요. 기본: 30.
  • --instructions-append: MCP 클라이언트가 initialize할 때 반환되는 서버 지침에 덧붙일 텍스트라서, 연결하는 모든 에이전트가 이 문구를 보게 돼요.

HTTP 전송 보안 구성하기

SSE와 streamable-http 전송은 MCP 리스너(/sse, /mcp, 그리고 같은 리스너에 남아 있는 /healthz//metrics)의 모든 라우트에서 Host와 Origin 헤더를 검증해 DNS-rebinding 공격을 막아요. Stdio 전송은 영향을 받지 않아요. --healthz-address나 --metrics-address가 시작한 사이드 리스너는 래핑되지 않아요.

  • --allowed-hosts: 허용할 Host 헤더 값의 쉼표 구분 목록. 설정하지 않으면 (또는 파싱된 값이 비어 있으면 — 예: ,,,) --address의 루프백 변형(예: localhost:8000, 127.0.0.1:8000, [::1]:8000)으로 폴백해요. *를 넘기면 Host 검증을 끄는데, 신뢰할 수 있는 리버스 프록시가 Host를 검증할 때만 안전해요.
  • --allowed-origins: 허용할 Origin 헤더 값의 쉼표 구분 목록. 기본은 비어 있어서 Origin 헤더를 가진 요청은 모두 거부돼요 (브라우저는 크로스 오리진 요청에 항상 Origin을 보내고, 브라우저가 이 서버를 직접 호출하는 일은 없어야 하니까요). 브라우저 클라이언트를 허용하려면 명시적 목록을, 검증을 끄려면 *를 넘기세요.

인그레스나 리버스 프록시 뒤에 배포하면서 원래 Host를 전달한다면, --allowed-hosts에 예상 호스트명을 설정하세요 (예: --allowed-hosts mcp.example.com). Kubernetes httpGet liveness/readiness 프로브는 기본적으로 Host: :를 보내요 — --allowed-hosts '*'로 설정하거나, 프로브의 host: 필드를 덮어쓰거나, tcpSocket 프로브를 쓰거나, /healthz를 --healthz-address(그리고 /metrics는 --metrics-address)에 바인딩하면 돼요. 이 사이드 리스너는 Host/Origin 검증에 래핑되지 않아요.

호출자 인증 구성하기

SSE와 streamable-http 전송은 호출자(MCP 클라이언트)를 인증할 수 있어요. 이건 서버가 Grafana에 도달할 때 쓰는 자격 증명과는 별개예요. 서버를 호출할 수 있는 사람을 통제해서, 인증되지 않은 클라이언트가 서버의 Grafana 신원을 빌려 쓰거나 도구를 실행하지 못하게 해요. Stdio는 로컬 파이프라서 영향을 받지 않아요.

  • --server-auth-token: 호출자가 Authorization: Bearer ***에 담아 제시해야 하는 Bearer 토큰이에요. MCP_GRAFANA_SERVER_TOKEN 환경 변수로 폴백돼요. 설정하면 유효한 토큰이 없는 요청은 어떤 도구도 실행되기 전에 401로 거부돼요. 비밀이 프로세스 인자 목록에 나타나지 않도록 플래그보다 환경 변수를 쓰는 게 좋아요.

바인드 정책

호출자 인증은 --server-auth-token이 설정됐을 때만 적용돼요. 설정되지 않았으면 네트워크 전송은 외부에서 접근 가능한 주소에 바인딩할 때 경고만 하고 (그래도 시작은 해요):

Transport / bind Behavior
stdio No caller authentication (local pipe).
SSE / streamable-http on a loopback address (localhost, 127.0.0.1, ::1) Caller token optional.
SSE / streamable-http on any other address Starts and logs a security error (at the error log level, so it isn’t suppressed by --log-level) unless --server-auth-token is set.

참고: 관대한 기본값은 기존 배포(컨테이너의 0.0.0.0 바인드처럼)와의 하위 호환성을 유지하기 위한 것이에요. 향후 메이저 릴리스에서는 인증되지 않은 비루프백 바인드를 시작 오류로 만들 예정이에요. 지금 --server-auth-token을 설정해 호출자 인증을 요구하고 그 변화에 대비하세요.

인증 토큰은 연결이 암호화된 경우에만 전송 중 보호돼요. 비루프백 주소에서 --server-auth-token을 설정할 때는 서버 앞에서 TLS를 종료하거나, streamable-http의 서버 TLS를 사용하세요.

호출자 인증이 켜져 있으면 Authorization 헤더는 호출자 토큰 전용으로 예약되고 검증 후 제거돼서 Grafana로 절대 전달되지 않아요. --server-auth-token과 GRAFANA_FORWARD_HEADERS=Authorization을 함께 설정하면 모순이라 서버가 시작을 거부해요. GRAFANA_FORWARD_HEADERS에서 Authorization을 제거하거나, 프록시 전달 모드로 실행하려면 호출자 토큰을 해제하세요.

요청별 Grafana URL 선택하기

경고: URL 오버라이드는 MCP 호출자가 아웃바운드 HTTP(S) 목적지를 선택하게 해요. 허용 목록은 URL을 제한하지만 호출자를 인증하거나, 토큰을 대상에 바인딩하거나, 네트워크 이그레스 정책을 강제하지는 않아요.

호출자의 각 목적지를 인가하고, 클라이언트가 보낸 X-Grafana-URL과 Grafana 토큰 헤더를 제거하고, 승인된 URL을 그에 맞는 토큰과 함께 제공하는 인증 프록시 뒤에 배포하세요. 네트워크 정책, 방화벽, 이그레스 프록시로 승인된 목적지에만 아웃바운드 접근을 제한하세요. 이런 통제는 허용 목록이 있더라도 중요해요.

URL 허용 목록이 없으면 가짜 요청 토큰으로 도달 가능한 모든 HTTP(S) 서비스(내부·메타데이터 서비스 포함)에 요청을 보낼 수 있어요.

SSE와 streamable-http 전송에서는 호출자가 요청별로 Grafana 인스턴스를 선택할 수 있어요. 기본은 비활성화돼 있어요.

  • --allow-grafana-url-override: X-Grafana-URL을 통한 선택을 활성화해요. 플래그를 설정하지 않으면 GRAFANA_ALLOW_URL_OVERRIDE로 폴백돼요.
  • --allowed-grafana-urls: 호출자가 선택할 수 있는 정확한 Grafana 기본 URL의 선택적 쉼표 구분 목록. 플래그를 설정하지 않으면 GRAFANA_ALLOWED_URLS로 폴백돼요. 활성화 스위치가 필요하고, 명시적으로 빈 플래그는 상속된 목록을 비워요.

프록시로 선택되는 대규모 플릿에서는 GRAFANA_ALLOW_URL_OVERRIDE=true로 목록의 모든 인스턴스를 나열하지 않아도 선택이 가능해져요. 위 경고의 배포 통제는 여전히 적용돼요. 프록시는 각 MCP 요청에 X-Grafana-URL:과 X-Grafana-Service-Account-Token:을 모두 보내야 해요. 폐기 예정인 X-Grafana-API-Key 헤더도 동작해요. 서버는 그 요청의 토큰을 쓰고, 환경 Grafana 자격 증명을 선택된 대상으로 보내지 않아요. 호출자 인증을 구성했다면 Authorization 헤더는 별도의 MCP 호출자 토큰을 담아요.

--allowed-grafana-urls가 없으면 서버는 시작 시 보안 오류를 로그로 남겨요. 아웃바운드 Grafana 요청은 리다이렉트를 포함해 선택된 기본 URL로 고정돼요. SSE에서는 메시지 POST마다 선택 헤더를 포함하세요. 초기 GET의 헤더는 도구 호출로 이어지지 않아요.

디버그와 로깅 구성하기

  • --debug: Grafana API로/로부터 오가는 상세 HTTP 요청·응답 로깅을 위한 디버그 모드를 켜요.
  • --log-level: 로그 레벨 (debug, info, warn, error). 기본: info.

관측성(observability) 엔드포인트 구성하기

  • --metrics: /metrics에 Prometheus 메트릭 엔드포인트를 노출해요 (SSE와 streamable-http에서만).
  • --metrics-address: 메트릭용 선택적 별도 리슨 주소 (예: :9090). 비어 있으면 메트릭은 메인 HTTP 서버에서 서빙돼요.
  • --healthz-address: /healthz용 선택적 별도 리슨 주소 (예: :8080). 비어 있으면 /healthz는 메인 HTTP 서버에서 서빙돼요. --metrics-address와 같으면 두 라우트가 별도 리스너 하나를 공유해요. 사이드 리스너는 Host/Origin 검증에 래핑되지 않아서, --address가 루프백에 있어도 Kubernetes 프로브가 도달할 수 있어요.

익명 사용 통계 구성하기

  • --usage-stats: 익명 사용 통계 보고 — enabled, disabled, log(보낼 보고서를 stderr에 출력하고 아무것도 보내지 않음). GRAFANA_USAGE_STATS 환경 변수를 덮어써요. 기본: disabled.

GRAFANA_USAGE_STATS_ENDPOINT는 보고서를 보낼 위치를 바꿔요.

전체 필드 목록, 절대 보내지 않는 것, 데이터 읽는 방법은 Anonymous usage statistics 문서를 참고하세요.

도구 카테고리 구성하기

  • --enabled-tools: 활성화할 도구 카테고리의 쉼표 구분 목록. 기본은 정확히 search,datasource,incident,prometheus,loki,alerting,dashboard,folder,oncall,asserts,sift,pyroscope,navigation,tempo,annotations,rendering,snapshot,docs예요. 기본 문자열에 없는 카테고리(예: admin, agento11y, assistant, elasticsearch, cloudwatch, cloudlogging, examples, sql, influxdb, quickwit, runpanelquery)는 추가할 때까지 꺼져 있어요. 기본값을 완전히 대체하려면 전체 쉼표 구분 목록을 넘기거나, --disable-* 플래그로 기본 집합의 일부를 끄면 돼요. 하위 호환 별칭 clickhouse, snowflake, athena는 sql로, proxied는 tempo로 매핑돼요.
  • --disable-search: search 도구 비활성화.
  • --disable-datasource: datasource 도구 비활성화.
  • --disable-incident: incident 도구 비활성화.
  • --disable-prometheus: Prometheus 도구 비활성화.
  • --disable-write: 쓰기 도구 비활성화 (읽기 전용 모드; 아래 섹션 참고).
  • --disable-query: 쿼리 도구(데이터소스에 쿼리를 실행하는 도구) 비활성화 (아래 섹션 참고).
  • --enable-query: --disable-write 아래에서 raw-SQL 쿼리 도구를 유지해요 (아래 섹션 참고).
  • --disable-loki: Loki 도구 비활성화.
  • --disable-elasticsearch: Elasticsearch 도구 비활성화.
  • --disable-quickwit: Quickwit 도구 비활성화.
  • --disable-influxdb: InfluxDB 도구 비활성화.
  • --disable-alerting: alerting 도구 비활성화.
  • --disable-dashboard: dashboard 도구 비활성화.
  • --disable-folder: folder 도구 비활성화.
  • --disable-oncall: OnCall 도구 비활성화.
  • --disable-asserts: Asserts 도구 비활성화.
  • --disable-sift: Sift 도구 비활성화.
  • --disable-admin: admin 도구 비활성화.
  • --disable-pyroscope: Pyroscope 도구 비활성화.
  • --disable-navigation: navigation (deeplink) 도구 비활성화.
  • --disable-rendering: rendering 도구(패널·대시보드 이미지 내보내기) 비활성화.
  • --disable-snapshot: snapshot 도구 비활성화.
  • --disable-cloudwatch: CloudWatch 도구 비활성화.
  • --disable-cloudlogging: Google Cloud Logging 도구 비활성화.
  • --disable-examples: query examples 도구 비활성화.
  • --disable-sql: SQL 데이터소스 도구(ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL) 비활성화. 별칭 --disable-clickhouse, --disable-snowflake, --disable-athena도 동작해요.
  • --disable-runpanelquery: run panel query 도구 비활성화.
  • --disable-annotations: annotation 도구 비활성화.
  • --disable-tempo: Tempo 추적 도구 비활성화.
  • --disable-provisioning: provisioning 도구 비활성화.
  • --disable-agento11y: Agent Observability 도구 비활성화.
  • --disable-assistant: Grafana Assistant 도구 비활성화.
  • --disable-docs: 문서 도구 비활성화.
  • --disable-user: user info 도구 비활성화.

도구 한도 구성하기

  • --max-loki-log-limit: query_loki_logs 호출당 반환되는 최대 로그 줄 수.
  • --loki-guardrail-mode: query_loki_logs용 Loki 쿼리 비용 가드레일 — off(기본), shadow(차단될 쿼리를 로그로 남기되 실행은 허용), enforce(재작성 안내와 함께 거부). 가드레일은 선택적 스트림 셀렉터를 요구하고, 유효 시간 범위([30d] 같은 range-vector 기간 포함)를 제한하고, 쿼리 실행 전에 Loki의 index/stats 바이트 추정치를 사전 점검해요. VictoriaLogs에서는 셀렉터 형태({...}) 쿼리에만 적용돼요 — 중괄호 없는 LogsQL은 완전히 통과하고 바이트 예산 점검도 적용되지 않아요. GRAFANA_LOKI_GUARDRAIL_MODE 환경 변수로 폴백돼요.
  • --loki-guardrail-max-bytes: 단일 query_loki_logs 호출이 스캔할 수 있는 최대 바이트 (Loki의 index/stats API로 추정). 기본 100 GiB, 0이면 바이트 예산 점검 비활성화. GRAFANA_LOKI_GUARDRAIL_MAX_BYTES로 폴백돼요.
  • --loki-guardrail-max-range: 단일 query_loki_logs 호출의 최대 유효 시간 범위 (range-vector 기간 포함). 기본 24h, 0이면 범위 점검 비활성화. GRAFANA_LOKI_GUARDRAIL_MAX_RANGE로 폴백돼요.

가드레일 판정은 OTel 카운터(mcp_loki_guardrail_admitted_total, _would_block_total, _blocked_total, _fail_open_total)로도 내보내져요. shadow에서 enforce로 승격하기 전에 영향받는 집단의 규모를 재는 권장 방법이에요. Observability 문서 참고.

  • --dynamic-multi-org: 선택적 orgId 인자를 통해 도구 호출이 호출별로 Grafana 조직을 선택하게 해요. 기본은 꺼져 있어요. Multi-organization support 문서 참고.

쿼리 실행 없이 실행하기

--disable-query는 데이터소스에 쿼리를 실행하는 모든 도구를 제거하고, 메타데이터·발견 도구는 남겨둬요.

어시스턴트가 비싸거나 민감한 쿼리를 실행하지 않고도 데이터소스, 대시보드, 메트릭 이름, 라벨, 테이블 스키마 같은 것들이 무엇이 있는지 탐색할 수 있게 하고 싶을 때 써요 — 예를 들어 datasources:query는 없고 datasources:read만 있는 서비스 계정에서요.

플래그가 설정되면 다음 도구는 등록되지 않아요:

  • Prometheus: query_prometheus, query_prometheus_histogram
  • Loki: query_loki_logs, query_loki_patterns (query_loki_stats와 analyze_loki_labels는 로그 내용 대신 index를 읽으므로 등록 유지)
  • Elasticsearch와 OpenSearch, Quickwit: query_elasticsearch, query_quickwit
  • SQL 데이터소스: query_sql, query_influxdb
  • Graphite: query_graphite, query_graphite_density
  • CloudWatch: query_cloudwatch
  • Google Cloud Logging: query_cloud_logging
  • Pyroscope: query_pyroscope
  • Panels: run_panel_query

elasticsearch, quickwit, influxdb, runpanelquery 카테고리에는 그 외 다른 것이 없어서, 쿼리가 비활성화되면 도구를 아예 노출하지 않아요. list_prometheus_metric_names, list_loki_label_values, describe_sql_table, list_cloudwatch_metrics, list_cloud_logging_projects 같은 형제 도구는 계속 사용 가능해요.

이 플래그는 쿼리 도구와 grafana_api_request의 /api/ds/query로의 POST 경로를 막지만, 데이터소스로 가는 모든 라우트를 단속하지는 않아요. 읽기 전용 모드에서 grafana_api_request는 쿼리 도구가 활성화된 경우에만 /api/ds/query로의 POST를 허용해요 (raw-SQL 도구와 같은 게이트 — --enable-query가 덮어쓰지 않으면 --disable-write에 막혀요). 패널을 서버 측에서 렌더링하는 get_panel_image는 영향을 받지 않아요.

쿼리 실행과 읽기 전용 모드

raw-SQL 쿼리 도구(query_sql, query_influxdb)는 쿼리를 필터 없이 데이터소스에 보내므로, 데이터소스 자격 증명이 허용하면 무엇이든 써요. 읽기 전용 모드는 다른 쓰기 도구와 함께 이 도구들도 제거해요.

--enable-query는 이 도구들을 다시 넣어요. 데이터소스 자격 증명이 읽기 전용임이 알려져 있고, 그 외에는 읽기 전용인 서버에서 쿼리 실행을 원할 때 써요. 다른 어떤 쓰기 도구도 다시 활성화하지 않고, 항상 우선하는 --disable-query와 함께 쓰면 효과가 없어요.

Flags Safe query tools Raw-SQL query tools
(none) Registered Registered
--disable-write Registered Not registered
--disable-write --enable-query Registered Registered
--disable-query Not registered Not registered
--disable-query --enable-query Not registered Not registered

읽을 수 있는 Loki 스트림 제한하기

  • --loki-enforced-matchers: 모든 네이티브 Loki 쿼리에 AND로 결합되는 LogQL 라벨 매처라서, 읽을 수 있는 로그 스트림을 제한해요 (예: environment=~"prod|staging"). 파싱할 수 없는 쿼리는 거부되고, 설정돼 있는 동안에는 VictoriaLogs 데이터소스가 거부돼요.
  • --loki-label-enumeration-fallback: 음의 enforced matcher로 스코프할 수 없을 때 라벨 열거 도구가 하는 동작 — reject(기본) 또는 unfiltered.

경고: 강제는 Loki 쿼리 도구에만 적용돼요. 다른 도구가 강제 백엔드를 거치지 않는 경로로 Loki 로그 데이터에 도달할 수 있으니, 제한이 유지되려면 그것들도 꺼야 해요:

  • --disable-api: grafana_api_request가 Loki 데이터소스 프록시를 직접 쿼리할 수 있어요 (완전한 우회).
  • --disable-rendering: get_panel_image가 Loki 패널을 서버 측에서 렌더링해, 제한 없는 로그 줄이 담긴 이미지를 만들어요.
  • --disable-sift: Sift 조사가 모든 스트림에 걸쳐 Loki 로그를 서버 측에서 분석해요.
  • --disable-assistant: ask_assistant가 Grafana Assistant에 위임하는데, 이 어시스턴트가 모든 스트림의 Loki를 서버 측에서 읽어요. 쓰기 도구가 활성화됐을 때만 등록되므로, --disable-write도 이것을 닫아요.

서버는 시작 시 아직 활성화되어 있는 각 항목을 이름 짚어 경고를 로그로 남겨요. run_panel_query는 안전해요. UID에서 해석한 데이터소스의 실제 타입으로 라우팅하므로, 패널이나 호출자가 다른 datasourceType을 선언해도 Loki 데이터소스는 항상 강제 쿼리 경로로 실행돼요. Tempo 도구는 Loki 로그가 아닌 추적만 노출해서 우회가 아니에요. 대시보드 스냅샷(--disable-snapshot)은 강제 밖에서 캡처된 로그 패널 데이터를 임베드할 수 있어요.

읽기 전용 모드로 실행하기

--disable-write는 Grafana에 대한 쓰기 작업을 막아요. 읽기 전용 서비스 계정, 더 안전한 프로덕션 어시스턴트에서 쓰거나, 우발적 변경을 피하려고 써요. 데이터소스를 통해 쓸 수 있는 raw-SQL 쿼리 도구도 제거해요 — 유지하려면 앞 섹션의 --enable-query를 참고하세요.

활성화되면 다음 쓰기가 비활성화돼요.

Dashboard tools

  • update_dashboard

Folder tools

  • create_folder

Incident tools

  • create_incident
  • add_activity_to_incident
  • update_incident

Alerting tools

  • alerting_manage_rules (create, update, delete)

OnCall tools

  • update_alert_group

Annotation tools

  • create_annotation
  • update_annotation
  • delete_annotation

Sift tools

  • find_error_pattern_logs (investigations 생성)
  • find_slow_requests (investigations 생성)

Snapshot tools

  • create_snapshot
  • delete_snapshot

Agent Observability tools

  • agento11y_manage_evaluators (upsert, delete, fork, test evaluators)
  • agento11y_manage_eval_rules (create, update, delete, preview eval rules and guards)
  • agento11y_manage_eval_collections (save and delete saved conversations; create, update, delete collections; add/remove collection members)
  • agento11y_manage_experiments (update and cancel experiments)
  • agento11y_manage_test_suites (create and update test suites; create and publish versions; upsert and delete test cases)

읽기 작업(쿼리, 목록, 검색)은 계속 사용 가능해요.

Grafana용 클라이언트 TLS 구성하기

  • --tls-cert-file: Grafana로의 mTLS용 클라이언트 인증서.
  • --tls-key-file: 클라이언트 개인 키.
  • --tls-ca-file: Grafana 서버 인증서를 검증하기 위한 CA 인증서.
  • --tls-skip-verify: TLS 검증 건너뛰기 (비보안; 테스트 전용).

streamable-http용 서버 TLS 구성하기

이 플래그들은 MCP HTTP 서버(MCP 클라이언트와 mcp-grafana 사이)를 보호하지, mcp-grafana에서 Grafana로 가는 연결은 보호하지 않아요:

  • --server.tls-cert-file: HTTPS용 서버 인증서.
  • --server.tls-key-file: 서버 개인 키.

버전 정보 출력하기

  • --version: 버전을 출력하고 종료.

더 알아보기 (Learn more)