# Access MCP Servers with Teleport This guide explains how to configure MCP clients to access MCP servers served by Teleport. ## 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 `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: **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\) 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.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 ``` * Teleport MCP Access configured. Configure MCP Access - [Quick-start with demo MCP server](https://goteleport.com/docs/enroll-resources/mcp-access/getting-started.md). - [MCP Access with Stdio MCP Server](https://goteleport.com/docs/enroll-resources/mcp-access/enrolling-mcp-servers/stdio.md) ## Step 1/2. Configure MCP clients First, sign in into your Teleport cluster using `tsh login`, assigning teleport.example.com to the web address of the Teleport Proxy Service in your cluster: ``` $ tsh login --proxy=teleport.example.com --user=myuser@example.com ``` You can now list the available MCP servers that you can use: ``` $ tsh mcp ls Name Description Type Labels -------------- ------------------------------------------ ----- -------------------- fs Filesystem MCP Server stdio env=prod mcp-everything This MCP server attempts to exercise al... stdio env=dev,sandbox=true ``` The MCP client configuration can be created using the `tsh mcp config` command. You can choose which servers to configure by using the `--labels` flag to filter by labels or by specifying `--all`, which will configure all MCP servers you have access to. This command can either generate a configuration file (using the `mcpServers` format) for manual MCP client updates or automatically update the MCP client configuration. **Claude Desktop** `tsh` can automatically update the Claude Desktop MCP configuration file to include Teleport's configuration: ``` $ tsh mcp config --all --client-config=claude Found MCP servers: fs mcp-everything Updated client configuration at: ~/Library/Application Support/Claude/claude_desktop_config.json Teleport MCP servers will be prefixed with "teleport-mcp-" in this configuration. You may need to restart your client to reload these new configurations. If you encounter a "disconnected" error when tsh session expires, you may also need to restart your client after logging in a new tsh session. ``` You can also provide a custom path for your Claude Desktop MCPs configuration: ``` $ tsh mcp config --all --client-config=/path/to/config.json ``` After updating the configuration, you need to restart the Claude Desktop app before using the newly added MCPs. **Cursor** `tsh` can automatically update the Global Cursor MCP servers to include Teleport's configuration: ``` $ tsh mcp config --all --client-config=cursor Found MCP servers: fs mcp-everything Updated client configuration at: /your/home/path/.cursor/mcp.json Teleport MCP servers will be prefixed with "teleport-mcp-" in this configuration. You may need to restart your client to reload these new configurations. If you encounter a "disconnected" error when tsh session expires, you may also need to restart your client after logging in a new tsh session. ``` You can also update a Cursor project MCP servers by providing the path to the file: ``` $ tsh mcp config --all --client-config=/path/to/project/.cursor/mcp.json ``` **Others** Currently, `tsh` only supports generating the `mcpServers` format and some client-specific formats. Running the config command without any specific options will output configuration used to start Teleport's STDIO MCP server. You can use this as a base and modify it to suit your MCP client needs. ``` $ tsh mcp config --all Found MCP servers: fs mcp-everything Here is a sample JSON configuration for launching Teleport MCP servers: { "mcpServers": { "teleport-mcp-fs": { "command": "tsh", "args": ["mcp", "connect", "fs"] }, "teleport-mcp-mcp-everything": { "command": "tsh", "args": ["mcp", "connect", "mcp-everything"] } } } ``` ## Step 2/2. Use Teleport-protected MCP servers After configuring your MCP client, the MCP tools and resources should be available. You can now use the MCP servers as usual. Here is an example of using the `mcp-everything` server through Teleport with Claude Desktop: ![MCP everything usage example](/docs/assets/images/usage-example-everything-87dd7382b4ac8133f6e48afa778b0862.png) ## Troubleshooting ### Server is running but it has an empty list of tools Besides accessing the MCP servers, you also need permissions for the MCP tools they provide. You can see which tools are available for you by running `tsh mcp ls -v`. If you're missing tool permissions, reach out to your Teleport administrator to have them properly configured. ### Expired `tsh` session There must be a valid `tsh` session during the MCP server startup, or it won't start. If your session expires while the MCP server is running, the next tool calls will fail. You need to run `tsh login` again and retry the failed requests. In such cases, you don't have to restart the MCP client or the MCP server. ### `tsh mcp` commands not found If you're encountering an error like this when running the `tsh mcp` commands family: ``` ERROR: expected command but got "mcp" ``` This is caused by using an outdated version of `tsh`. The earliest version that includes the MCP commands is `18.1.0`, so you need to make sure you’re running at least this version. You can check your `tsh` version by running `tsh version`. ### `tsh mcp ls` returns an empty list of servers Make sure your Teleport cluster has MCP access resources available and the correct permissions to reach them. [See our guides for enrollment instructions.](https://goteleport.com/docs/enroll-resources/mcp-access.md) ### `tsh` path errors in your MCP clients When starting your MCP client, you might see an error such as `spawn ENOENT` or `command not found`: ![ENOENT error](/docs/assets/images/troubleshoot-tsh-binary-enoent-ccda85645c76788352d36401ed8e983f.png) This error indicates the path to the `tsh` binary is misconfigured in the client’s settings. To fix it, re-run the `tsh mcp config` command to update the path, or manually correct it in the client’s configuration file. See [connect MCP clients](https://goteleport.com/docs/connect-your-client/model-context-protocol/mcp-access.md) for more details. This issue can also occur due to a bug from the managed update feature, which has been fixed in version 18.2.3. If your Teleport cluster has managed update enabled for tools, check your `tsh` version by: ``` $ tsh version Teleport v18.2.3 git:v18.2.3-0-xxxxxxxx go1.24.7 Proxy version: 18.2.0 Proxy: teleport.example.com:443 Re-executed from version: 18.2.0 ``` The first line shows the version of the `tsh` binary from the managed update, and the last line shows the version from your original installation. Both versions must be at least `18.2.3` to fully resolve this issue. If the version shown on the first line is outdated, contact your Teleport administrator to raise the version for tools update. If the version shown in the "Re-executed from version" is outdated, find the `tsh` binary from your original installation (e.g. `which tsh`), uninstall it and install a newer release. Once `tsh` has been updated, re-run the `tsh mcp config` commands to reconfigure your MCP client.