MCP Tools Reference: cloud-sql

Tool: execute_sql

Execute any valid SQL statement, including data definition language (DDL), data control language (DCL), data query language (DQL), or data manipulation language (DML) statements, on a Cloud SQL for MySQL, Cloud SQL for PostgreSQL, or Cloud SQL for SQL Server instance.

To support the execute_sql tool, a Cloud SQL instance and request must meet the following requirements:

• The value of data_api_access must be set to ALLOW_DATA_API.
• For PostgreSQL and SQL Server instances, the database field is required. For MySQL instances, the database field is optional.

• For built-in database users (supported for MySQL, PostgreSQL, and SQL Server, and required for SQL Server because Cloud SQL for SQL Server doesn't support IAM database authentication):

  • Specify the user field and the password_secret_version field.
  • The value of password_secret_version must be the resource name of a regional secret version in Secret Manager stored in the same region as the Cloud SQL instance, such as projects/12345/locations/us-central1/secrets/my-password-secret/versions/1 or projects/12345/locations/us-central1/secrets/my-password-secret/versions/latest.
  • The caller must have the secretmanager.secretVersions.access permission on the secret version.

• For IAM database authentication (supported for MySQL and PostgreSQL only; not supported for SQL Server):

  • For a MySQL instance, the database flag cloudsql_iam_authentication must be set to on.
  • For a PostgreSQL instance, the database flag cloudsql.iam_authentication must be set to on.
  • An IAM user account or IAM service account (CLOUD_IAM_USER or CLOUD_IAM_SERVICE_ACCOUNT) must exist on the instance. After you use the create_instance tool to create a MySQL or PostgreSQL instance, you can use the create_user tool to create an IAM user account for the user currently logged in to the project.

The execute_sql tool has the following limitations:

• If a SQL statement returns a response larger than 10 MB, then the response will be truncated.
• The execute_sql tool has a default timeout of 30 seconds. If a query runs longer than 30 seconds, then the tool returns a DEADLINE_EXCEEDED error.

If you receive errors similar to "IAM authentication is not enabled for the instance" on a MySQL or PostgreSQL instance, then you can use the get_instance tool to check the value of the IAM database authentication flag for the instance.

If you receive errors like "The instance doesn't allow using executeSql to access this instance", then you can use the get_instance tool to check the data_api_access setting.

When you receive authentication errors for a built-in database user (including all SQL Server requests):

1. Check if the specified database user exists on the instance using the list_users tool.
2. Verify that password_secret_version references a valid regional Secret Manager secret version in the same region as the Cloud SQL instance and that the caller has the secretmanager.secretVersions.access permission on the secret version.
3. Check if the caller has the cloudsql.instances.executeSql IAM permission on the project (included in roles such as Cloud SQL Instance User (roles/cloudsql.instanceUser) or Cloud SQL Admin (roles/cloudsql.admin)).

When you receive authentication errors for IAM database authentication (MySQL and PostgreSQL only):

1. Check if the currently logged-in user account exists as an IAM user on the instance using the list_users tool.
2. If the IAM user account doesn't exist, then use the create_user tool to create the IAM user account for the logged-in user.
3. If the currently logged-in user doesn't have the proper database user roles, then you can use the update_user tool to grant database roles to the user. For example, the cloudsqlsuperuser role can provide an IAM user with many required permissions.

4. Check if the currently logged-in user has the correct IAM permissions assigned for the project. You can use the gcloud projects get-iam-policy [PROJECT_ID] command to check if the user has the proper IAM roles or permissions assigned for the project.

   • The user must have cloudsql.instances.login permission to do automatic IAM database authentication.
   • The user must have cloudsql.instances.executeSql permission to execute SQL statements using the execute_sql tool or executeSql API.
   • Common IAM roles that contain the required permissions: Cloud SQL Instance User (roles/cloudsql.instanceUser) or Cloud SQL Admin (roles/cloudsql.admin).

When receiving an ExecuteSqlResponse, always check the message and status fields within the response body. A successful HTTP status code doesn't guarantee full success of all SQL statements. The message and status fields will indicate if there were any partial errors or warnings during SQL statement execution.

The following code sample shows how to use curl to call the execute_sql MCP tool.

Input Schema

{
  "instance": string,
  "project": string,
  "sqlStatement": string,
  "database": string,
  "user": string,
  "passwordSecretVersion": string,
  "sqlCommenterEnabled": boolean
}

Output Schema

{
  "messages": [
    {
      object (Message)
    }
  ],
  "metadata": {
    object (Metadata)
  },
  "results": [
    {
      object (QueryResult)
    }
  ],
  "status": {
    object (Status)
  }
}

{

  // Union field _message can be only one of the following:
  "message": string
  // End of list of possible types for union field _message.

  // Union field _severity can be only one of the following:
  "severity": string
  // End of list of possible types for union field _severity.
}

{
  "sqlStatementExecutionTime": string
}

{
  "seconds": string,
  "nanos": integer
}

{
  "columns": [
    {
      object (Column)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "message": string,
  "partialResult": boolean,
  "status": {
    object (Status)
  }
}

{
  "name": string,
  "type": string
}

{
  "values": [
    {
      object (Value)
    }
  ]
}

{
  "value": string,
  "nullValue": boolean
}

{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}

{
  "typeUrl": string,
  "value": string
}

Tool Annotations

Tool annotations are sent to MCP clients to describe the basic risk of a given tool. Most clients treat these hints as untrusted, but they can be used to decide when a confirmation prompt might be sent to a user.

Along with the title string, the following boolean hints are defined as follows:

• readOnlyHint: If true, the tool doesn't modify its environment. Default: false.
• destructiveHint: If true, then the tool can perform destructive actions. If false, then the tool can only perform additive actions. Default: true.
• idempotentHint: If true, then calling the tool repeatedly with the same arguments will have no additional effect on its environment. Default: false.
• openWorldHint: If true, then the tool can interact with an 'open world' of external entities. If false, then the tool can only interact with internal entities. For example, a web search tool would be open world, while a memory tool would not be open world.

Destructive Hint: ✅ | Idempotent Hint: ❌ | Read Only Hint: ❌ | Open World Hint: ❌