이 섹션은 Teleport로 MCP 서버 액세스를 관리할 때 발생할 수 있는 일반적인 문제와 해결 또는 우회 방법을 설명합니다.

MCP 서버가 비활성화되거나 MCP 서버에서 도구가 누락된 경우#

기본적으로 Teleport 역할에서는 어떤 MCP 도구도 허용되지 않습니다. 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/

사용자에게 access 프리셋 역할이 할당된 경우, 기본적으로 사용 가능한 MCP 도구는 역할 정의의 {{internal.mcp_tools}} 소스에 의해 제어됩니다. 이 값은 사용자 트레이트(trait)를 통해 설정할 수 있습니다:

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

tctl을 사용하여 Teleport 사용자 my_user에게 이 사용자 트레이트를 설정할 수 있습니다:

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

또는 모든 MCP 서버와 그 도구에 대한 액세스를 허용하는 프리셋 역할 mcp-user를 Teleport 사용자에게 할당할 수 있습니다. 허용되는 MCP 도구를 명시적으로 지정하는 사용자 정의 역할을 만들어 Teleport 사용자에게 할당할 수도 있습니다. 자세한 내용은 RBAC를 참조하세요.

MCP 서버 시작 시 서버 연결 끊김#

MCP 클라이언트가 MCP 서버를 시작할 때 "Server disconnected" 오류 또는 유사한 오류가 발생할 수 있습니다.

먼저 클라이언트 설정이 올바른지, tsh 세션이 활성 상태인지 확인하세요. 자세한 내용은 MCP 클라이언트 연결을 참조하세요.

문제가 지속되면 MCP 클라이언트의 특정 가이드라인을 따라 MCP 서버 실행의 디버그 로그를 확인하세요.

디버그 로그에서 "Lost server connection" 오류가 발생하거나 tsh 명령이 즉시 종료되는 경우, 일반적으로 Teleport Application Service 인스턴스에서 stdio MCP 서버를 실행하는 데 사용된 명령이 제대로 실행되지 않았음을 나타냅니다.

이를 확인하려면 Application Service 로그에서 MCP 서버 프로세스 시작 실패를 나타내는 경고를 확인하세요 — 일반적으로 exec.ExitError이지만 다른 관련 실행 또는 런타임 오류도 포함될 수 있습니다. 이러한 오류는 일반적으로 클라이언트 연결이 수립된 직후에 나타납니다:

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

문제를 해결하려면 MCP 서버를 시작하는 데 사용된 Teleport 앱 정의가 올바르게 설정되어 있는지 확인하세요. Teleport를 사용하지 않고 Teleport Application Service가 실행되는 호스트에서 직접 app.mcp.command와 app.mcp.args를 수동으로 실행하여 테스트할 수 있습니다. 또한 mcp.run_as_host_user에 설정된 호스트 사용자가 호스트에 존재하고 설정된 명령을 실행할 충분한 권한이 있는지 확인하세요.

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

MCP 클라이언트를 시작할 때 spawn <tsh-path> ENOENT 또는 command not found와 같은 오류가 표시될 수 있습니다:

이 오류는 클라이언트 설정에서 tsh 바이너리 경로가 잘못 구성되었음을 나타냅니다. 이를 해결하려면 tsh mcp config 명령을 다시 실행하여 경로를 업데이트하거나, 클라이언트 구성 파일에서 수동으로 수정하세요. 자세한 내용은 MCP 클라이언트 연결을 참조하세요.

이 문제는 관리형 업데이트(managed update) 기능의 버그로 인해 발생할 수도 있으며, 이는 버전 18.2.3에서 수정되었습니다. Teleport 클러스터에서 도구에 대한 관리형 업데이트가 활성화되어 있는 경우, 다음과 같이 tsh 버전을 확인하세요:

$ 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

첫 번째 줄은 관리형 업데이트로 설치된 tsh 바이너리의 버전을 나타내고, 마지막 줄은 원래 설치본의 버전을 나타냅니다. 이 문제를 완전히 해결하려면 두 버전 모두 18.2.3 이상이어야 합니다.

첫 번째 줄에 표시된 버전이 오래된 경우, Teleport 관리자에게 문의하여 도구 업데이트 버전을 올리세요. "Re-executed from version"에 표시된 버전이 오래된 경우, 원래 설치본의 tsh 바이너리를 찾아서(예: which tsh) 제거하고 최신 릴리스를 설치하세요.

tsh가 업데이트되면 tsh mcp config 명령을 다시 실행하여 MCP 클라이언트를 다시 구성하세요.