# MCP Access with Streamable-HTTP MCP Server Teleport can provide secure access to MCP servers with streamable-HTTP transport. This guide shows you how to: - Enroll a MCP server with streamable-HTTP transport in your Teleport cluster. - Connect to the streamable-HTTP MCP server via Teleport. ## How it works ![How it works](/docs/assets/images/architecture-http-cec4ca4b0bbf6bec68e5bb9be677d05d.svg) 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. Teleport proxies the MCP protocol 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.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 `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 Application Service. * The endpoint of the streamable-HTTP MCP server MCP endpoint. ## Step 1/3. Configure the Teleport Application Service You can update an existing Application Service or create a new one to enable the MCP server. **Update an existing service** If you already have an existing Application Service running, you can add a MCP server in your YAML configuration: ``` app_service: enabled: true apps: - name: "everything" uri: "mcp+MCP endpoint" labels: env: dev description: ``` **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 file at `/etc/teleport.yaml` with the following content: ``` version: v3 teleport: join_params: token_name: "/tmp/token" method: token proxy_server: "teleport.example.com:443" auth_service: enabled: false proxy_service: enabled: false ssh_service: enabled: false app_service: enabled: true apps: - name: "everything" uri: "mcp+MCP endpoint" labels: env: dev description: ``` Replace teleport.example.com:443 with the host and port of your Teleport Proxy Service or Teleport Cloud tenant, and replace the MCP details with the MCP server you desire to run. #### 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 ---------- --------------------- --------------- ---------- everything everything MCP server Streamable HTTP env=dev ``` To show configurations for your MCP client to connect: ``` $ tsh mcp config everything Found MCP servers: everything Here is a sample JSON configuration for launching Teleport MCP servers: { "mcpServers": { "teleport-mcp-everything": { "command": "/path/to/tsh", "args": ["mcp", "connect", "everything"] } } } 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-everything` MCP server with allowed tools appear in your MCP client. ## Connect with streamable-HTTP client The `tsh mcp connect` command demonstrated above can be used by any stdio MCP client to start a MCP session, and Teleport automatically handles the transport conversion to the remote MCP server. However, if you wish to connect to the MCP server in streamable-HTTP transport, you can start a local proxy that creates an authenticated tunnel to the remote MCP server: ``` $ tsh proxy mcp everything -p 8888 Proxying connections to everything on 127.0.0.1:8888 ``` Then, connect to the MCP server locally with a MCP client that supports streamable-HTTP, for example: ``` $ npx @modelcontextprotocol/inspector --transport http --cli --method tools/list http://127.0.0.1:8888 ``` Alternatively, instead of `tsh`, you can use [Teleport Connect](https://goteleport.com/docs/connect-your-client/teleport-clients/teleport-connect.md#connecting-to-an-mcp-server) which can maintain the local proxies in the background. ## 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). - [JWT Authentication to MCP server](https://goteleport.com/docs/enroll-resources/mcp-access/jwt.md) - [Register MCP servers dynamically](https://goteleport.com/docs/enroll-resources/mcp-access/dynamic-registration.md) - Configuration and CLI [reference](https://goteleport.com/docs/enroll-resources/mcp-access/reference.md).