Skip to main content
Version: 19.x (unreleased)

Connect a Grafana MCP Server to Teleport

Report an Issue

Teleport can provide secure access to MCP servers via Teleport Application Service.

In this guide, you will:

  1. Configure your Grafana service for access by the MCP server.
  2. Run the Grafana MCP Server.
  3. Enroll the MCP server into your Teleport cluster and connect to it.

How it works​

The Grafana MCP server forwards JWT tokens signed by Teleport to access Grafana and runs on a local endpoint reachable by the Teleport Application Service. Teleport proxies all client requests to the server, which interacts with Grafana using permissions mapped by JWT authentication.

Prerequisites​

  • A running Teleport (v18.3.0 or higher) cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tsh client.

    Installing tsh client

    1. Determine the version of your Teleport cluster. The tsh client must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

      TELEPORT_DOMAIN=teleport.example.com:443
      TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"

    2. Follow the instructions for your platform to install tsh client:

      Download the signed macOS .pkg installer for Teleport, which includes the tsh client:

      curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg

      In Finder double-click the pkg file to begin installation.

      danger

      Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

  • Ability to configure your Grafana instance.
  • A host to run the MCP server that is reachable by the Teleport Application Service.
  • A running Teleport Application Service. If you have not yet done this, follow the Getting Started guide.
  • A Teleport user with sufficient permissions (e.g. role mcp-user) to access MCP servers.

Step 1/3. Configure JWT authentication in Grafana​

Add an auth.jwt section in Grafana’s main configuration file. Replace teleport.example.com with the domain name of your Teleport cluster:

[auth.jwt]
enabled = true

# HTTP header to look into to get a JWT token.
header_name = Authorization

# JSON Web Key Set (JWKS) URL from your Teleport cluster.
jwk_set_url = https://teleport.example.com/.well-known/jwks.json

# Teleport username can be found in "sub" or "username" claims.
username_claim = sub

# Map Teleport users to Grafana organization roles based on their Teleport
# roles. Adjust accordingly.
#
# In this example, if the user's Teleport role list (the "roles" claim) contains
# "editor", assign them the Grafana "Editor" role. All other users get the
# "Viewer" role.
#
# Teleport user traits are also available in the "traits" claim and can be
# used in expressions in the same way as roles.
role_attribute_path = contains(roles[*], 'editor') && 'Editor' || 'Viewer'

# auto-create users if they are not already matched.
auto_sign_up = true

Restart your Grafana instance after updating the config.

Step 2/3. Run the Grafana MCP server​

The Grafana MCP Server can be run either as a compiled binary or via the official Docker image:

Run the MCP server in streamable-HTTP transport. Assign GRAFANA_URL to the URL of your Grafana instance and MCP_HOST to the hostname of the host machine running the MCP server:

export GRAFANA_URL=GRAFANA_URL
./mcp-grafana --transport streamable-http --address MCP_HOST:8000

The Grafana MCP Server now exposes a streamable-HTTP endpoint at http://MCP_HOST:8000/mcp.

Step 3/3. Connect via Teleport​

You can register an MCP application in Teleport by defining it in your Teleport Application Service configuration, or by using dynamic registration with tctl or Terraform:

Replace MCP_HOST with the host running the Grafana MCP server:

app_service:
  enabled: "yes"
  apps:
  - name: "grafana-mcp"
    uri: "mcp+http://MCP_HOST:8000/mcp"
    labels:
      env: dev
      service: grafana
    rewrite:
      headers:
      - "X-Grafana-API-Key: {{internal.jwt}}"

Restart the Application Service.

The header rewrite configuration above will replace the {{internal.jwt}} template variable with a Teleport-signed JWT token in each request. The Grafana MCP server will use this token as a bearer token in "Authorization" header when connecting to Grafana.

To grant access to the MCP server and all its tools, assign the preset mcp-user role to your Teleport user.

Optionally, you can limit which MCP tools the user can access by adjusting the mcp.tools list in their role. For example:

kind: role
version: v8
metadata:
  name: grafana-mcp-readonly
spec:
  allow:
    app_labels:
      'service': 'grafana'
    mcp:
      tools:
      - ^(get|query|list|search|find)_.*$

Now wait until the application appears in tsh mcp ls, then configure your MCP clients to access the MCP server, for example:

tsh mcp config grafana-mcp --client-config claude

After configuring your MCP client, you will find Grafana-related tools from teleport-mcp-grafana-mcp. You can now use these tools to interactive with Grafana via Teleport in your MCP clients:

Connect to Grafana using a service account​

Instead of accessing Grafana with JWT authentication, you can also use a service account.

Navigate to Administrators > Users and Accounts > Service Accounts, and then click Create Service Account:

Assign the Viewer role to keep the service account limited to read-only access.

After the service account is created, click Add service account token to generate a new token. Use this token SERVICE_ACCOUNT_TOKEN when starting the Grafana MCP server:

docker run -d -p 8000:8000 \  -e GRAFANA_URL=GRAFANA_URL \  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=SERVICE_ACCOUNT_TOKEN \  mcp/grafana --transport streamable-http

Lastly, you don’t need to configure any header rewrites in the Teleport application:

app_service:
  enabled: "yes"
  apps:
  - name: "grafana-mcp"
    uri: "mcp+http://MCP_HOST:8000/mcp"
    labels:
      env: dev
      service: grafana

Next steps​