Deploy and Host Grafana MCP on Railway

Grafana MCP is a Model Context Protocol server that exposes a Grafana instance to LLM clients as tools — dashboards, datasources, Prometheus and Loki queries, alert rules, incidents and Sift investigations. This template deploys the MCP server behind an nginx bearer-token auth gateway, so an LLM can safely talk to your Grafana from a publicly reachable endpoint.

About Hosting Grafana MCP

The MCP server itself has no notion of per-client credentials, so this template places an nginx service in front that validates every request against a comma-separated list of bearer tokens before proxying to the MCP over Railway's private network. Keys can be issued and revoked one at a time without touching the MCP service. The MCP can be pointed at any Grafana instance — a Grafana service running in the same Railway project, Grafana Cloud, or a self-hosted instance — and reaches it over GRAFANA_URL, so Grafana itself never has to be public either.

Common Use Cases

Give Claude, Cursor, or other MCP clients read-only access to production dashboards and metrics
Let an agent investigate an incident by querying Prometheus and Loki, and reading alert rules, without handing it Grafana admin credentials
Retrieval-Augmented Generation (RAG) over your observability data
Secure sharing of a Grafana tool endpoint with teammates via per-person bearer tokens

Dependencies for Grafana MCP Hosting

The template ships the nginx auth gateway and the Grafana MCP server. You bring the Grafana: add a Grafana service to the same project after deploy, or point the MCP at any external instance via GRAFANA_URL.

Deployment Dependencies

A reachable Grafana base URL, e.g. http://grafana.railway.internal:3000 for a Grafana service in the same project, or https://your-org.grafana.net.
Grafana credentials: a service account token (recommended), or a username and password.

Implementation Details

Architecture Components

This template deploys two services:

Gateway: nginx:alpine with a public Railway domain. Validates Authorization: Bearer against API_KEYS and proxies the rest to the MCP over Railway's private network with streaming-friendly settings.
Grafana MCP: the official grafana/mcp-grafana image (pinned to 1.3.0) running in streamable-HTTP transport mode. No public domain — reachable only via grafana-mcp.railway.internal:8000.

Authentication

Clients must send Authorization: Bearer where `` is one of the comma-separated entries in API_KEYS. Generate keys with openssl rand -hex 32; rotating is a variable update plus a gateway redeploy, and the MCP service is untouched.

Defense-in-depth is provided by ACCESS_MODE=restricted on the MCP, which passes --disable-write so no tool can create or modify dashboards, alert rules, annotations or incidents even if a key leaks.

A third layer is optional: set MCP_GRAFANA_SERVER_TOKEN on the MCP service and the matching MCP_SERVER_TOKEN on the gateway. The MCP server then requires that token itself and rejects anything that did not arrive through the gateway.

For MCP clients that cannot send an Authorization header on their first request, set PATH_KEY_AUTH=true on the gateway to also accept the same key as a path segment at /k//mcp. It is off by default, since a key in a URL can be recorded by logs outside your control.

Service Configuration

MCP endpoint: https:///mcp (streamable-HTTP, "type": "http").
Grafana: set GRAFANA_URL on the MCP service, plus either GRAFANA_SERVICE_ACCOUNT_TOKEN or both GRAFANA_USERNAME and GRAFANA_PASSWORD. If you add a Grafana service to the same project, you can reference ${{Grafana.GF_SECURITY_ADMIN_USER}} and ${{Grafana.GF_SECURITY_ADMIN_PASSWORD}} directly. The service refuses to start with neither auth method set.
Access mode: ACCESS_MODE=restricted (default) for read-only Grafana access, or unrestricted for full read/write — recommended only for dev or throwaway instances.
Tool allowlist: ENABLED_TOOLS narrows what the MCP exposes, e.g. loki,prometheus,dashboard. All categories are enabled by default.

License Information

Apache-2.0 (mcp-grafana) + BSD-2-Clause (nginx). The template itself is MIT.

Why Deploy Grafana MCP on Railway?

The auth gateway, private-network wiring, and streamable-HTTP passthrough are all pre-configured — giving an MCP client secure access to Grafana is a one-click deploy instead of a custom nginx and reverse-proxy project.

Notes

Source repo: https://github.com/FournyP/grafana-mcp-railway-template
Upstream MCP server: https://github.com/grafana/mcp-grafana
Model Context Protocol: https://modelcontextprotocol.io