MCP Reference: cloud-sql

모델 컨텍스트 프로토콜 (MCP) 서버는 대규모 언어 모델 (LLM) 또는 AI 애플리케이션에 컨텍스트, 데이터 또는 기능을 제공하는 외부 서비스 간의 프록시 역할을 합니다. MCP 서버는 AI 애플리케이션을 데이터베이스 및 웹 서비스와 같은 외부 시스템에 연결하여 AI 애플리케이션이 이해할 수 있는 형식으로 응답을 변환합니다.

서버 설정

사용하기 전에 MCP 서버를 사용 설정하고 인증을 설정해야 합니다. Google 및 Google Cloud 원격 MCP 서버 사용에 대한 자세한 내용은 Google Cloud MCP 서버 개요를 참고하세요.

MCP용 Cloud SQL Admin API

서버 엔드포인트

MCP 서비스 엔드포인트는 AI 애플리케이션 (MCP 클라이언트의 호스트)이 보안 표준 연결을 설정하는 데 사용하는 MCP 서버의 네트워크 주소 및 통신 인터페이스 (일반적으로 URL)입니다. LLM이 컨텍스트를 요청하거나, 도구를 호출하거나, 리소스에 액세스할 때 사용하는 연락처입니다. Google MCP 엔드포인트는 전역 또는 리전일 수 있습니다.

cloud-sql MCP 서버에는 다음과 같은 MCP 엔드포인트가 있습니다.

• https://sqladmin.googleapis.com/mcp

MCP 도구

MCP 도구는 MCP 서버가 LLM 또는 AI 애플리케이션에 노출하여 실제 작업을 실행하는 함수 또는 실행 가능한 기능입니다.

cloud-sql MCP 서버에는 다음 도구가 있습니다.

