Skip to main content

Connect a GitHub MCP Server to Teleport

Report an issue with this page

This guide demonstrates how to run a GitHub MCP server and connect it via Teleport.

How it works​

The GitHub MCP server uses a personal access token of a service account to access GitHub and mcp-proxy exposes it to Teleport 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 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.

  • Access to a service account to your GitHub organization.
  • A host to run the MCP server that is reachable by the Teleport Application Service.
  • Running Teleport Application Service.
  • A Teleport user with sufficient permissions (e.g. role mcp-user) to access MCP servers.

Step 1/3. Create a personal access token​

Log in to GitHub using your service account. Navigate to Settings > Developer Settings > Personal access tokens, then click Generate new token.

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

Once the token is created, save it for use in the next step.

Step 2/3. 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://localhost: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 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.

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

Connect to GitHub without 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​