이 가이드는 Teleport가 제공하는 MCP 서버에 접근하도록 MCP 클라이언트를 구성하는 방법을 설명합니다.

사전 요구 사항#

• A running Teleport (v18.1.0 or higher) cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• 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 with the web address of your Teleport Proxy Service:

     $ TELEPORT_DOMAIN=
     $ 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:

• Teleport MCP Access가 구성되어 있어야 합니다.

  MCP Access 구성하기

  • 데모 MCP 서버로 빠르게 시작하기.
  • Stdio MCP 서버를 사용한 MCP Access

1/2단계. 사용 가능한 MCP 서버 목록#

먼저, tsh login을 사용하여 Teleport 클러스터에 로그인합니다. 클러스터의 Teleport Proxy Service 웹 주소를 에 지정합니다:

$ tsh login --proxy= --user=myuser@example.com

이제 사용 가능한 MCP 서버 목록을 확인할 수 있습니다:

$ 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

2/2단계. MCP 클라이언트 구성하기#

tsh mcp config 명령을 사용하여 MCP 클라이언트 구성을 생성할 수 있습니다. --labels 플래그를 사용하여 레이블로 필터링하거나, 접근 가능한 모든 MCP 서버를 구성하는 --all을 지정하여 구성할 서버를 선택할 수 있습니다.

이 명령은 수동 MCP 클라이언트 업데이트를 위한 구성 파일(mcpServers 형식 사용)을 생성하거나 MCP 클라이언트 구성을 자동으로 업데이트할 수 있습니다.

$ 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.

$ tsh mcp config --all --client-config=/path/to/config.json

$ 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.

$ tsh mcp config --all --client-config=/path/to/project/.cursor/mcp.json

$ 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"]
    }
  }
}

MCP 클라이언트를 구성한 후에는 MCP 도구와 리소스를 사용할 수 있습니다.

이제 평소와 같이 MCP 서버를 사용할 수 있습니다. 다음은 Claude Desktop을 통해 Teleport를 경유하여 mcp-everything 서버를 사용하는 예시입니다:

문제 해결#

서버는 실행 중이지만 도구 목록이 비어 있음#

MCP 서버에 접근하는 것 외에도, 서버가 제공하는 MCP 도구에 대한 권한도 필요합니다. tsh mcp ls -v를 실행하여 어떤 도구를 사용할 수 있는지 확인할 수 있습니다.

도구 권한이 없는 경우, Teleport 관리자에게 연락하여 적절히 구성되도록 요청하세요.

만료된 tsh 세션#

MCP 서버 시작 시 유효한 tsh 세션이 있어야 하며, 그렇지 않으면 시작되지 않습니다.

MCP 서버가 실행 중인 동안 세션이 만료되면 다음 도구 호출이 실패합니다. tsh login을 다시 실행하고 실패한 요청을 재시도해야 합니다. 이런 경우에는 MCP 클라이언트나 MCP 서버를 재시작할 필요가 없습니다.

tsh mcp 명령을 찾을 수 없음#

tsh mcp 명령 계열을 실행할 때 다음과 같은 오류가 발생하는 경우:

ERROR: expected command but got "mcp"

이는 오래된 버전의 tsh를 사용하기 때문에 발생합니다. MCP 명령이 포함된 최초 버전은 18.1.0이므로, 최소 이 버전 이상을 실행하고 있는지 확인해야 합니다. tsh version을 실행하여 tsh 버전을 확인할 수 있습니다.

tsh mcp ls가 빈 서버 목록을 반환함#

Teleport 클러스터에 MCP 접근 리소스가 사용 가능하고 해당 리소스에 접근할 수 있는 올바른 권한이 있는지 확인하세요. 등록 방법은 가이드를 참조하세요.

MCP 클라이언트에서 tsh 경로 오류#

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

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