MCP 도구
list_instances	프로젝트의 모든 Cloud SQL 인스턴스를 나열합니다.
get_instance	Cloud SQL 인스턴스의 세부정보를 가져옵니다.
create_instance	Cloud SQL 인스턴스 생성을 시작합니다. 이 도구는 장기 실행 작업을 반환합니다. 작업이 완료될 때까지 get_operation 도구를 사용하여 상태를 폴링합니다. 인스턴스 생성 작업은 몇 분 정도 걸릴 수 있습니다. 명령줄 도구를 사용하여 30초 동안 일시중지한 후 상태를 다시 확인합니다. create_instance 도구를 사용하여 인스턴스를 만든 후 create_user 도구를 사용하여 현재 프로젝트에 로그인한 사용자의 IAM 사용자 계정을 만들 수 있습니다. data_api_access의 값은 기본적으로 ALLOW_DATA_API로 설정됩니다. 이 설정을 사용하면 execute_sql 도구와 executeSql API를 사용하여 SQL 문을 실행할 수 있습니다. 달리 지정하지 않는 한 새로 생성된 인스턴스는 개발 환경의 기본 인스턴스 구성을 사용합니다. 다음은 개발 환경의 인스턴스에 대한 기본 구성입니다. { "tier": "db-perf-optimized-N-2", "data_disk_size_gb": 100, "region": "us-central1", "database_version": "POSTGRES_18", "edition": "ENTERPRISE_PLUS", "availability_type": "ZONAL", "tags": [{"environment": "dev"}] } 프로덕션 환경의 인스턴스에는 다음 구성을 사용하는 것이 좋습니다. { "tier": "db-perf-optimized-N-8", "data_disk_size_gb": 250, "region": "us-central1", "database_version": "POSTGRES_18", "edition": "ENTERPRISE_PLUS", "availability_type": "REGIONAL", "tags": [{"environment": "prod"}] } SQL Server에는 다음 인스턴스 구성이 권장됩니다. { "tier": "db-perf-optimized-N-8", "data_disk_size_gb": 250, "region": "us-central1", "database_version": "SQLSERVER_2022_STANDARD", "edition": "ENTERPRISE_PLUS", "availability_type": "REGIONAL", "tags": [{"environment": "prod"}] }
execute_sql	Cloud SQL 인스턴스에서 데이터 정의 언어 (DDL), 데이터 제어 언어 (DCL), 데이터 쿼리 언어 (DQL) 또는 데이터 조작 언어 (DML) 문을 비롯한 유효한 SQL 문을 실행합니다. execute_sql 도구를 지원하려면 Cloud SQL 인스턴스가 다음 요구사항을 충족해야 합니다. data_api_access의 값은 ALLOW_DATA_API로 설정해야 합니다. MySQL 인스턴스의 경우 데이터베이스 플래그 cloudsql_iam_authentication을 on으로 설정해야 합니다. PostgreSQL 인스턴스의 경우 데이터베이스 플래그 cloudsql.iam_authentication를 on로 설정해야 합니다. execute_sql 도구를 호출하려면 IAM 사용자 계정 또는 IAM 서비스 계정 (CLOUD_IAM_USER 또는 CLOUD_IAM_SERVICE_ACCOUNT)이 필요합니다. 이 도구는 IAM 데이터베이스 인증으로 로그인한 데이터베이스 사용자의 권한을 사용하여 SQL 문을 실행합니다. create_instance 도구를 사용하여 인스턴스를 만든 후 create_user 도구를 사용하여 현재 프로젝트에 로그인한 사용자의 IAM 사용자 계정을 만들 수 있습니다. execute_sql 도구에는 다음과 같은 제한사항이 있습니다. SQL 문이 10MB보다 큰 응답을 반환하면 응답이 잘립니다. execute_sql 도구의 기본 제한 시간은 30초입니다. 쿼리가 30초 이상 실행되면 도구에서 DEADLINE_EXCEEDED 오류를 반환합니다. SQL Server에는 execute_sql 도구가 지원되지 않습니다. '인스턴스에 IAM 인증이 사용 설정되지 않음'과 같은 오류가 표시되면 get_instance 도구를 사용하여 인스턴스의 IAM 데이터베이스 인증 플래그 값을 확인할 수 있습니다. '인스턴스에서 executeSql을 사용하여 이 인스턴스에 액세스할 수 없습니다'와 같은 오류가 표시되면 get_instance 도구를 사용하여 data_api_access 설정을 확인할 수 있습니다. 인증 오류가 표시되는 경우: list_users 도구를 사용하여 현재 로그인한 사용자 계정이 인스턴스에 IAM 사용자로 있는지 확인합니다. IAM 사용자 계정이 없으면 create_user 도구를 사용하여 로그인한 사용자의 IAM 사용자 계정을 만듭니다. 현재 로그인한 사용자에게 적절한 데이터베이스 사용자 역할이 없는 경우 update_user 도구를 사용하여 사용자에게 데이터베이스 역할을 부여할 수 있습니다. 예를 들어 cloudsqlsuperuser 역할은 IAM 사용자에게 필요한 많은 권한을 제공할 수 있습니다. 현재 로그인한 사용자에게 프로젝트에 올바른 IAM 권한이 할당되어 있는지 확인합니다. gcloud projects get-iam-policy [PROJECT_ID] 명령어를 사용하여 사용자에게 프로젝트에 적합한 IAM 역할 또는 권한이 할당되어 있는지 확인할 수 있습니다. 자동 IAM 데이터베이스 인증을 수행하려면 사용자에게 cloudsql.instance.login 권한이 있어야 합니다. execute_sql 도구 또는 executeSql API를 사용하여 SQL 문을 실행하려면 사용자에게 cloudsql.instances.executeSql 권한이 있어야 합니다. 필요한 권한이 포함된 일반적인 IAM 역할: Cloud SQL 인스턴스 사용자 (roles/cloudsql.instanceUser) 또는 Cloud SQL 관리자 (roles/cloudsql.admin) ExecuteSqlResponse를 수신할 때는 항상 응답 본문 내의 message 및 status 필드를 확인하세요. HTTP 상태 코드가 성공이라고 해서 모든 SQL 문이 완전히 성공하는 것은 아닙니다. message 및 status 필드는 SQL 문 실행 중에 부분 오류나 경고가 있었는지 여부를 나타냅니다.
get_operation	장기 실행 작업 상태를 가져옵니다. 장기 실행 작업은 완료하는 데 몇 분 정도 걸릴 수 있습니다. 작업에 시간이 오래 걸리는 경우 명령줄 도구를 사용하여 30초 동안 일시중지한 후 작업 상태를 다시 확인합니다.
create_user	Cloud SQL 인스턴스의 데이터베이스 사용자를 만듭니다. 이 도구는 장기 실행 작업을 반환합니다. get_operation 도구를 사용하여 작업이 완료될 때까지 상태를 폴링합니다. create_user 도구를 사용할 때는 사용자 유형(CLOUD_IAM_USER 또는 CLOUD_IAM_SERVICE_ACCOUNT)을 지정합니다. 요청에 다른 데이터베이스 역할을 명시적으로 지정하지 않는 한 새로 생성된 사용자에게는 기본적으로 cloudsqlsuperuser 역할이 할당됩니다. 현재 로그인된 IAM 사용자인 경우 execute_sql 도구로 새로 생성된 사용자를 사용할 수 있습니다. execute_sql 도구는 IAM 데이터베이스 인증을 사용하여 로그인한 데이터베이스 사용자의 권한을 사용하여 SQL 문을 실행합니다. create_user 도구에는 다음과 같은 제한사항이 있습니다. 비밀번호가 있는 기본 제공 사용자는 만들 수 없습니다. create_user 도구는 SQL Server용 사용자 만들기를 지원하지 않습니다. PostgreSQL에서 IAM 사용자를 만들려면 다음 단계를 따르세요. 데이터베이스 사용자 이름은 IAM 사용자의 이메일 주소여야 하며 모두 소문자여야 합니다. 예를 들어 PostgreSQL IAM 사용자 [e-mail]의 사용자를 만들려면 다음 요청을 사용하면 됩니다. { "name": "[e-mail]", "type": "CLOUD_IAM_USER", "instance":"test-instance", "project": "test-project" } IAM 사용자를 위해 생성된 데이터베이스 사용자 이름은 [e-mail]입니다. PostgreSQL에서 IAM 서비스 계정을 만들려면 다음 단계를 따르세요. 계정의 전체 이메일 주소가 [e-mail]이더라도 데이터베이스 사용자 이름은 .gserviceaccount.com 서픽스 없이 만들어야 합니다. 예를 들어 PostgreSQL용 IAM 서비스 계정을 만들려면 다음 요청 형식을 사용하면 됩니다. { "name": "[e-mail]", "type": "CLOUD_IAM_SERVICE_ACCOUNT", "instance": "test-instance", "project": "test-project" } IAM 서비스 계정에 대해 생성된 데이터베이스 사용자 이름은 [e-mail]입니다. MySQL에서 IAM 사용자 또는 IAM 서비스 계정을 만들려면 다음 단계를 따르세요. MySQL용 Cloud SQL이 사용자 이름을 저장하면 사용자 또는 서비스 계정의 이메일 주소에서 @ 및 도메인 이름이 잘립니다. 예를 들어 [e-mail]는 example-user가 됩니다. 따라서 사용자 이름은 동일하지만 도메인 이름이 다른 두 개의 IAM 사용자 또는 서비스 계정을 동일한 Cloud SQL 인스턴스에 추가할 수 없습니다. 예를 들어 MySQL IAM 사용자 [e-mail]의 사용자를 만들려면 다음 요청을 사용합니다. { "name": "[e-mail]", "type": "CLOUD_IAM_USER", "instance": "test-instance", "project": "test-project" } IAM 사용자를 위해 생성된 데이터베이스 사용자 이름은 example-user입니다. 예를 들어 MySQL IAM 서비스 계정 [e-mail]를 만들려면 다음 요청을 사용합니다. { "name": "[e-mail]", "type": "CLOUD_IAM_SERVICE_ACCOUNT", "instance": "test-instance", "project": "test-project" } IAM 서비스 계정에 대해 생성된 데이터베이스 사용자 이름은 service-account-name입니다.
update_user	Cloud SQL 인스턴스의 데이터베이스 사용자를 업데이트합니다. update_user의 일반적인 사용 사례는 사용자에게 cloudsqlsuperuser 역할을 부여하는 것입니다. 이 역할은 사용자에게 필요한 많은 권한을 제공할 수 있습니다. 이 도구는 데이터베이스 역할을 할당하기 위해 사용자를 업데이트하는 것만 지원합니다. 이 도구는 장기 실행 작업을 반환합니다. 작업이 완료될 때까지 get_operation 도구를 사용하여 상태를 폴링합니다. update_user 도구를 호출하기 전에 항상 list_users 도구를 사용하여 사용자 유형과 같은 사용자의 기존 구성을 확인하세요. MySQL의 특별한 경우로, list_users 도구가 iamEmail 필드에 전체 이메일 주소(예: {name=test-account, iamEmail=[e-mail]})를 반환하는 경우 update_user 요청에서 도구 요청의 name 필드에 있는 iamEmail 필드에 전체 이메일 주소를 사용합니다. 예를 들면 name=[e-mail]입니다. 사용자 역할을 업데이트하기 위한 주요 매개변수: database_roles: 사용자에게 할당할 데이터베이스 역할 목록입니다. revokeExistingRoles: 기존 역할을 처리하는 방법을 제어하는 불리언 필드입니다 (기본값: false). 역할 업데이트 작동 방식: revokeExistingRoles이 true인 경우: 사용자에게 부여되었지만 제공된 database_roles 목록에 없는 기존 역할은 취소됩니다. 취소는 시스템이 아닌 역할에만 적용됩니다. cloudsqliamuser 등의 시스템 역할은 취소되지 않습니다. 사용자가 아직 보유하지 않은 database_roles 목록의 역할은 부여됩니다. database_roles가 비어 있으면 기존의 모든 비시스템 역할이 취소됩니다. revokeExistingRoles이 false인 경우 (기본값): 사용자가 아직 보유하지 않은 database_roles 목록의 역할은 부여됩니다. database_roles 목록에 없는 기존 역할은 유지됩니다. database_roles가 비어 있으면 사용자의 역할이 변경되지 않습니다. 예: 기존 역할: [roleA, roleB] 요청: database_roles: [roleB, roleC], revokeExistingRoles: true 결과: roleA가 취소되고 roleC가 부여됩니다. 사용자 역할이 [roleB, roleC]이 됩니다. 요청: database_roles: [roleB, roleC], revokeExistingRoles: false 결과: roleC 권한을 부여합니다. 사용자 역할이 [roleA, roleB, roleC]이 됩니다. 요청: database_roles: [], revokeExistingRoles: true 결과: roleA 취소, roleB 취소 사용자 역할이 []이 됩니다. 요청: database_roles: [], revokeExistingRoles: false 결과: 변경사항 없음 사용자 역할은 [roleA, roleB]로 유지됩니다.
clone_instance	Cloud SQL 인스턴스를 소스 인스턴스의 클론으로 만듭니다. 이 도구는 장기 실행 작업을 반환합니다. 작업이 완료될 때까지 get_operation 도구를 사용하여 상태를 폴링합니다. 복제 작업은 몇 분 정도 걸릴 수 있습니다. 명령줄 도구를 사용하여 30초 동안 일시중지한 후 상태를 다시 확인합니다.
update_instance	Cloud SQL 인스턴스의 구성 설정을 부분적으로 업데이트합니다. 이 도구는 장기 실행 작업을 반환합니다. get_operation 도구를 사용하여 작업이 완료될 때까지 상태를 폴링합니다.
list_users	Cloud SQL 인스턴스의 모든 데이터베이스 사용자를 나열합니다.
import_data	Cloud SQL 인스턴스로 데이터를 가져옵니다. 파일이 gs://로 시작하지 않으면 파일이 로컬에 저장된 것으로 간주됩니다. 파일이 로컬인 경우 실제 import_data 호출을 하기 전에 파일을 Cloud Storage에 업로드해야 합니다. Cloud Storage에 파일을 업로드하려면 gcloud 또는 gsutil 명령어를 사용하면 됩니다. Cloud Storage에 파일을 업로드하기 전에 제공된 프로젝트에서 기존 버킷을 사용할지 아니면 새 버킷을 만들지 고려하세요. 파일이 Cloud Storage에 업로드된 후 인스턴스 서비스 계정에는 Cloud Storage 버킷에서 업로드된 파일을 읽을 수 있는 충분한 권한이 있어야 합니다. 이 작업은 다음과 같이 수행할 수 있습니다. get_instance 도구를 사용하여 인스턴스 서비스 계정의 이메일 주소를 가져옵니다. 도구의 출력에서 serviceAccountEmailAddress 필드의 값을 가져옵니다. 제공된 Cloud Storage 버킷에 인스턴스 서비스 계정에 storage.objectAdmin 역할을 부여합니다. gcloud storage buckets add-iam-policy-binding과 같은 명령어 또는 Cloud Storage API에 대한 요청을 사용합니다. 역할이 부여되고 권한이 Cloud Storage의 서비스 계정에 전파되는 데 2~7분 이상 걸릴 수 있습니다. IAM 정책을 업데이트한 후 권한 오류가 발생하면 몇 분 정도 기다린 후 다시 시도하세요. 권한이 부여되면 데이터를 가져올 수 있습니다. 선택적 매개변수는 비워 두고 시스템 기본값을 사용하는 것이 좋습니다. 파일 유형은 일반적으로 파일 확장자로 확인할 수 있습니다. 예를 들어 파일이 SQL 파일인 경우 CSV 파일의 .sql 또는 .csv입니다. 다음은 MySQL용 샘플 SQL importContext입니다. { "uri": "gs://sample-gcs-bucket/sample-file.sql", "kind": "sql#importContext", "fileType": "SQL" } 데이터베이스 이름이 SQL 파일에 있어야 하므로 MySQL에는 database 파라미터가 없습니다. URI는 하나만 지정합니다. importContext 외에 다른 필드는 필요하지 않습니다. PostgreSQL의 경우 database 필드가 필요합니다. 다음은 database 필드가 지정된 샘플 PostgreSQL importContext입니다. { "uri": "gs://sample-gcs-bucket/sample-file.sql", "kind": "sql#importContext", "fileType": "SQL", "database": "sample-db" } import_data 도구는 장기 실행 작업을 반환합니다. 작업이 완료될 때까지 get_operation 도구를 사용하여 상태를 폴링합니다.

MCP 도구 사양 가져오기

MCP 서버의 모든 도구에 대한 MCP 도구 사양을 가져오려면 tools/list 메서드를 사용하세요. 다음 예시에서는 curl을 사용하여 MCP 서버 내에서 현재 사용할 수 있는 모든 도구와 사양을 나열하는 방법을 보여줍니다.

curl 요청
curl --location 'https://sqladmin.googleapis.com/mcp' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/list", "jsonrpc": "2.0", "id": 1 }'