MCP 액세스 참조

요약

이 가이드는 MCP 액세스를 위한 Teleport 애플리케이션 서비스와 상호 작용하기 위한 인터페이스 및 옵션을 설명합니다. 다음 스니펫은 teleport.yaml 구성 파일에 나타나는 애플리케이션 서비스의 전체 YAML 구성을 보여줍니다:

이 가이드는 MCP 액세스를 위한 Teleport 애플리케이션 서비스와 상호 작용하기 위한 인터페이스 및 옵션을 설명합니다. 여기에는 teleport 바이너리의 정적 구성 파일과 tsh mcp 명령이 포함됩니다.

구성#

다음 스니펫은 teleport.yaml 구성 파일에 나타나는 애플리케이션 서비스의 전체 YAML 구성을 보여줍니다:

app_service:
  # 애플리케이션 프록시 서비스를 활성화합니다.
  enabled: true
  # 현재 사용자 및 세션 정보를 표시하는 내장 Teleport 데모 MCP 서버를 활성화합니다.
  # 이 MCP 서버에 액세스하려면 값이 "demo"인 앱 레이블
  # "teleport.internal/resource-type"을 사용합니다.
  mcp_demo_server: true
  # 이 섹션에는 이 서비스로 프록시되는 모든 애플리케이션의 정의가 포함됩니다.
  # 여러 항목을 포함할 수 있습니다.
  apps:
  # 애플리케이션의 이름. 식별 목적으로 사용됩니다.
  - name: "mcp-everything"
    # 대상 MCP 서버의 엔드포인트 URI.
    # 스트리머블 HTTP MCP 서버에는 "mcp+http://" 및 "mcp+https://"를 스킴으로 사용합니다.
    # SSE MCP 서버에는 "mcp+sse+http://" 및 "mcp+sse+https://"를 스킴으로 사용합니다.
    # stdio MCP 서버에는 비워두거나 "mcp+stdio://"를 사용합니다.
    uri: "mcp+http://localhost:12345/mcp"
    # 자유 형식의 애플리케이션 설명.
    description: "Example Everything MCP server"
    # 앱에 할당할 정적 레이블. RBAC에서 사용됩니다.
    labels:
      env: "prod"

    # MCP 서버 관련 구성을 포함합니다.
    mcp:
      # stdio 기반 MCP 서버를 실행하는 명령.
      command: "docker"
      # 명령과 함께 실행할 인수.
      args: ["run", "-i", "--rm", "mcp/everything"]
      # 명령이 실행될 호스트 사용자 계정 이름.
      # stdio 기반 MCP 서버에 필요합니다.
      run_as_host_user: "docker"

    # SSE 및 스트리머블 HTTP MCP 서버의 TLS 유효성 검사를 비활성화합니다.
    insecure_skip_verify: true
    # SSE 및 스트리머블 HTTP MCP 서버의 리라이트 섹션.
    rewrite:
      # JWT에 역할 또는 특성을 포함할지 여부를 지정합니다.
      # 옵션:
      # - roles-and-traits: 역할과 특성 모두 포함
      # - roles: 역할만 포함
      # - traits: 특성만 포함
      # - none: JWT 토큰에서 역할과 특성 모두 제외
      # 기본값: roles-and-traits
      jwt_claims: roles-and-traits
      # 헤더 통과 구성.
      headers:
      - "Authorization: Bearer {{internal.jwt}}"
      - "X-Custom-Header: example"
      - "X-External-Trait: {{external.env}}"

리소스#

MCP 서버 리소스는 Teleport 백엔드에서 app 리소스로 등록됩니다. 다음은 tctl 리소스 명령으로 관리되는 MCP 서버 리소스의 스펙입니다:

kind: app
version: v3
metadata:
  # MCP 서버 이름
  name: everything
  # MCP 서버 설명.
  description: The Everything MCP server
  # MCP 서버 레이블.
  labels:
    env: local
spec:
  # 대상 MCP 서버의 엔드포인트 URI.
  # 스트리머블 HTTP MCP 서버에는 "mcp+http://" 및 "mcp+https://"를 스킴으로 사용합니다.
  # SSE MCP 서버에는 "mcp+sse+http://" 및 "mcp+sse+https://"를 스킴으로 사용합니다.
  # stdio MCP 서버에는 비워두거나 "mcp+stdio://"를 사용합니다.
  uri: "mcp+http://localhost:12345/mcp"

  mcp:
    # stdio 기반 MCP 서버를 실행하는 명령.
    command: "docker"
    # 명령과 함께 실행할 인수.
    args: ["run", "-i", "--rm", "mcp/everything"]
    # 명령이 실행될 호스트 사용자 계정 이름.
    # stdio 기반 MCP 서버에 필요합니다.
    run_as_host_user: "docker"

  # SSE 및 스트리머블 HTTP MCP 서버의 TLS 유효성 검사를 비활성화합니다.
  insecure_skip_verify: true
  # SSE 및 스트리머블 HTTP MCP 서버의 리라이트 섹션.
  rewrite:
    # JWT에 역할 또는 특성을 포함할지 여부를 지정합니다.
    # 옵션:
    # - roles-and-traits: 역할과 특성 모두 포함
    # - roles: 역할만 포함
    # - traits: 특성만 포함
    # - none: JWT 토큰에서 역할과 특성 모두 제외
    # 기본값: roles-and-traits
    jwt_claims: roles-and-traits
    # 헤더 통과 구성.
    headers:
    - "Authorization: Bearer {{internal.jwt}}"
    - "X-Custom-Header: example"
    - "X-External-Trait: {{external.env}}"

CLI#

이 섹션은 MCP 액세스와 관련된 CLI 명령을 보여줍니다.

tsh mcp ls#

사용 가능한 MCP 서버 목록을 표시합니다.

# 모든 MCP 서버 목록 표시.
$ tsh mcp ls
# 키워드로 MCP 서버 검색.
$ tsh mcp ls --search foo,bar
# 레이블로 MCP 서버 필터링.
$ tsh mcp ls key1=value1,key2=value2
# "jq"를 사용하여 MCP 서버 이름 가져오기.
$ tsh mcp ls --format json  | jq -r '.[].metadata.name'

플래그	설명
`--search`	쉼표로 구분된 검색 키워드 또는 따옴표로 묶인 구절 목록 (예: `--search=foo,bar,"some phrase"`).
`--query`	단일 따옴표로 묶인 술어 언어로 쿼리 (예: `--query='labels["key1"] == "value1" && labels["key2"] != "value2"'`).
`--format`	출력 형식 (`text`, `json`, `yaml`).

tsh mcp config#

클라이언트 구성 세부 정보를 출력하거나 구성을 직접 업데이트합니다.

# MCP 서버 앱의 샘플 구성 출력
$ tsh mcp config my-mcp-server-app
# 사용자 정의 헤더가 있는 스트리머블 HTTP MCP 서버의 샘플 구성 출력
$ tsh mcp config my-mcp-server-app -H "Header1: value1" -H "Header2: value2"
# 모든 MCP 서버를 Claude Desktop에 추가
$ tsh mcp config --all --client-config=claude
# 레이블로 MCP 서버를 검색하여 지정된 JSON 파일에 추가
$ tsh mcp config --labels env=dev --client-config=my-config.json`

플래그	설명
`--all`	모든 MCP 서버 선택. `--labels` 또는 `--query`와 상호 배타적.
`--labels`	레이블로 필터링하기 위한 쉼표로 구분된 레이블 목록 (예: key1=value1,key2=value2).
`--query`	단일 따옴표로 묶인 술어 언어로 쿼리 (예: `--query='labels["key1"] == "value1" && labels["key2"] != "value2"'`).
`--client-config`	지정된 경우 지정한 클라이언트 구성을 업데이트합니다. 기본 Claude Desktop 구성에는 `claude`, 또는 JSON 파일 경로를 지정합니다. 환경 변수 `TELEPORT_MCP_CLIENT_CONFIG`으로도 설정 가능.",
`--json-format`	JSON 파일 형식 지정 (`pretty`, `compact`, `auto`, `none`). `auto`는 파일이 이미 컴팩트한 경우 컴팩트로, 그렇지 않으면 pretty로 저장합니다. 환경 변수 `TELEPORT_MCP_CONFIG_JSON_FORMAT`으로도 설정 가능합니다. 기본값은 `auto`.",
`-H`, `--header`	스트리머블 HTTP MCP 서버에 사용되는 추가 사용자 정의 헤더.

tsh mcp connect#

Claude Desktop과 같은 AI 도구가 Teleport를 통해 MCP 서버에 연결하는 데 사용됩니다.

Tip

tsh mcp config는 샘플 구성을 출력하거나 AI 도구를 직접 업데이트할 수 있습니다. 이를 통해 tsh mcp connect 명령을 수동으로 구성할 필요가 없습니다.

$ tsh mcp connect mcp-everything

tsh 디버그 로그는 기본적으로 활성화되어 있으며 환경 변수 TELEPORT_DEBUG=false로 비활성화할 수 있습니다. tsh mcp config로 샘플 구성을 생성할 때 --no-debug 플래그를 지정할 수도 있습니다.

tsh proxy mcp#

MCP 연결을 위한 로컬 프록시를 시작합니다. 스트리머블 HTTP 전송을 사용하는 대상 MCP 서버만 지원됩니다.

$ tsh proxy mcp my-streamable-http-mcp-server

MCP 액세스 참조

원문 보기

번역일: 2026-04-04

요약

구성#

다음 스니펫은 teleport.yaml 구성 파일에 나타나는 애플리케이션 서비스의 전체 YAML 구성을 보여줍니다:

app_service:
  # 애플리케이션 프록시 서비스를 활성화합니다.
  enabled: true
  # 현재 사용자 및 세션 정보를 표시하는 내장 Teleport 데모 MCP 서버를 활성화합니다.
  # 이 MCP 서버에 액세스하려면 값이 "demo"인 앱 레이블
  # "teleport.internal/resource-type"을 사용합니다.
  mcp_demo_server: true
  # 이 섹션에는 이 서비스로 프록시되는 모든 애플리케이션의 정의가 포함됩니다.
  # 여러 항목을 포함할 수 있습니다.
  apps:
  # 애플리케이션의 이름. 식별 목적으로 사용됩니다.
  - name: "mcp-everything"
    # 대상 MCP 서버의 엔드포인트 URI.
    # 스트리머블 HTTP MCP 서버에는 "mcp+http://" 및 "mcp+https://"를 스킴으로 사용합니다.
    # SSE MCP 서버에는 "mcp+sse+http://" 및 "mcp+sse+https://"를 스킴으로 사용합니다.
    # stdio MCP 서버에는 비워두거나 "mcp+stdio://"를 사용합니다.
    uri: "mcp+http://localhost:12345/mcp"
    # 자유 형식의 애플리케이션 설명.
    description: "Example Everything MCP server"
    # 앱에 할당할 정적 레이블. RBAC에서 사용됩니다.
    labels:
      env: "prod"

    # MCP 서버 관련 구성을 포함합니다.
    mcp:
      # stdio 기반 MCP 서버를 실행하는 명령.
      command: "docker"
      # 명령과 함께 실행할 인수.
      args: ["run", "-i", "--rm", "mcp/everything"]
      # 명령이 실행될 호스트 사용자 계정 이름.
      # stdio 기반 MCP 서버에 필요합니다.
      run_as_host_user: "docker"

    # SSE 및 스트리머블 HTTP MCP 서버의 TLS 유효성 검사를 비활성화합니다.
    insecure_skip_verify: true
    # SSE 및 스트리머블 HTTP MCP 서버의 리라이트 섹션.
    rewrite:
      # JWT에 역할 또는 특성을 포함할지 여부를 지정합니다.
      # 옵션:
      # - roles-and-traits: 역할과 특성 모두 포함
      # - roles: 역할만 포함
      # - traits: 특성만 포함
      # - none: JWT 토큰에서 역할과 특성 모두 제외
      # 기본값: roles-and-traits
      jwt_claims: roles-and-traits
      # 헤더 통과 구성.
      headers:
      - "Authorization: Bearer {{internal.jwt}}"
      - "X-Custom-Header: example"
      - "X-External-Trait: {{external.env}}"

리소스#

MCP 서버 리소스는 Teleport 백엔드에서 app 리소스로 등록됩니다. 다음은 tctl 리소스 명령으로 관리되는 MCP 서버 리소스의 스펙입니다:

kind: app
version: v3
metadata:
  # MCP 서버 이름
  name: everything
  # MCP 서버 설명.
  description: The Everything MCP server
  # MCP 서버 레이블.
  labels:
    env: local
spec:
  # 대상 MCP 서버의 엔드포인트 URI.
  # 스트리머블 HTTP MCP 서버에는 "mcp+http://" 및 "mcp+https://"를 스킴으로 사용합니다.
  # SSE MCP 서버에는 "mcp+sse+http://" 및 "mcp+sse+https://"를 스킴으로 사용합니다.
  # stdio MCP 서버에는 비워두거나 "mcp+stdio://"를 사용합니다.
  uri: "mcp+http://localhost:12345/mcp"

  mcp:
    # stdio 기반 MCP 서버를 실행하는 명령.
    command: "docker"
    # 명령과 함께 실행할 인수.
    args: ["run", "-i", "--rm", "mcp/everything"]
    # 명령이 실행될 호스트 사용자 계정 이름.
    # stdio 기반 MCP 서버에 필요합니다.
    run_as_host_user: "docker"

  # SSE 및 스트리머블 HTTP MCP 서버의 TLS 유효성 검사를 비활성화합니다.
  insecure_skip_verify: true
  # SSE 및 스트리머블 HTTP MCP 서버의 리라이트 섹션.
  rewrite:
    # JWT에 역할 또는 특성을 포함할지 여부를 지정합니다.
    # 옵션:
    # - roles-and-traits: 역할과 특성 모두 포함
    # - roles: 역할만 포함
    # - traits: 특성만 포함
    # - none: JWT 토큰에서 역할과 특성 모두 제외
    # 기본값: roles-and-traits
    jwt_claims: roles-and-traits
    # 헤더 통과 구성.
    headers:
    - "Authorization: Bearer {{internal.jwt}}"
    - "X-Custom-Header: example"
    - "X-External-Trait: {{external.env}}"

CLI#

이 섹션은 MCP 액세스와 관련된 CLI 명령을 보여줍니다.

tsh mcp ls#

사용 가능한 MCP 서버 목록을 표시합니다.

# 모든 MCP 서버 목록 표시.
$ tsh mcp ls
# 키워드로 MCP 서버 검색.
$ tsh mcp ls --search foo,bar
# 레이블로 MCP 서버 필터링.
$ tsh mcp ls key1=value1,key2=value2
# "jq"를 사용하여 MCP 서버 이름 가져오기.
$ tsh mcp ls --format json  | jq -r '.[].metadata.name'

플래그	설명
`--search`	쉼표로 구분된 검색 키워드 또는 따옴표로 묶인 구절 목록 (예: `--search=foo,bar,"some phrase"`).
`--query`	단일 따옴표로 묶인 술어 언어로 쿼리 (예: `--query='labels["key1"] == "value1" && labels["key2"] != "value2"'`).
`--format`	출력 형식 (`text`, `json`, `yaml`).

tsh mcp config#

클라이언트 구성 세부 정보를 출력하거나 구성을 직접 업데이트합니다.

# MCP 서버 앱의 샘플 구성 출력
$ tsh mcp config my-mcp-server-app
# 사용자 정의 헤더가 있는 스트리머블 HTTP MCP 서버의 샘플 구성 출력
$ tsh mcp config my-mcp-server-app -H "Header1: value1" -H "Header2: value2"
# 모든 MCP 서버를 Claude Desktop에 추가
$ tsh mcp config --all --client-config=claude
# 레이블로 MCP 서버를 검색하여 지정된 JSON 파일에 추가
$ tsh mcp config --labels env=dev --client-config=my-config.json`

플래그	설명
`--all`	모든 MCP 서버 선택. `--labels` 또는 `--query`와 상호 배타적.
`--labels`	레이블로 필터링하기 위한 쉼표로 구분된 레이블 목록 (예: key1=value1,key2=value2).
`--query`	단일 따옴표로 묶인 술어 언어로 쿼리 (예: `--query='labels["key1"] == "value1" && labels["key2"] != "value2"'`).
`--client-config`	지정된 경우 지정한 클라이언트 구성을 업데이트합니다. 기본 Claude Desktop 구성에는 `claude`, 또는 JSON 파일 경로를 지정합니다. 환경 변수 `TELEPORT_MCP_CLIENT_CONFIG`으로도 설정 가능.",
`--json-format`	JSON 파일 형식 지정 (`pretty`, `compact`, `auto`, `none`). `auto`는 파일이 이미 컴팩트한 경우 컴팩트로, 그렇지 않으면 pretty로 저장합니다. 환경 변수 `TELEPORT_MCP_CONFIG_JSON_FORMAT`으로도 설정 가능합니다. 기본값은 `auto`.",
`-H`, `--header`	스트리머블 HTTP MCP 서버에 사용되는 추가 사용자 정의 헤더.

tsh mcp connect#

Claude Desktop과 같은 AI 도구가 Teleport를 통해 MCP 서버에 연결하는 데 사용됩니다.

Tip

tsh mcp config는 샘플 구성을 출력하거나 AI 도구를 직접 업데이트할 수 있습니다. 이를 통해 tsh mcp connect 명령을 수동으로 구성할 필요가 없습니다.

$ tsh mcp connect mcp-everything

tsh proxy mcp#

MCP 연결을 위한 로컬 프록시를 시작합니다. 스트리머블 HTTP 전송을 사용하는 대상 MCP 서버만 지원됩니다.

$ tsh proxy mcp my-streamable-http-mcp-server