# Troubleshooting MCP Access

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 has
appropriate '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](https://goteleport.com/docs/enroll-resources/mcp-access/rbac.md) 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](/docs/assets/images/troubleshoot-server-disconnected-a392126c9e21246aa7c361cbacb55bde.png)

First, make sure your client configuration is correct and your `tsh` session is active. See [connect MCP clients](https://goteleport.com/docs/connect-your-client/model-context-protocol/mcp-access.md) 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](/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.