AWS Labs Aurora DSQL MCP 서버

Aurora DSQL용 AWS Labs Model Context Protocol(MCP) 서버

특성

사용 가능한 도구

데이터베이스 작업

설명서 및 권장 사항

사전 조건

설치

대부분의 도구의 경우 기본 설치 지침에 따라 구성을 업데이트하는 것으로 충분합니다.

Claude Code 및 Codex에 대해서는 별도의 지침이 마련되어 있습니다.

기본 설치: 관련 MCP 구성 파일 업데이트

uv 사용하기

MCP 클라이언트 구성에서 MCP 서버 구성(MCP 구성 파일 찾기)

{
  "mcpServers": {
    "awslabs.aurora-dsql-mcp-server": {
      "command": "uvx",
      "args": [
        "awslabs.aurora-dsql-mcp-server@latest",
        "--cluster_endpoint",
        "[your dsql cluster endpoint, e.g. abcdefghijklmnopqrst234567.dsql.us-east-1.on.aws]",
        "--region",
        "[your dsql cluster region, e.g. us-east-1]",
        "--database_user",
        "[your dsql username, e.g. admin]",
        "--profile",
        "[your aws profile, e.g. default]"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Windows 설치

Windows 사용자의 경우 MCP 서버 구성 형식이 약간 다릅니다.

{
  "mcpServers": {
    "awslabs.aurora-dsql-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "awslabs.aurora-dsql-mcp-server@latest",
        "awslabs.aurora-dsql-mcp-server.exe"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

MCP 클라이언트 구성 파일 찾기

가장 일반적인 에이전틱 개발 도구의 경우 다음 파일 경로에서 MCP 클라이언트 구성을 찾을 수 있습니다.

Claude Code

사전 조건

중요: MCP 서버 관리는 VS Code 기본 패널 모드가 아닌 Claude Code CLI 터미널을 통해서만 가능합니다.

먼저 Claude의 기본 설치 권장 프로세스에 따라 Claude Code CLI를 설치합니다.

올바른 범위 선택

Claude Code는 로컬(기본값), 프로젝트, 사용자라는 세 가지 범위를 제공하며, 자격 증명의 민감도와 공유 필요성에 따라 어떤 범위를 선택해야 하는지 자세히 설명합니다. 자세한 내용은 Claude Code 설명서의 MCP 설치 범위를 참조하세요.

Claude CLI 사용(권장)

대화형 claude CLI 세션을 사용하면 문제 해결 경험이 개선되므로 이 방법이 권장됩니다.

claude mcp add amazon-aurora-dsql \
  --scope [one of local, project, or user] \
  --env FASTMCP_LOG_LEVEL="ERROR" \
  -- uvx "awslabs.aurora-dsql-mcp-server@latest" \
  --cluster_endpoint "[dsql-cluster-id].dsql.[region].on.aws" \
  --region "[dsql cluster region, eg. us-east-1]" \
  --database_user "[your-username]"

문제 해결: 다른 AWS 계정에서 Bedrock과 함께 Claude Code 사용

dsql 클러스터에 연결하는 데 필요한 프로필과 구별되는 Bedrock AWS 계정 또는 프로필로 Claude Code를 구성한 경우 추가 환경 인수를 제공해야 합니다.

  --env AWS_PROFILE="[dsql profile, eg. default]" \
  --env AWS_REGION="[dsql cluster region, eg. us-east-1]" \

구성 파일의 직접 수정

Claude Code는 영숫자 명명 규칙을 사용하므로 서버 이름을 aurora-dsql-mcp-server와 같이 지정하는 것이 좋습니다.

로컬 범위

프로젝트별 mcpServers 필드 내의 ~/.claude.json을 다음과 같이 업데이트합니다.

{
  "projects": {
    "/path/to/project": {
      "mcpServers": {}
    }
  }
}

프로젝트 범위

mcpServers 필드의 /path/to/project/root/.mcp.json을 업데이트합니다.

{
  "mcpServers": {}
}

사용자 범위

프로젝트별 mcpServers 필드 내의 ~/.claude.json을 다음과 같이 업데이트합니다.

{
  "mcpServers": {}
}

Codex

옵션 1: Codex CLI

Codex CLI가 설치된 경우 codex mcp 명령을 사용하여 MCP 서버를 구성할 수 있습니다.

codex mcp add amazon-aurora-dsql \
  --env FASTMCP_LOG_LEVEL="ERROR" \
  -- uvx "awslabs.aurora-dsql-mcp-server@latest" \
  --cluster_endpoint "[dsql-cluster-id].dsql.[region].on.aws" \
  --region "[dsql cluster region, eg. us-east-1]" \
  --database_user "[your-username]"

옵션 2: config.toml

MCP 서버 옵션을 보다 세밀하게 제어하려면 ~/.codex/config.toml 구성 파일을 수동으로 편집하면 됩니다. 각 MCP 서버는 구성 파일의 [mcp_servers.<server-name>] 테이블을 사용하여 구성됩니다.

[mcp_servers.amazon-aurora-dsql]
command = "uvx"
args = [
  "awslabs.aurora-dsql-mcp-server@latest",
  "--cluster_endpoint", "<DSQL_CLUSTER_ID>.dsql.<AWS_REGION>.on.aws",
  "--region", "<AWS_REGION>",
  "--database_user", "<DATABASE_USERNAME>"
]

[mcp_servers.amazon-aurora-dsql.env]
FASTMCP_LOG_LEVEL = "ERROR"

설치 확인

Amazon Q Developer CLI, Kiro CLI, Claude CLI/TUI 또는 Codex CLI/TUI의 경우 /mcp를 실행하여 MCP 서버의 상태를 확인합니다.

Kiro IDE의 경우 Kiro 패널의 MCP SERVERS 탭으로 이동하여 구성된 모든 MCP 서버와 연결 상태 표시기를 확인할 수도 있습니다.

서버 구성 옵션

--allow-writes

기본적으로 dsql mcp 서버는 쓰기 작업('읽기 전용 모드')을 허용하지 않습니다. 이 모드에서는 트랜잭션 도구 호출이 실패합니다. 트랜잭션 도구를 사용하려면 --allow-writes 파라미터를 전달하여 쓰기를 허용합니다.

DSQL에 연결할 때 최소 권한 액세스를 사용하는 것이 좋습니다. 예를 들어 사용자는 가능하면 읽기 전용 역할을 사용해야 합니다. 읽기 전용 모드에는 변형을 거부하기 위한 최선의 클라이언트 측 적용이 있습니다.

--cluster_endpoint

연결할 클러스터를 지정하기 위한 필수 파라미터입니다. 이는 클러스터의 전체 엔드포인트여야 합니다. 예: 01abc2ldefg3hijklmnopqurstu.dsql.us-east-1.on.aws

--database_user

이는 연결할 사용자를 지정하는 필수 파라미터입니다. 예제: admin 또는 my_user. 사용 중인 AWS 자격 증명에는 해당 사용자로 로그인할 수 있는 권한이 있어야 합니다. DSQL에서 데이터베이스 역할을 설정하고 사용하는 방법에 대한 자세한 내용은 IAM 역할로 데이터베이스 역할 사용을 참조하세요.

--profile

자격 증명에 사용할 aws 프로파일을 지정할 수 있습니다. Docker 설치에는 지원되지 않습니다.

MCP 구성에서 AWS_PROFILE 환경 변수를 사용하는 것도 지원됩니다.

"env": {
  "AWS_PROFILE": "your-aws-profile"
}

둘 다 제공되지 않으면 MCP 서버는 기본적으로 AWS 구성 파일에서 '기본' 프로파일을 사용합니다.

--region

이는 DSQL 데이터베이스의 리전을 지정하기 위한 필수 파라미터입니다.

--knowledge-server

DSQL 지식 도구(문서 검색, 읽기 및 권장 사항)에 대한 원격 MCP 서버 엔드포인트를 지정하는 선택적 파라미터입니다. 기본적으로 미리 구성되어 있습니다.

예제:

--knowledge-server https://custom-knowledge-server.example.com

참고: 보안을 위해 신뢰할 수 있는 지식 서버 엔드포인트만 사용합니다. 서버는 HTTPS 엔드포인트여야 합니다.

--knowledge-timeout

지식 서버에 대한 요청의 제한 시간을 초 단위로 지정하는 선택적 파라미터입니다.

기본값: 30.0

예제:

--knowledge-timeout 60.0

느린 네트워크의 설명서에 액세스할 때 제한 시간이 발생하면이 값을 늘립니다.