Skip to main content

Troubleshooting MCP Access

Report an issue with this page

This section describes common issues that you might encounter in managing access to MCP servers with Teleport and how to work around or resolve them.

Disabled MCP server or tools missing from the MCP server​

By default, no MCP tools are allowed by your Teleport roles. You can check if any tool is allowed by running tsh mcp ls:

tsh mcp ls
Name              Description                                        Type  Allowed Tools Labels----------------- -------------------------------------------------- ----- ------------- ------teleport-mcp-demo A demo MCP server that shows current user and s... stdio (none) [!]
[!] Warning: you do not have access to any tools on the MCP server.Please contact your Teleport administrator to ensure your Teleport role hasappropriate 'allow.mcp.tools' set. For details on MCP access RBAC, see:https://goteleport.com/docs/enroll-resources/mcp-access/rbac/

If a user is assigned the access preset role, by default the available MCP tools are controlled by the {{internal.mcp_tools}} source in the role definition. This value can be populated through user traits:

kind: role
metadata:
  name: access
spec:
  allow:
    mcp:
      tools:
      - "{{internal.mcp_tools}}"

You can configure this user trait with tctl, assigning it to the Teleport user my_user:

tctl users update my_user --set-mcp-tools "*"

Alternatively you can assign your Teleport user the preset role mcp-user which allows access to all MCP servers and their tools. You can also define a custom role that explicitly specifies the allowed MCP tools and assigns them to your Teleport user. See RBAC for more details.

Server disconnected when starting the MCP server​

You may encounter a "Server disconnected" error or similar errors when your MCP client starts the MCP server.

Server disconnected error

First, make sure your client configuration is correct and your tsh session is active. See connect MCP clients for more details.

If the problem persists, follow your MCP client's specific guideline to find the debug logs of the MCP server execution.

If you encounter a "Lost server connection" error in the debug log, or the tsh command exits immediately, it usually indicates that the command used to launch the stdio MCP server on the Teleport Application Service instance has failed to execute properly.

To confirm this, check the Application Service logs for any warnings that indicate a failure to start the MCP server process — commonly an exec.ExitError, but it may also include other related execution or runtime errors. These typically appear shortly after the client connection is established:

WARN [APP:SERVICE] Failed to handle client connection. error:[
ERROR REPORT:
Original Error: *exec.ExitError exit status 1

To fix the issue, ensure that the Teleport app definition used to start the MCP server is configured correctly. You can test it by manually running the app.mcp.command and app.mcp.args directly on the host where the Teleport Application Service is running — without using Teleport. Also, make sure the host user set for mcp.run_as_host_user exists on the host and has the necessary permissions to execute the configured command.

tsh path errors in your MCP clients​

When starting your MCP client, you might see an error such as spawn <tsh-path> ENOENT or command not found:

ENOENT error

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 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.7Proxy version: 18.2.0Proxy: teleport.example.com:443Re-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.