# MCP Access Getting Started Guide 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 ![How it works](/docs/assets/images/architecture-demo-f22808729eaff4ee8611a5301d3d8304.svg) 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](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md). - 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: **Mac** 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. --- **Windows - Powershell** ``` $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip Unzip the archive and move the `tctl` and `tsh` clients to your %PATH% NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP. Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\) instead. ``` **Linux** All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. 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 ``` * A host, e.g., an EC2 instance, where you will run the Teleport Applications Service. ## 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 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. **Create a new service** #### 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: - [Configure Teleport to Automatically Enroll EC2 instances](https://goteleport.com/docs/enroll-resources/auto-discovery/servers/ec2-discovery.md) - [Joining Teleport Services via AWS IAM Role](https://goteleport.com/docs/enroll-resources/agents/aws-iam.md) - [Joining Teleport Services via AWS EC2 Identity Document](https://goteleport.com/docs/enroll-resources/agents/aws-ec2.md) #### Install the Teleport Application Service Install Teleport on the host where you will run the Teleport Application Service: To install a Teleport Agent on your Linux server: The recommended installation method is the cluster install script. It will select the correct version, edition, and installation mode for your cluster. 1. Assign teleport.example.com:443 to your Teleport cluster hostname and port, but not the scheme (https\://). 2. 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 Configure the Application Service to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed the Application Service. **Package Manager** On the host where you will run the Application Service, enable and start Teleport: ``` $ sudo systemctl enable teleport $ sudo systemctl start teleport ``` **TAR Archive** On the host where you will run the Application Service, create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport: ``` $ sudo teleport install systemd -o /etc/systemd/system/teleport.service $ 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. **Configure an existing user** 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. **Create a new user** Create a new local user called my\_user with MCP access: ``` $ tctl users add my_user --roles=mcp-user ``` --- 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= to specify a config file location that is compatible with the "mcpServers" mapping. For example, you can update a Cursor project using --client-config=/.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](/docs/assets/images/demo-server-claude-desktop-23f0e3ce11ff74bfd99344a0ad025741.png) ## Next Steps Learn more about protecting MCP servers with Teleport in the following topics: - [MCP Access Control](https://goteleport.com/docs/enroll-resources/mcp-access/rbac.md). - Configuration and CLI [reference](https://goteleport.com/docs/enroll-resources/mcp-access/reference.md). - Audit events [reference](https://goteleport.com/docs/reference/deployment/monitoring/audit.md#event-types).