{"token_count": 2401}

# Connect a GitHub MCP Server to Teleport

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

In this guide, you will:

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

## How it works

The [GitHub MCP server](https://github.com/github/github-mcp-server) uses a personal access token of a service account to access GitHub and [`mcp-proxy`](https://github.com/sparfenyuk/mcp-proxy) exposes it to the Teleport Application Service over a streamable-HTTP endpoint by translating the original transport. Teleport proxies all client requests to the server, which interacts with GitHub using the permissions granted to the service account.

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

     **Mac/Linux**

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

     **Windows - Powershell**

     ```
     $ $TELEPORT_DOMAIN = "teleport.example.com:443"
     $ $TELEPORT_VERSION = (Invoke-RestMethod -Uri "https://${TELEPORT_DOMAIN}/v1/webapi/find").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/single-machine.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
     ```

* Access to a service account to your GitHub organization.

* 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.

* A GitHub personal access token, which requires manual preparation in the GitHub Web UI. To create a token, follow the [GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token).

  ---

  DANGER

  When creating the token, grant only the minimal permissions needed. Avoid broad scopes such as write or admin access unless absolutely required.

  ---

## Step 1/2. Run the GitHub MCP server

First, install `mcp-proxy` on the host that will run the MCP server:

```
Option 1: With uv (recommended)
$ uv tool install mcp-proxy

Option 2: With pipx (alternative)
$ pipx install mcp-proxy
```

Now start the GitHub MCP server behind `mcp-proxy`, using the personal access token github\_personal\_access\_token:

```
$ mcp-proxy \
  --host MCP_HOST  --port 8000 \
  -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN=github_personal_access_token \
  ghcr.io/github/github-mcp-server
```

Replace MCP\_HOST with the hostname of the host machine running the MCP server. The host must be reachable by the Teleport Application Service.

After starting, `mcp-proxy` exposes a streamable-HTTP endpoint at `http://MCP_HOST:8000/mcp`.

## Step 2/2. 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 GitHub MCP server:

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

```

Restart the Application Service.

**tctl**

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

```
# app-github-mcp.yaml
kind: app
version: v3
metadata:
  name: github-mcp
  labels:
    env: dev
    service: github
spec:
  uri: "mcp+http://MCP_HOST:8000/mcp"

```

Create the `app` resource with:

```
$ tctl create -f app-github-mcp.yaml
```

**Terraform**

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

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

  spec = {
    uri = "mcp+http://MCP_HOST:8000/mcp"
  }
}

```

Apply the configuration:

```
$ terraform apply
```

---

MCP ENDPOINT PATHS

If the MCP endpoint includes a path such as `/mcp` or `/sse`, it can be included in the `uri`. For streamable-HTTP servers, Teleport uses the path in `uri` when an MCP client requests `/`. When the client requests a different path, Teleport forwards the request to that path instead of appending it to the path in `uri`. For example, if `uri` is `mcp+https://localhost:3000/mcp` and the MCP client requests `/.well-known/oauth-authorization-server`, Teleport forwards the request to `/.well-known/oauth-authorization-server`, not `/mcp/.well-known/oauth-authorization-server`.

---

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: github-mcp-readonly
spec:
  allow:
    app_labels:
      'service': 'github'
    mcp:
      tools:
      - ^(get|search|list)_.*$
      - ^.*_read$

```

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 github-mcp --client-config claude
```

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

![GitHub Claude](/docs/assets/images/github-claude-3bde3ffece6e9207083cd8893c5b0ab6.png)

## Connect to GitHub without a service account

Instead of using a service account's personal access token, you can require each Teleport user to supply their own token from the client side. This removes the need to run an `mcp-proxy`, allowing you to use the official MCP server directly when configuring your MCP server:

```
app_service:
  enabled: "yes"
  apps:
  - name: "github-mcp"
    uri: "mcp+https://api.githubcopilot.com/mcp/"
    labels:
      env: dev
      service: github

```

When configuring the MCP client, use your own personal access token as a bearer token for the `Authorization` header:

```
$ tsh mcp config github-mcp --client-config claude --header "Authorization: Bearer github_personal_access_token"
```

## Next steps

- 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 [github-mcp-server](https://github.com/github/github-mcp-server).
- Connect your [MCP clients](https://goteleport.com/docs/connect-your-client/model-context-protocol/mcp-access.md).