InfoGrab DocsInfoGrab Docs

OAuth로 보호되는 MCP 서버에 로그인하기

요약

일부 원격 MCP 서버는 Teleport 로그인과는 별개로, 해당 서버의 자체 인가 서버가 발급한 OAuth 액세스 토큰을 요구합니다. Teleport는 여전히 사용자를 인증하고, 호출할 수 있는 MCP 도구를 포함한 역할을 적용합니다.

일부 원격 MCP 서버는 Teleport 로그인과는 별개로, 해당 서버의 자체 인가 서버가 발급한 OAuth 액세스 토큰을 요구합니다. tsh mcp login 명령은 브라우저에서 MCP 인가 흐름을 실행하고, 그 결과로 받은 토큰을 워크스테이션에 저장하며, tsh가 해당 MCP 서버로 보내는 모든 요청에 이 토큰을 첨부하도록 합니다.

Teleport는 여전히 사용자를 인증하고, 호출할 수 있는 MCP 도구를 포함한 역할을 적용합니다. OAuth 토큰은 MCP 서버 자체의 요구 사항만 충족합니다.

동작 방식#

tsh mcp login을 실행하면 tsh는 먼저 Teleport를 통해 MCP 서버에 인증되지 않은 MCP initialize 요청을 보냅니다. 서버가 이 요청을 수락하면 로그인이 필요하지 않으므로 명령이 종료됩니다. Teleport 관리자가 MCP 서버를 OAuth를 사용하지 않는 것으로 구성한 경우 tsh는 요청을 보내지 않고 종료합니다. 서버가 HTTP 401로 응답하면 tsh는 다음 단계를 계속합니다.

  • MCP 서버의 OAuth 보호 리소스 메타데이터에 명시된 인가 서버를 찾은 다음, 해당 인가 서버의 메타데이터를 읽습니다.
  • --client-id로 사전 등록된 클라이언트를 지정했거나 Teleport 관리자가 MCP 서버용으로 구성해 둔 경우가 아니라면, 동적 클라이언트 등록을 사용하여 Teleport tsh라는 이름의 OAuth 클라이언트를 등록합니다.
  • 브라우저에서 공급자의 인가 페이지를 열고, 결과를 받기 위해 루프백 콜백 주소 (기본값은 http://127.0.0.1:<port>/callback)에서 대기합니다. 인가를 완료하는 데 3분이 주어집니다.
  • 인가 코드를 토큰으로 교환하고, 이를 $TELEPORT_HOME/mcp/<proxy>/<user>/<cluster>/<name>.oauth.json에 저장합니다. 이 파일은 해당 사용자만 읽을 수 있습니다. TELEPORT_HOME의 기본값은 ~/.tsh입니다.

MCP 서버와 해당 보호 리소스 메타데이터에 대한 요청은 Teleport 애플리케이션 서비스를 거치므로, MCP 서버가 워크스테이션에서 접근 가능할 필요는 없습니다. 인가 서버에 대한 요청은 워크스테이션에서 직접 전송되거나 HTTPS_PROXY에 설정된 프록시를 거칩니다. 인가 서버는 HTTPS를 사용해야 하며 공인 IP 주소로 해석되어야 합니다. tsh는 루프백, 사설, 링크 로컬 또는 기타 비공인 주소에 있는 OAuth 엔드포인트에 접속하지 않습니다.

로그인한 후에는 tsh mcp connect와 tsh proxy mcp가 저장된 액세스 토큰을 Authorization 헤더에 담아 보냅니다. 액세스 토큰이 만료되면 tsh가 토큰을 갱신합니다. 갱신에 실패하면 tsh는 최초 로그인과 동일한 클라이언트와 리디렉션 URI를 사용하여 브라우저를 열고 다시 로그인하도록 합니다.

저장된 자격 증명은 MCP 서버의 URI 및 해당 자격 증명을 발급한 인가 서버에 묶여 있습니다. Teleport 관리자가 MCP 서버의 URI를 변경하면 tsh mcp login을 다시 실행하십시오. 관리자가 MCP 서버에 구성된 OAuth 설정을 변경한 경우에도 마찬가지입니다. 자동 로그인은 최초 로그인에 사용한 클라이언트와 리디렉션 URI를 계속 사용하기 때문입니다.

사전 요구사항#

  • 실행 중인 Teleport (v18.11.1 or higher) 클러스터. Teleport를 시작하려면 무료 체험판에 가입하거나 데모 환경을 구성하세요.

  • `tsh` client.

    Installing \`tsh\` client
    1. Teleport 클러스터의 버전을 확인합니다. `tsh` client는 Teleport 클러스터 버전보다 최대 한 개의 메이저 버전까지만 뒤처질 수 있습니다. Proxy Service의 /v1/webapi/find로 GET 요청을 보내고 JSON 쿼리 도구를 사용하여 클러스터 버전을 확인합니다. teleport.example.com:443를 Teleport Proxy Service의 웹 주소로 바꿉니다:

      $ TELEPORT_DOMAIN=teleport.example.com:443
      $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
      
    2. 사용 중인 플랫폼에 대한 지침에 따라 `tsh` client를 설치합니다:

Mac

     \`tsh\` client가 포함된, 서명된 Teleport macOS .pkg 설치 프로그램을 다운로드합니다:
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     Finder에서 `pkg` 파일을 더블 클릭하여 설치를 시작합니다.
 
     
Warning
       Homebrew를 사용하여 Teleport를 설치하는 것은 지원되지 않습니다. Homebrew의
       Teleport 패키지는 Teleport에서 유지 관리하지 않으므로 신뢰성이나 보안을
       보장할 수 없습니다.
     

Windows - Powershell

     ```code
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     # Unzip the archive and move the \`tsh\` client to your %PATH%
     # NOTE: Do not place the \`tsh\` client in the System32 directory, as this can cause issues when using WinSCP.
     # Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```
 
   

 
   

Linux

     Linux 설치판의 모든 Teleport 바이너리에는 \`tsh\` client가 포함되어 있습니다.  RPM/DEB
     패키지 및 i386/ARM/ARM64용 다운로드를 포함한 더 많은 옵션은
     [설치 페이지](../installation/installation.mdx)를 참조하세요.
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     # Teleport binaries have been copied to /usr/local/bin
     ```
   

 
  • streamable-HTTP 전송을 사용하고, OAuth를 요구하며, Teleport에 등록된 MCP 서버. Streamable-HTTP MCP 서버를 사용한 MCP 접근을 참고하십시오.
  • tsh를 실행하는 머신의 웹 브라우저. SSH를 통해 tsh를 실행하는 경우, 로컬 브라우저에서 로그인을 완료하는 방법은 문제 해결을 참고하십시오.
  • 워크스테이션에서 MCP 서버의 OAuth 인가 서버로 연결되는 HTTPS 접근.

1/2단계. MCP 서버에 로그인하기#

Teleport 클러스터에 로그인하고 MCP 서버의 이름을 확인합니다. teleport.example.com에는 Teleport 프록시 서비스의 웹 주소를, my_user에는 Teleport 사용자 이름을 지정합니다.

$ tsh login --proxy=teleport.example.com --user=my_user
$ tsh mcp ls

MCP 서버에 로그인합니다. my-mcp-server를 서버 이름으로 바꿉니다.

$ tsh mcp login my-mcp-server
Requesting scopes required by the MCP server: mcp:read mcp:write
Registering OAuth client "Teleport tsh" for MCP server "my-mcp-server"...
Opening browser for authorization. If it does not open, visit:

  https://auth.example.com/authorize?client_id=...

Authorization complete. Tokens stored in /home/alice/.tsh/mcp/teleport.example.com/alice/teleport.example.com/my-mcp-server.oauth.json.
MCP server "my-mcp-server" is ready — restart your MCP clients if already running.

브라우저에서 요청을 승인합니다. 브라우저에 "Login complete"가 표시되면 터미널로 돌아옵니다.

2/2단계. MCP 클라이언트 연결하기#

Warning

Teleport MCP 서버에는 MCP 클라이언트의 내장 OAuth 로그인을 사용하지 마십시오. 또한 tsh mcp connect에 -H로, 또는 tsh mcp config에 --header로 Authorization 헤더를 설정하지 마십시오. 해당 헤더는 tsh mcp login이 저장한 자격 증명을 대체합니다.

MCP 클라이언트가 tsh mcp connect를 실행한다면 모든 설정이 끝난 것입니다. 이 구성은 tsh mcp config가 생성하는 설정이며, tsh mcp connect는 저장된 자격 증명을 자동으로 사용합니다. MCP 클라이언트가 이미 실행 중이었다면 다시 시작하십시오. MCP 클라이언트를 아직 구성하지 않았다면 Teleport로 MCP 서버에 접근하기를 따르십시오.

MCP 클라이언트가 tsh mcp connect를 실행할 수 없고 streamable HTTP로 연결해야 하는 경우에만 tsh proxy mcp를 사용하십시오. 로그인한 후에 시작하고, 이미 실행 중이었다면 다시 시작합니다.

$ tsh proxy mcp my-mcp-server -p 8888

MCP 서버에서 로그아웃하기#

MCP 서버 하나에 저장된 자격 증명을 제거합니다.

$ tsh mcp logout my-mcp-server

이름을 생략하면 현재 클러스터의 모든 MCP 서버에 대한 자격 증명이 제거됩니다. tsh logout도 Teleport 자격 증명과 함께 MCP OAuth 자격 증명을 제거합니다.

tsh mcp login 플래그#

기본적으로 tsh mcp login에는 플래그가 필요하지 않습니다. Teleport 관리자는 MCP 서버에 클라이언트 ID, 콜백 주소, 스코프를 구성할 수 있으며, tsh는 사용자가 지정하지 않은 플래그에 대해 이 값을 사용합니다. --callback-port 또는 --redirect-uri는 구성된 콜백 주소를 대체합니다. OAuth 공급자가 동적 클라이언트 등록을 지원하지 않거나 특정 값을 요구하는 경우에 플래그를 사용하십시오.

플래그 용도
--client-id 새 클라이언트를 등록하는 대신 공급자에 이미 등록된 OAuth 클라이언트를 사용합니다.
--client-secret 사전 등록된 기밀 클라이언트의 시크릿을 프롬프트로 입력받습니다. --client-id 또는 MCP 서버에 구성된 클라이언트 ID가 필요합니다. tsh가 토큰을 갱신할 수 있도록 시크릿은 토큰과 함께 저장됩니다.
--callback-port 고정된 포트에서 대기하며, 리디렉션 URI는 http://127.0.0.1:<port>/callback이 됩니다. 클라이언트에 등록된 리디렉션 URI와 일치하도록 설정하십시오.
--redirect-uri http://localhost:3118/callback과 같이 정확한 루프백 리디렉션 URI를 설정합니다. 등록된 리디렉션 URI가 127.0.0.1이 아니라 localhost 또는 다른 루프백 주소를 사용하는 경우에 사용합니다. --callback-port와 함께 사용할 수 없습니다.
--oauth-scope 요청할 OAuth 스코프를 설정합니다. 스코프는 쉼표나 공백으로 구분하거나 플래그를 반복하여 지정합니다. 이 플래그가 없으면 tsh는 MCP 서버에 구성된 스코프, 서버의 401 응답 챌린지에 명시된 스코프, 보호 리소스 메타데이터에 나열된 스코프 순서로 요청합니다.
--browser none으로 설정하면 브라우저를 열지 않고 인가 URL을 출력합니다.

사전 등록된 클라이언트로 로그인하려면 공급자에 http://127.0.0.1:<code>3118</code>/callback을 리디렉션 URI로 등록한 다음 다음 명령을 실행합니다.

$ tsh mcp login my-mcp-server --client-id=client-id --callback-port=3118

클라이언트가 http://localhost:<code>3118</code>/callback으로 등록되어 있다면 --redirect-uri를 사용합니다.

$ tsh mcp login my-mcp-server --client-id=client-id --redirect-uri=http://localhost:3118/callback

클라이언트가 기밀 클라이언트라면 두 명령 중 하나에 --client-secret을 추가하십시오. tsh가 시크릿을 프롬프트로 입력받으므로 셸 히스토리에 남지 않습니다.

이후의 토큰 갱신과 자동 로그인은 이번 로그인의 클라이언트 ID, 시크릿, 리디렉션 URI, 스코프를 재사용하므로 이 플래그는 한 번만 지정하면 됩니다.

문제 해결#

단계가 실패했을 때 더 자세한 정보를 보려면 tsh mcp login에 --debug를 추가하십시오.

공급자가 동적 클라이언트 등록을 지원하지 않는 경우#

The MCP server's OAuth provider does not support dynamic client registration.

인가 서버가 등록 엔드포인트를 게시하지 않습니다. 공급자에 OAuth 클라이언트를 등록하거나 공급자가 MCP 클라이언트용으로 게시한 클라이언트 ID를 사용한 다음, tsh mcp login 플래그에 나온 대로 --client-id와 --callback-port 또는 --redirect-uri를 지정하여 로그인하십시오.

공급자가 클라이언트 등록을 거부한 경우#

The MCP server's OAuth provider rejected the client registration.

일부 공급자는 승인된 MCP 클라이언트만 등록하도록 허용합니다. 공급자의 관리자에게 Teleport를 승인하거나 클라이언트 ID를 발급해 달라고 요청한 다음, --client-id로 로그인하십시오.

공급자가 리디렉션 URI 불일치를 보고하는 경우#

공급자는 포트와 호스트가 127.0.0.1인지 localhost인지를 포함하여 리디렉션 URI를 정확히 비교합니다. --callback-port 또는 --redirect-uri를 지정하지 않으면 tsh는 임의의 포트를 선택하는데, 사전 등록된 클라이언트는 대개 이를 허용하지 않습니다. 클라이언트에 등록된 리디렉션 URI를 확인하여 --redirect-uri로 전달하거나, 127.0.0.1을 사용하는 경우에는 해당 포트를 --callback-port로 전달하십시오.

로그인 시간이 초과되는 경우#

timed out waiting for the browser authorization to complete

브라우저가 3분 이내에 콜백 주소에 도달하지 못했습니다. 브라우저가 tsh와 다른 머신에서 실행되는 경우, 예를 들어 SSH를 통해 tsh를 실행하는 경우에 발생합니다. 콜백 주소는 tsh를 실행하는 머신의 루프백 주소이므로, 고정 포트를 해당 주소로 포워딩하십시오. remote-host는 tsh를 실행하는 머신으로 바꿉니다.

$ ssh -L 3118:127.0.0.1:3118 remote-host
$ tsh mcp login my-mcp-server --callback-port=3118 --browser=none

출력된 인가 URL을 로컬 브라우저에서 엽니다.

콜백 포트가 이미 사용 중인 경우#

listen tcp 127.0.0.1:3118: bind: address already in use

다른 프로세스(대개 다른 tsh mcp login)가 콜백 포트에서 대기하고 있습니다. 해당 프로세스를 중지하거나 다른 포트를 선택하십시오. 사전 등록된 클라이언트를 사용하는 경우 새 포트도 공급자에 등록되어 있어야 합니다.

OAuth 엔드포인트가 허용되지 않는 네트워크 주소를 사용하는 경우#

OAuth authorization endpoint resolves to a prohibited network address

tsh는 공인 IP 주소에서 HTTPS로 제공되는 인가 서버에만 접속합니다. 사설 네트워크에 있거나 일반 HTTP로 제공되는 인가 서버는 지원되지 않습니다.

MCP 클라이언트가 로그인을 요구하는 경우#

Authentication with MCP server "my-mcp-server" is required or has expired. Run `tsh mcp login my-mcp-server` in a terminal, complete authorization in the browser, then retry the request.
MCP server "my-mcp-server" rejected the request with HTTP 401. Do not use the MCP client's built-in OAuth login for a Teleport endpoint.

tsh에 MCP 서버에 대해 사용할 수 있는 자격 증명이 없거나, 자격 증명을 갱신하지 못했고 다시 로그인하기 위해 브라우저를 열 수도 없었습니다. tsh mcp login을 실행한 다음 MCP 클라이언트에서 요청을 다시 시도하십시오.

tsh가 로그인이 필요하지 않다고 알리는 경우#

MCP server "my-mcp-server" accepted an unauthenticated request, so OAuth login is not required.

MCP 서버가 토큰 없는 initialize 요청을 수락했으므로 tsh가 OAuth 흐름을 시작하지 않았습니다. 로그인하지 않고 서버에 연결하십시오.

MCP server "my-mcp-server" is configured as not using OAuth, so OAuth login is not required.

Teleport 관리자가 MCP 서버를 OAuth를 사용하지 않는 것으로 구성했습니다. MCP 서버가 실제로 로그인을 요구한다면 관리자에게 구성을 변경해 달라고 요청하십시오.

MCP 서버가 HTTP 전송을 사용하지 않는 경우#

MCP server "my-mcp-server" does not use HTTP transport; OAuth login only applies to HTTP MCP servers

tsh mcp login은 streamable-HTTP 전송으로 등록되어 URI가 mcp+http:// 또는 mcp+https://로 시작하는 MCP 서버에만 적용됩니다. Stdio 및 SSE MCP 서버는 MCP OAuth를 사용하지 않습니다.

다음 단계#

OAuth로 보호되는 MCP 서버에 로그인하기

Teleport v18.11
원문 보기

요약

일부 원격 MCP 서버는 Teleport 로그인과는 별개로, 해당 서버의 자체 인가 서버가 발급한 OAuth 액세스 토큰을 요구합니다. Teleport는 여전히 사용자를 인증하고, 호출할 수 있는 MCP 도구를 포함한 역할을 적용합니다.

일부 원격 MCP 서버는 Teleport 로그인과는 별개로, 해당 서버의 자체 인가 서버가 발급한 OAuth 액세스 토큰을 요구합니다. tsh mcp login 명령은 브라우저에서 MCP 인가 흐름을 실행하고, 그 결과로 받은 토큰을 워크스테이션에 저장하며, tsh가 해당 MCP 서버로 보내는 모든 요청에 이 토큰을 첨부하도록 합니다.

Teleport는 여전히 사용자를 인증하고, 호출할 수 있는 MCP 도구를 포함한 역할을 적용합니다. OAuth 토큰은 MCP 서버 자체의 요구 사항만 충족합니다.

동작 방식#

tsh mcp login을 실행하면 tsh는 먼저 Teleport를 통해 MCP 서버에 인증되지 않은 MCP initialize 요청을 보냅니다. 서버가 이 요청을 수락하면 로그인이 필요하지 않으므로 명령이 종료됩니다. Teleport 관리자가 MCP 서버를 OAuth를 사용하지 않는 것으로 구성한 경우 tsh는 요청을 보내지 않고 종료합니다. 서버가 HTTP 401로 응답하면 tsh는 다음 단계를 계속합니다.

  • MCP 서버의 OAuth 보호 리소스 메타데이터에 명시된 인가 서버를 찾은 다음, 해당 인가 서버의 메타데이터를 읽습니다.
  • --client-id로 사전 등록된 클라이언트를 지정했거나 Teleport 관리자가 MCP 서버용으로 구성해 둔 경우가 아니라면, 동적 클라이언트 등록을 사용하여 Teleport tsh라는 이름의 OAuth 클라이언트를 등록합니다.
  • 브라우저에서 공급자의 인가 페이지를 열고, 결과를 받기 위해 루프백 콜백 주소 (기본값은 http://127.0.0.1:<port>/callback)에서 대기합니다. 인가를 완료하는 데 3분이 주어집니다.
  • 인가 코드를 토큰으로 교환하고, 이를 $TELEPORT_HOME/mcp/<proxy>/<user>/<cluster>/<name>.oauth.json에 저장합니다. 이 파일은 해당 사용자만 읽을 수 있습니다. TELEPORT_HOME의 기본값은 ~/.tsh입니다.

MCP 서버와 해당 보호 리소스 메타데이터에 대한 요청은 Teleport 애플리케이션 서비스를 거치므로, MCP 서버가 워크스테이션에서 접근 가능할 필요는 없습니다. 인가 서버에 대한 요청은 워크스테이션에서 직접 전송되거나 HTTPS_PROXY에 설정된 프록시를 거칩니다. 인가 서버는 HTTPS를 사용해야 하며 공인 IP 주소로 해석되어야 합니다. tsh는 루프백, 사설, 링크 로컬 또는 기타 비공인 주소에 있는 OAuth 엔드포인트에 접속하지 않습니다.

로그인한 후에는 tsh mcp connect와 tsh proxy mcp가 저장된 액세스 토큰을 Authorization 헤더에 담아 보냅니다. 액세스 토큰이 만료되면 tsh가 토큰을 갱신합니다. 갱신에 실패하면 tsh는 최초 로그인과 동일한 클라이언트와 리디렉션 URI를 사용하여 브라우저를 열고 다시 로그인하도록 합니다.

저장된 자격 증명은 MCP 서버의 URI 및 해당 자격 증명을 발급한 인가 서버에 묶여 있습니다. Teleport 관리자가 MCP 서버의 URI를 변경하면 tsh mcp login을 다시 실행하십시오. 관리자가 MCP 서버에 구성된 OAuth 설정을 변경한 경우에도 마찬가지입니다. 자동 로그인은 최초 로그인에 사용한 클라이언트와 리디렉션 URI를 계속 사용하기 때문입니다.

사전 요구사항#

  • 실행 중인 Teleport (v18.11.1 or higher) 클러스터. Teleport를 시작하려면 무료 체험판에 가입하거나 데모 환경을 구성하세요.

  • `tsh` client.

    Installing \`tsh\` client
    1. Teleport 클러스터의 버전을 확인합니다. `tsh` client는 Teleport 클러스터 버전보다 최대 한 개의 메이저 버전까지만 뒤처질 수 있습니다. Proxy Service의 /v1/webapi/find로 GET 요청을 보내고 JSON 쿼리 도구를 사용하여 클러스터 버전을 확인합니다. teleport.example.com:443를 Teleport Proxy Service의 웹 주소로 바꿉니다:

      $ TELEPORT_DOMAIN=teleport.example.com:443
      $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
      
    2. 사용 중인 플랫폼에 대한 지침에 따라 `tsh` client를 설치합니다:

Mac

     \`tsh\` client가 포함된, 서명된 Teleport macOS .pkg 설치 프로그램을 다운로드합니다:
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     Finder에서 `pkg` 파일을 더블 클릭하여 설치를 시작합니다.
 
     
Warning
       Homebrew를 사용하여 Teleport를 설치하는 것은 지원되지 않습니다. Homebrew의
       Teleport 패키지는 Teleport에서 유지 관리하지 않으므로 신뢰성이나 보안을
       보장할 수 없습니다.
     

Windows - Powershell

     ```code
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     # Unzip the archive and move the \`tsh\` client to your %PATH%
     # NOTE: Do not place the \`tsh\` client in the System32 directory, as this can cause issues when using WinSCP.
     # Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```
 
   

 
   

Linux

     Linux 설치판의 모든 Teleport 바이너리에는 \`tsh\` client가 포함되어 있습니다.  RPM/DEB
     패키지 및 i386/ARM/ARM64용 다운로드를 포함한 더 많은 옵션은
     [설치 페이지](../installation/installation.mdx)를 참조하세요.
 
     ```code
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     # Teleport binaries have been copied to /usr/local/bin
     ```
   

 
  • streamable-HTTP 전송을 사용하고, OAuth를 요구하며, Teleport에 등록된 MCP 서버. Streamable-HTTP MCP 서버를 사용한 MCP 접근을 참고하십시오.
  • tsh를 실행하는 머신의 웹 브라우저. SSH를 통해 tsh를 실행하는 경우, 로컬 브라우저에서 로그인을 완료하는 방법은 문제 해결을 참고하십시오.
  • 워크스테이션에서 MCP 서버의 OAuth 인가 서버로 연결되는 HTTPS 접근.

1/2단계. MCP 서버에 로그인하기#

Teleport 클러스터에 로그인하고 MCP 서버의 이름을 확인합니다. teleport.example.com에는 Teleport 프록시 서비스의 웹 주소를, my_user에는 Teleport 사용자 이름을 지정합니다.

$ tsh login --proxy=teleport.example.com --user=my_user
$ tsh mcp ls

MCP 서버에 로그인합니다. my-mcp-server를 서버 이름으로 바꿉니다.

$ tsh mcp login my-mcp-server
Requesting scopes required by the MCP server: mcp:read mcp:write
Registering OAuth client "Teleport tsh" for MCP server "my-mcp-server"...
Opening browser for authorization. If it does not open, visit:

  https://auth.example.com/authorize?client_id=...

Authorization complete. Tokens stored in /home/alice/.tsh/mcp/teleport.example.com/alice/teleport.example.com/my-mcp-server.oauth.json.
MCP server "my-mcp-server" is ready — restart your MCP clients if already running.

브라우저에서 요청을 승인합니다. 브라우저에 "Login complete"가 표시되면 터미널로 돌아옵니다.

2/2단계. MCP 클라이언트 연결하기#

Warning

Teleport MCP 서버에는 MCP 클라이언트의 내장 OAuth 로그인을 사용하지 마십시오. 또한 tsh mcp connect에 -H로, 또는 tsh mcp config에 --header로 Authorization 헤더를 설정하지 마십시오. 해당 헤더는 tsh mcp login이 저장한 자격 증명을 대체합니다.

MCP 클라이언트가 tsh mcp connect를 실행한다면 모든 설정이 끝난 것입니다. 이 구성은 tsh mcp config가 생성하는 설정이며, tsh mcp connect는 저장된 자격 증명을 자동으로 사용합니다. MCP 클라이언트가 이미 실행 중이었다면 다시 시작하십시오. MCP 클라이언트를 아직 구성하지 않았다면 Teleport로 MCP 서버에 접근하기를 따르십시오.

MCP 클라이언트가 tsh mcp connect를 실행할 수 없고 streamable HTTP로 연결해야 하는 경우에만 tsh proxy mcp를 사용하십시오. 로그인한 후에 시작하고, 이미 실행 중이었다면 다시 시작합니다.

$ tsh proxy mcp my-mcp-server -p 8888

MCP 서버에서 로그아웃하기#

MCP 서버 하나에 저장된 자격 증명을 제거합니다.

$ tsh mcp logout my-mcp-server

이름을 생략하면 현재 클러스터의 모든 MCP 서버에 대한 자격 증명이 제거됩니다. tsh logout도 Teleport 자격 증명과 함께 MCP OAuth 자격 증명을 제거합니다.

tsh mcp login 플래그#

기본적으로 tsh mcp login에는 플래그가 필요하지 않습니다. Teleport 관리자는 MCP 서버에 클라이언트 ID, 콜백 주소, 스코프를 구성할 수 있으며, tsh는 사용자가 지정하지 않은 플래그에 대해 이 값을 사용합니다. --callback-port 또는 --redirect-uri는 구성된 콜백 주소를 대체합니다. OAuth 공급자가 동적 클라이언트 등록을 지원하지 않거나 특정 값을 요구하는 경우에 플래그를 사용하십시오.

플래그 용도
--client-id 새 클라이언트를 등록하는 대신 공급자에 이미 등록된 OAuth 클라이언트를 사용합니다.
--client-secret 사전 등록된 기밀 클라이언트의 시크릿을 프롬프트로 입력받습니다. --client-id 또는 MCP 서버에 구성된 클라이언트 ID가 필요합니다. tsh가 토큰을 갱신할 수 있도록 시크릿은 토큰과 함께 저장됩니다.
--callback-port 고정된 포트에서 대기하며, 리디렉션 URI는 http://127.0.0.1:<port>/callback이 됩니다. 클라이언트에 등록된 리디렉션 URI와 일치하도록 설정하십시오.
--redirect-uri http://localhost:3118/callback과 같이 정확한 루프백 리디렉션 URI를 설정합니다. 등록된 리디렉션 URI가 127.0.0.1이 아니라 localhost 또는 다른 루프백 주소를 사용하는 경우에 사용합니다. --callback-port와 함께 사용할 수 없습니다.
--oauth-scope 요청할 OAuth 스코프를 설정합니다. 스코프는 쉼표나 공백으로 구분하거나 플래그를 반복하여 지정합니다. 이 플래그가 없으면 tsh는 MCP 서버에 구성된 스코프, 서버의 401 응답 챌린지에 명시된 스코프, 보호 리소스 메타데이터에 나열된 스코프 순서로 요청합니다.
--browser none으로 설정하면 브라우저를 열지 않고 인가 URL을 출력합니다.

사전 등록된 클라이언트로 로그인하려면 공급자에 http://127.0.0.1:<code>3118</code>/callback을 리디렉션 URI로 등록한 다음 다음 명령을 실행합니다.

$ tsh mcp login my-mcp-server --client-id=client-id --callback-port=3118

클라이언트가 http://localhost:<code>3118</code>/callback으로 등록되어 있다면 --redirect-uri를 사용합니다.

$ tsh mcp login my-mcp-server --client-id=client-id --redirect-uri=http://localhost:3118/callback

클라이언트가 기밀 클라이언트라면 두 명령 중 하나에 --client-secret을 추가하십시오. tsh가 시크릿을 프롬프트로 입력받으므로 셸 히스토리에 남지 않습니다.

이후의 토큰 갱신과 자동 로그인은 이번 로그인의 클라이언트 ID, 시크릿, 리디렉션 URI, 스코프를 재사용하므로 이 플래그는 한 번만 지정하면 됩니다.

문제 해결#

단계가 실패했을 때 더 자세한 정보를 보려면 tsh mcp login에 --debug를 추가하십시오.

공급자가 동적 클라이언트 등록을 지원하지 않는 경우#

The MCP server's OAuth provider does not support dynamic client registration.

인가 서버가 등록 엔드포인트를 게시하지 않습니다. 공급자에 OAuth 클라이언트를 등록하거나 공급자가 MCP 클라이언트용으로 게시한 클라이언트 ID를 사용한 다음, tsh mcp login 플래그에 나온 대로 --client-id와 --callback-port 또는 --redirect-uri를 지정하여 로그인하십시오.

공급자가 클라이언트 등록을 거부한 경우#

The MCP server's OAuth provider rejected the client registration.

일부 공급자는 승인된 MCP 클라이언트만 등록하도록 허용합니다. 공급자의 관리자에게 Teleport를 승인하거나 클라이언트 ID를 발급해 달라고 요청한 다음, --client-id로 로그인하십시오.

공급자가 리디렉션 URI 불일치를 보고하는 경우#

공급자는 포트와 호스트가 127.0.0.1인지 localhost인지를 포함하여 리디렉션 URI를 정확히 비교합니다. --callback-port 또는 --redirect-uri를 지정하지 않으면 tsh는 임의의 포트를 선택하는데, 사전 등록된 클라이언트는 대개 이를 허용하지 않습니다. 클라이언트에 등록된 리디렉션 URI를 확인하여 --redirect-uri로 전달하거나, 127.0.0.1을 사용하는 경우에는 해당 포트를 --callback-port로 전달하십시오.

로그인 시간이 초과되는 경우#

timed out waiting for the browser authorization to complete

브라우저가 3분 이내에 콜백 주소에 도달하지 못했습니다. 브라우저가 tsh와 다른 머신에서 실행되는 경우, 예를 들어 SSH를 통해 tsh를 실행하는 경우에 발생합니다. 콜백 주소는 tsh를 실행하는 머신의 루프백 주소이므로, 고정 포트를 해당 주소로 포워딩하십시오. remote-host는 tsh를 실행하는 머신으로 바꿉니다.

$ ssh -L 3118:127.0.0.1:3118 remote-host
$ tsh mcp login my-mcp-server --callback-port=3118 --browser=none

출력된 인가 URL을 로컬 브라우저에서 엽니다.

콜백 포트가 이미 사용 중인 경우#

listen tcp 127.0.0.1:3118: bind: address already in use

다른 프로세스(대개 다른 tsh mcp login)가 콜백 포트에서 대기하고 있습니다. 해당 프로세스를 중지하거나 다른 포트를 선택하십시오. 사전 등록된 클라이언트를 사용하는 경우 새 포트도 공급자에 등록되어 있어야 합니다.

OAuth 엔드포인트가 허용되지 않는 네트워크 주소를 사용하는 경우#

OAuth authorization endpoint resolves to a prohibited network address

tsh는 공인 IP 주소에서 HTTPS로 제공되는 인가 서버에만 접속합니다. 사설 네트워크에 있거나 일반 HTTP로 제공되는 인가 서버는 지원되지 않습니다.

MCP 클라이언트가 로그인을 요구하는 경우#

Authentication with MCP server "my-mcp-server" is required or has expired. Run `tsh mcp login my-mcp-server` in a terminal, complete authorization in the browser, then retry the request.
MCP server "my-mcp-server" rejected the request with HTTP 401. Do not use the MCP client's built-in OAuth login for a Teleport endpoint.

tsh에 MCP 서버에 대해 사용할 수 있는 자격 증명이 없거나, 자격 증명을 갱신하지 못했고 다시 로그인하기 위해 브라우저를 열 수도 없었습니다. tsh mcp login을 실행한 다음 MCP 클라이언트에서 요청을 다시 시도하십시오.

tsh가 로그인이 필요하지 않다고 알리는 경우#

MCP server "my-mcp-server" accepted an unauthenticated request, so OAuth login is not required.

MCP 서버가 토큰 없는 initialize 요청을 수락했으므로 tsh가 OAuth 흐름을 시작하지 않았습니다. 로그인하지 않고 서버에 연결하십시오.

MCP server "my-mcp-server" is configured as not using OAuth, so OAuth login is not required.

Teleport 관리자가 MCP 서버를 OAuth를 사용하지 않는 것으로 구성했습니다. MCP 서버가 실제로 로그인을 요구한다면 관리자에게 구성을 변경해 달라고 요청하십시오.

MCP 서버가 HTTP 전송을 사용하지 않는 경우#

MCP server "my-mcp-server" does not use HTTP transport; OAuth login only applies to HTTP MCP servers

tsh mcp login은 streamable-HTTP 전송으로 등록되어 URI가 mcp+http:// 또는 mcp+https://로 시작하는 MCP 서버에만 적용됩니다. Stdio 및 SSE MCP 서버는 MCP OAuth를 사용하지 않습니다.

다음 단계#