# Connect a Grafana MCP Server to Teleport

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](https://github.com/grafana/mcp-grafana) 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](https://grafana.com/docs/grafana/latest/setup-grafana/configure-access/configure-authentication/jwt/).

## Prerequisites

- A running Teleport (v18.3.0 or higher) cluster. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md).

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

     **Mac**

     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.

     ---

     **Windows - Powershell**

     ```
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     Unzip the archive and move the `tsh` client to your %PATH%
     NOTE: Do not place the `tsh` client in the System32 directory, as this can cause issues when using WinSCP.
     Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```

     **Linux**

     All of the Teleport binaries in Linux installations include the `tsh` client. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation.md).

     ```
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     Teleport binaries have been copied to /usr/local/bin
     ```

* 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](https://goteleport.com/docs/enroll-resources/mcp-access/getting-started.md).
* 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:

**mcp-grafana binary**

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

**Docker**

Run the MCP server in streamable-HTTP transport. Assign GRAFANA\_URL to the URL of your Grafana instance:

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

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:

**Static configuration**

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.

**tctl**

Create an `app` resource definition file named `app-grafana-mcp.yaml`. Replace MCP\_HOST with the host running the Grafana MCP server:

```
# app-grafana-mcp.yaml
kind: app
version: v3
metadata:
  name: grafana-mcp
  labels:
    env: dev
    service: grafana
spec:
  uri: "mcp+http://MCP_HOST:8000/mcp"
  rewrite:
    headers:
    - name: "X-Grafana-API-Key"
      value: "{{internal.jwt}}"

```

Create the `app` resource with:

```
$ tctl create -f app-grafana-app.yaml
```

**Terraform**

Create a `teleport_app` resource in terraform. Replace MCP\_HOST with the host running the Grafana MCP server:

```
resource "teleport_app" "grafana" {
  version = "v3"
  metadata = {
    name = "grafana"
    labels = {
      "teleport.dev/origin" = "dynamic"
      "env"                 = "dev"
      "service"             = "grafana"
    }
  }

  spec = {
    uri = "mcp+http://MCP_HOST:8000/mcp"
    rewrite = {
      headers = [{
        name  = "X-Grafana-API-Key"
        value = "{{internal.jwt}}"
      }]
    }
  }
}

```

Apply the configuration:

```
$ terraform apply
```

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 interact with Grafana via Teleport in your MCP clients:

![Grafana Claude](/docs/assets/images/grafana-claude-07a5a4eed6fe067f46952ce8e03dd0d1.png)

## 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**:

![Grafana Service Account](/docs/assets/images/grafana-create-sa-5a6150f88b8732e1679afbb20610e9e8.png)

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

- Read more on accessing Grafana through Teleport with [JWT authentication](https://goteleport.com/docs/enroll-resources/application-access/jwt/grafana.md).
- Review [Enroll a Streamable-HTTP MCP Server](https://goteleport.com/docs/enroll-resources/mcp-access/enrolling-mcp-servers/streamable-http.md).
- See the [dynamic registration](https://goteleport.com/docs/enroll-resources/mcp-access/dynamic-registration.md) guide.
- Learn more about [mcp-grafana](https://github.com/grafana/mcp-grafana).
- Connect your [MCP clients](https://goteleport.com/docs/connect-your-client/model-context-protocol/mcp-access.md).