Skip to main content
Version: 18.x

MCP Access

Report an issue with this page

This guide explains how to configure MCP clients to access MCP servers served by Teleport.

Prerequisites​

  • A running Teleport cluster version 18.0.2 or above. If you do not have one, read Get Started with Teleport or set up a demo environment.

  • The tctl and tsh clients.

    Installing 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-18.0.2.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.

    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/ping and use a JSON query tool to obtain your cluster version:

    curl https://example.teleport.sh/v1/webapi/ping | jq -r '.server_version'
    18.0.2
  • The Teleport MCP Access configured. See our guides for how to set up the MCP Access.

Step 1/2. Installation​

First, sign in into your Teleport cluster using tsh login:

tsh login --proxy=teleport.example.com:443 [email protected]

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=prodmcp-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.

tsh can automatically update the Claude Desktop MCP configuration file to include Teleport's configuration:

tsh mcp config --all --config-client=claude
Found MCP servers:fsmcp-everything
Updated client configuration at:~/Library/Application Support/Claude/claude_desktop_config.json
Teleport MCP servers will be prefixed with "teleport-mcp-" in thisconfiguration.
You may need to restart your client to reload these new configurations. If youencounter a "disconnected" error when tsh session expires, you may also need torestart 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 --config-client=/path/to/config.json

After updating the configuration, you need to restart the Claude Desktop app before using the newly added MCPs.

Step 2/2. Usage​

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:

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.