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

MCP Access Getting Started Guide

Report an Issue

Teleport can provide secure connections to your MCP (Model Context Protocol) servers while improving both access control and visibility.

This guide shows you how to:

  • Enroll the Teleport demo MCP server in your Teleport cluster.
  • Connect to the MCP server via Teleport.

How it works​

The Teleport Application Service includes a built-in demo MCP server designed to showcase how MCP access works.

Users can configure their MCP clients such as Claude Desktop to start an MCP server using tsh. Once successfully authorized, tsh establishes a session with the Application Service.

Once the session is established, the Application Service starts the in-memory demo MCP server. Teleport then proxies the connection between the client and the remote MCP server, applying additional role-based access controls such as filtering which tools are available to the user. While proxying, Teleport also logs MCP protocol requests as audit events, providing visibility into user activity.

Prerequisites​

  • A running Teleport (v18.1.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 tctl and tsh clients.

    Installing tctl and tsh clients

    1. Determine the version of your Teleport cluster. The tctl and tsh clients 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 tctl and tsh clients:

      Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:

      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.

  • A host, e.g., an EC2 instance, where you will run the Teleport Applications Service.
  • Check that you can connect to your Teleport cluster and verify that you can run tctl and tsh commands using your current credentials.

    1. Assign teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and [email protected] to your Teleport username.

    2. Authenticate to your Teleport cluster. This depends on whether your shell is interactive or not.

      In an interactive shell: Run the following command. By default, this triggers a multi-factor authentication prompt:

      tsh login --proxy=teleport.example.com --user=[email protected]
      tctl status
      Cluster  teleport.example.com
      Version  19.0.0-dev
      CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

      On non-interactive environments: If you are running tsh and tctl as an AI agent, in a CI/CD environment, or similar, make sure the TELEPORT_IDENTITY_FILE environment variable is assigned to a valid file path with credentials for your cluster. tsh and tctl read the file path from the environment variable and do not require a separate authentication step. If there is no identity file available, we recommend that you set up Machine ID to provision one automatically.

      When executing tctl commands with an identity file, you must pass the --auth-server flag to provide the Teleport Auth Service address, which is not included in the identity file. If you provide the Proxy Service address, tctl connects to the Proxy Service, which forwards traffic to and from the Teleport Auth Service. Update 443 to 3025 if you are contacting the Auth Service directly with tctl:

      tctl status --auth-server=teleport.example.com:443

      For tsh commands that read an identity file, you must pass the --proxy flag, which points tsh to the address of the Teleport Proxy Service:

      tsh status --proxy=teleport.example.com

      Ensure client commands can access your identity file. Replace path/to/identity/file with the path to your identity file:

      export TELEPORT_IDENTITY_FILE="${TELEPORT_IDENTITY_FILE:-path/to/identity/file}"

      Add the --auth-server or --proxy flags to all subsequent tctl and tsh commands.

    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Step 1/3. Configure the Teleport Application Service​

You can update an existing Application Service or create a new one to enable the demo MCP server.

Update an existing service​

If you already have an existing Application Service instance running, you can enable the demo MCP server by adding the following in your YAML configuration:

app_service:
  enabled: true
+  mcp_demo_server: true
...

Now restart the Application Service and skip to Step 2.

Create a new service​

If you have not deployed the Teleport Application Service, you will need to run it on the host you prepared before following this guide.

Get a join token​

The Application Service requires a valid join token to join your Teleport cluster. Run the following tctl command and save the token output in /tmp/token on the server that will run the Application Service:

tctl tokens add --type=app --format=text
abcd123-insecure-do-not-use-this
Alternative methods

For users with a lot of infrastructure in AWS, or who might create or recreate many instances, consider alternative methods for joining new EC2 instances running Teleport:

Install the Teleport Application Service​

Install Teleport on the host where you will run the Teleport Application Service:

To install Teleport binaries on your Linux server, the recommended installation method is the cluster install script. This script is served by your Teleport cluster's Proxy Service and automatically selects the correct version, edition, and installation mode to match your cluster.

  1. Remove any existing Teleport binaries on your system:

    sudo rm -f /usr/local/bin/{tsh,teleport,tctl,tbot,fdpass-teleport,teleport-update}

  2. Assign teleport.example.com:443 to your Teleport cluster hostname and port, but not the scheme (https://).

  3. Run your cluster's install script:

    curl "https://teleport.example.com:443/scripts/install.sh" | sudo bash

Configure the Teleport Application service​

On the host where you will run the Teleport Application Service, create a configuration file:

sudo teleport configure \   -o file \   --roles=app \   --proxy=teleport.example.com:443 \   --token=/tmp/token \   --mcp-demo-server

The command will generate an Application Service configuration to proxy the demo MCP server and save the configuration to /etc/teleport.yaml.

Start the Teleport Application Service​

Start the Application Service. The instructions depend on how you installed the Application Service and whether your system supports systemd:

Configure the Application Service to start automatically when the host boots up by creating a systemd service for it. On the host where you will run the Application Service, enable and start Teleport:

sudo systemctl enable teleport
sudo systemctl start teleport

You can check the status of the Application Service with systemctl status teleport and view its logs with journalctl -fu teleport.

Step 2/3. Configure your Teleport user​

In this step, you will grant your Teleport user access to all MCP servers and their MCP tools.

If you have an existing Teleport user, assign the preset role mcp-user to that user. The mcp-user role allows access to all MCP servers and their tools:

kind: role
version: v8
metadata:
  description: Access to MCP servers
  labels:
    teleport.internal/resource-type: preset
  name: mcp-user
spec:
  allow:
    app_labels:
      'teleport.internal/app-sub-kind': 'mcp'
    mcp:
      tools:
      - '*'

Alternatively, add the above allow permissions to an existing Teleport role.

tip

You can also create and edit roles using the Web UI. Go to Access -> Roles and click Create New Role or pick an existing role to edit.

Step 3/3. Connect​

Log in to Teleport with the user we've just created, my_user:

tsh login --proxy=teleport.example.com:443 --user=my_user

Now we can inspect available MCP servers:

tsh mcp ls
Name              Description                                                       Type  Labels----------------- ----------------------------------------------------------------- ----- ------teleport-mcp-demo A demo MCP server that shows current user and session information stdio

To show configurations for your MCP client to connect:

tsh mcp config teleport-mcp-demo
Found MCP servers:everything
Here is a sample JSON configuration for launching Teleport MCP servers:{  "mcpServers": {    "teleport-mcp-teleport-mcp-demo": {      "command": "/path/to/tsh",      "args": ["mcp", "connect", "teleport-mcp-demo"]    }  }}
Tip: You can use this command to update your MCP servers configuration file automatically.- For Claude Desktop, use --client-config=claude to update the default configuration.- For Cursor, use --client-config=cursor to update the global MCP servers configuration.In addition, you can use --client-config=<path> to specify a config file location that is compatible with the "mcpServers" mapping.For example, you can update a Cursor project using --client-config=<path-to-project>/.cursor/mcp.json

Once your MCP client configuration is updated, you will see teleport-mcp-teleport-mcp-demo MCP server with allowed tools appear in your MCP client.

The demo MCP server consists of several tools:

  • teleport_user_info: Shows basic information about your Teleport user.
  • teleport_session_info: Shows information about this MCP session.
  • teleport_demo_info: Shows information about this Teleport Demo MCP server.

You can interact with it using sample questions like "can you show some details on this Teleport demo?":

Demo Server Claude Desktop

Next Steps​

Learn more about protecting MCP servers with Teleport in the following topics: