이 가이드는 MCP 클라이언트로 PostgreSQL Teleport 데이터베이스에 연결하는 방법을 설명합니다.

사전 요구 사항#

• A running Teleport 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:

• PostgreSQL 데이터베이스가 등록된 Teleport Database Service. Teleport에 PostgreSQL 데이터베이스를 등록하는 방법에 대한 옵션은 가이드를 참조하세요. AWS RDS PostgreSQL 및 자체 호스팅 PostgreSQL 가이드가 포함됩니다.

CREATE ROLE mcp_read_only WITH LOGIN;
GRANT CONNECT ON DATABASE my_database TO mcp_read_only;
GRANT USAGE ON SCHEMA public TO mcp_read_only;
GRANT SELECT ON my_table TO mcp_read_only;                     -- To grant read access to a single table.
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_read_only; -- To grant read access to all tables in the "public" schema.

GRANT rds_iam TO mcp_read_only; -- If connecting to a PostgreSQL RDS database.

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

먼저, tsh login을 사용하여 Teleport 클러스터에 로그인합니다:

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

접근 권한이 있는 데이터베이스만 MCP 서버로 노출할 수 있습니다. tsh db ls를 사용하여 데이터베이스 목록과 연결 옵션을 조회할 수 있습니다:

$ tsh db ls
# Name            Description          Allowed Users      Labels 
# --------------- -------------------- ------------------ -------
# postgres-dev    Development database [* postgres]       env=dev
# postgres-prod   Production database  [mcp_read_only]    env=prod

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

MCP를 통해 접근하려는 각 데이터베이스는 MCP 클라이언트에 개별적으로 구성해야 합니다. 이는 tsh mcp db config 명령어를 사용하여 수행됩니다. tsh db connect와 마찬가지로, 이 명령어는 MCP 연결에 사용할 데이터베이스 사용자와 데이터베이스 이름을 선택해야 합니다.

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

$ tsh mcp db config --db-user=postgres --db-name=employees --client-config=claude postgres-dev
Added database "postgres-dev" on the client configuration at:
~/Library/Application Support/Claude/claude_desktop_config.json

Teleport database access MCP server is named "teleport-databases" in this configuration.

You may need to restart your client to reload these new configurations.

$ tsh mcp db config --db-user=postgres --db-name=employees --client-config=/path/to/config.json postgres-dev

$ tsh mcp db config --db-user=postgres --db-name=employees --client-config=cursor postgres-dev
Added database "postgres-dev" on the client configuration at:
/your/home/path/.cursor/mcp.json

Teleport database access MCP server is named "teleport-databases" in this configuration.

You may need to restart your client to reload these new configurations.

$ tsh mcp db config --db-user=postgres --db-name=employees --client-config=/path/to/project/.cursor/mcp.json postgres-dev

$ tsh mcp db config --db-user=postgres --db-name=employees postgres-dev
Here is a sample JSON configuration for launching Teleport MCP servers:
{
  "mcpServers": {
    "teleport-databases": {
      "command": "tsh",
      "args": [
        "mcp",
        "db",
        "start",
        "teleport://clusters//databases/postgres-dev?dbName=employees&dbUser=postgres"
      ]
    }
  }
}

If you already have an entry for "teleport-databases" server, add the following database resource URI to the command arguments list:
teleport://clusters//databases/postgres-dev?dbName=employees&dbUser=postgres

MCP 클라이언트를 구성한 후, 다음 도구를 사용할 수 있습니다:

• teleport_list_databases: Teleport 도구로 접근 가능한 데이터베이스 리소스를 나열합니다.
• teleport_postgres_query (PostgreSQL 데이터베이스만 해당): Teleport를 통해 지정된 데이터베이스에서 SQL 쿼리를 실행합니다.

또한, 제공되는 데이터베이스는 MCP 리소스로 사용할 수 있습니다. 대화에 첨부하여 추가적인 컨텍스트를 제공할 수 있습니다. 동작은 MCP 클라이언트마다 다를 수 있습니다.

이제 이 도구를 사용하여 데이터베이스에서 쿼리를 실행할 수 있습니다. 다음은 Claude Desktop을 사용하여 연결을 테스트하고 데이터베이스 버전을 검색하는 예시입니다:

문제 해결#

데이터베이스 목록이 비어있거나 teleport_postgres_query 도구가 누락됨#

이는 MCP 서버 명령어(tsh mcp db start)에 잘못된 데이터베이스 목록이나 옵션이 있는 경우 발생합니다. 데이터베이스 URI 목록이 올바른지 확인하세요. tsh mcp db config 명령어를 사용하여 생성할 수 있습니다.

이 경우에도 teleport_list_databases를 확인하고 호출할 수 있으며, 진행 방법에 대한 지침을 제공합니다.

tsh 세션 만료#

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

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

접근 거부 오류#

쿼리를 실행하는 동안 접근 거부 응답을 받으면, 사용자가 구성된 데이터베이스에 접근할 권한이 있는지 확인하세요. MCP 서버를 시작하기 전에 tsh db connect를 실행하여 확인할 수 있습니다.

예를 들어, 다음과 같이 데이터베이스를 구성했다면:

$ tsh mcp db config --db-user=postgres --db-name=employees postgres-dev

다음을 실행하여 접근을 테스트할 수 있어야 합니다:

$ tsh db connect --db-user=postgres --db-name=employees postgres-dev