MCP Tools Reference: cloud-sql

Herramienta: execute_sql_readonly

Ejecutar cualquier instrucción de SQL de solo lectura válida en una instancia de Cloud SQL

Para admitir la herramienta execute_sql_readonly, una instancia de Cloud SQL debe cumplir con los siguientes requisitos:

  • El valor de data_api_access debe establecerse en ALLOW_DATA_API.
  • En el caso de una instancia de MySQL, la marca de base de datos cloudsql_iam_authentication debe establecerse en on. En el caso de una instancia de PostgreSQL, la marca de base de datos cloudsql.iam_authentication debe establecerse en on.
  • Se requiere una cuenta de usuario o una cuenta de servicio de IAM (CLOUD_IAM_USER o CLOUD_IAM_SERVICE_ACCOUNT) para llamar a la herramienta execute_sql_readonly. La herramienta ejecuta las sentencias SQL con los privilegios del usuario de la base de datos que accedió con la autenticación de la base de datos de IAM.

Después de usar la herramienta create_instance para crear una instancia, puedes usar la herramienta create_user para crear una cuenta de usuario de IAM para el usuario que actualmente accedió al proyecto.

La herramienta execute_sql_readonly tiene las siguientes limitaciones:

  • Si una instrucción de SQL devuelve una respuesta de más de 10 MB, la respuesta se truncará.
  • La herramienta tiene un tiempo de espera predeterminado de 30 segundos. Si una consulta se ejecuta durante más de 30 segundos, la herramienta devuelve un error de DEADLINE_EXCEEDED.
  • La herramienta no es compatible con SQL Server.

Si recibes errores similares a "La autenticación de IAM no está habilitada para la instancia", puedes usar la herramienta get_instance para verificar el valor de la marca de autenticación de la base de datos de IAM para la instancia.

Si recibes errores como "La instancia no permite usar executeSql para acceder a esta instancia", puedes usar la herramienta get_instance para verificar el parámetro de configuración data_api_access.

Cuando recibas errores de autenticación, haz lo siguiente:

  1. Verifica si la cuenta de usuario con la que se accedió actualmente existe como usuario de IAM en la instancia con la herramienta list_users.
  2. Si la cuenta de usuario de IAM no existe, usa la herramienta create_user para crearla para el usuario que accedió.
  3. Si el usuario conectado actualmente no tiene los roles de usuario de la base de datos adecuados, puedes usar la herramienta update_user para otorgarle roles de base de datos. Por ejemplo, el rol cloudsqlsuperuser puede proporcionar a un usuario de IAM muchos permisos requeridos.

  4. Verifica si el usuario que accedió actualmente tiene los permisos de IAM correctos asignados para el proyecto. Puedes usar el comando gcloud projects get-iam-policy [PROJECT_ID] para verificar si el usuario tiene los roles o permisos de IAM adecuados asignados para el proyecto.

    • El usuario debe tener permiso de cloudsql.instance.login para realizar la autenticación automática de la base de datos de IAM.
    • El usuario debe tener permiso cloudsql.instances.executeSql para ejecutar instrucciones SQL con la herramienta execute_sql_readonly o la API de executeSql.
    • Roles de IAM comunes que contienen los permisos requeridos: Usuario de instancia de Cloud SQL (roles/cloudsql.instanceUser) o Administrador de Cloud SQL (roles/cloudsql.admin)

Cuando recibas un ExecuteSqlResponse, siempre verifica los campos message y status dentro del cuerpo de la respuesta. Un código de estado HTTP correcto no garantiza el éxito total de todas las sentencias SQL. Los campos message y status indicarán si hubo errores o advertencias parciales durante la ejecución de la instrucción de SQL.

En el siguiente ejemplo, se muestra cómo usar curl para invocar la herramienta de MCP execute_sql_readonly.

Solicitud de Curl 
                  
curl --location 'https://sqladmin.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "execute_sql_readonly",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Esquema de entrada

Es una solicitud de ejecución de SQL de instancia para MCP.

SqlInstancesExecuteSqlMcpRequest

Representación JSON 
{
  "instance": string,
  "project": string,
  "sqlStatement": string,
  "database": string,
  "user": string,
  "passwordSecretVersion": string
}
Campos
instance

string

Obligatorio. El ID de instancia de la base de datos. Esto no incluye el ID del proyecto.
project

string

Obligatorio. El ID del proyecto que contiene la instancia.
sqlStatement

string

Obligatorio. Son las instrucciones de SQL que se ejecutarán en la base de datos. Puede ser una sola instrucción o una secuencia de instrucciones separadas por punto y coma.
database

string

Es opcional. Nombre de la base de datos en la que se ejecutará la instrucción. Es obligatorio para Postgres y opcional para MySQL. En el caso de Postgres, si tu consulta no se limita a una base de datos existente, como enumerar bases de datos, crear una base de datos nueva o otorgar roles, puedes pasar el valor predeterminado como postgres.
user

string

Es opcional. Nombre de un usuario de base de datos existente para conectarse a la base de datos. Cuando auto_iam_authn se establece como verdadero, se ignora este campo y se usa el usuario de IAM del llamador de la API.
passwordSecretVersion

string

Es opcional. Es el nombre del recurso del secreto de Secret Manager que contiene la contraseña para que el usuario acceda a la base de datos. El formato esperado es projects/{project}/secrets/{secret}/versions/{secret_version}. No se almacenará el nombre del recurso del secreto.

Esquema de salida

Es la respuesta de la ejecución de instrucciones de SQL.

SqlInstancesExecuteSqlResponse

Representación JSON 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "metadata": {
    object (Metadata)
  },
  "results": [
    {
      object (QueryResult)
    }
  ],
  "status": {
    object (Status)
  }
}
Campos
messages[]

object (Message)

Es una lista de avisos y advertencias generados durante la ejecución de la consulta. En el caso de PostgreSQL, esto incluye todos los avisos y advertencias. En el caso de MySQL, esto incluye las advertencias generadas por la última instrucción ejecutada. Para recuperar todas las advertencias de una consulta de varias instrucciones, se debe ejecutar SHOW WARNINGS después de cada instrucción.
metadata

object (Metadata)

Es la información de metadatos adicional sobre la ejecución de las sentencias SQL.
results[]

object (QueryResult)

Es la lista de resultados después de ejecutar todas las instrucciones SQL.
status

object (Status)

Contiene el error de la base de datos si falló la ejecución de SQL.

Mensaje

Representación JSON 
{

  // 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.
}
Campos

Campo de unión _message.

_message puede ser una de las siguientes opciones:
message

string

Es la cadena de mensaje completa. En el caso de PostgreSQL, se trata de una cadena con formato que puede incluir la gravedad, el código y el mensaje de aviso o advertencia. En el caso de MySQL, contiene el mensaje de advertencia.

Campo de unión _severity.

_severity puede ser una de las siguientes opciones:
severity

string

Es la gravedad del mensaje (p.ej., "NOTICE" para PostgreSQL y "WARNING" para MySQL).

Metadatos

Representación JSON 
{
  "sqlStatementExecutionTime": string
}
Campos
sqlStatementExecutionTime

string (Duration format)

Es el tiempo que se tarda en ejecutar las instrucciones de SQL.

Una duración en segundos con hasta nueve dígitos decimales, que terminan en “s”. Ejemplo: "3.5s".

Duración

Representación JSON 
{
  "seconds": string,
  "nanos": integer
}
Campos
seconds

string (int64 format)

Son los segundos firmados del período. Debe estar entre -315,576,000,000 y +315,576,000,000, inclusive. Nota: Estos límites se calculan de la siguiente manera: 60 s/min * 60 min/h * 24 h/día * 365.25 días/año * 10,000 años.
nanos

integer

Fracciones firmadas de un segundo con una resolución de nanosegundos del período. Las duraciones inferiores a un segundo se representan con un campo seconds igual a 0 y un campo nanos positivo o negativo. Para duraciones de un segundo o más, un valor distinto de cero para el campo nanos debe tener el mismo signo que el campo seconds. Debe ser un valor entre -999,999,999 y +999,999,999, inclusive.

QueryResult

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

object (Column)

Es la lista de columnas incluidas en el resultado. Esto también incluye el tipo de datos de la columna.
rows[]

object (Row)

Son las filas que devuelve la instrucción de SQL.
message

string

Es un mensaje relacionado con el resultado de la ejecución de SQL.
partialResult

boolean

Se establece en verdadero si el resultado de la ejecución de SQL se trunca debido a límites de tamaño o a un error al recuperar los resultados.
status

object (Status)

Son los detalles del error si los resultados se truncaron debido a un error.

Columna

Representación JSON 
{
  "name": string,
  "type": string
}
Campos
name

string

Nombre de la columna.
type

string

Es el tipo de datos de la columna.

Fila

Representación JSON 
{
  "values": [
    {
      object (Value)
    }
  ]
}
Campos
values[]

object (Value)

Son los valores de la fila.

Valor

Representación JSON 
{
  "value": string,
  "nullValue": boolean
}
Campos
value

string

Es el valor de la celda en formato de cadena.
nullValue

boolean

Si el valor de la celda es nulo, esta marca se establecerá en verdadero.

Estado

Representación JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Campos
code

integer

El código de estado, que debe ser un valor enum de google.rpc.Code.
message

string

Un mensaje de error dirigido al desarrollador, que debe estar en inglés. Cualquier mensaje de error dirigido al usuario debe localizarse y enviarse al campo google.rpc.Status.details; o el cliente debe localizarlo.
details[]

object

Una lista de mensajes que contienen los detalles del error. Hay un conjunto común de tipos de mensajes para que usen las API.

Un objeto que contiene campos de un tipo arbitrario. Un campo adicional "@type" contiene una URI que identifica el tipo. Ejemplo: { "id": 1234, "@type": "types.example.com/standard/id" }.

Cualquiera

Representación JSON 
{
  "typeUrl": string,
  "value": string
}
Campos
typeUrl

string

Identifica el tipo del mensaje serializado de Protobuf con una referencia de URI que consta de un prefijo que termina en una barra y el nombre de tipo completo.

Ejemplo: type.googleapis.com/google.protobuf.StringValue

Esta cadena debe contener al menos un carácter /, y el contenido después del último / debe ser el nombre completamente calificado del tipo en formato canónico, sin un punto inicial. No escribas un esquema en estas referencias de URI para que los clientes no intenten comunicarse con ellas.

El prefijo es arbitrario, y se espera que las implementaciones de Protobuf simplemente quiten todo hasta el último / inclusive para identificar el tipo. type.googleapis.com/ es un prefijo predeterminado común que requieren algunas implementaciones heredadas. Este prefijo no indica el origen del tipo, y no se espera que los URIs que lo contienen respondan a ninguna solicitud.

Todas las cadenas de URL de tipo deben ser referencias URI legales con la restricción adicional (para el formato de texto) de que el contenido de la referencia solo debe constar de caracteres alfanuméricos, escapes codificados como porcentaje y caracteres del siguiente conjunto (sin incluir las comillas invertidas externas): /-.~_!$&()*+,;=. A pesar de que permitimos la codificación de porcentaje, las implementaciones no deben decodificarlas para evitar confusiones con los analizadores existentes. Por ejemplo, se debe rechazar type.googleapis.com%2FFoo.

En el diseño original de Any, se consideró la posibilidad de lanzar un servicio de resolución de tipos en estas URLs de tipos, pero Protobuf nunca implementó uno y considera que contactar estas URLs es problemático y un posible problema de seguridad. No intentes comunicarte con URLs de tipo.
value

string (bytes format)

Contiene una serialización de Protobuf del tipo que describe type_url.

Es una cadena codificada en Base64.

Anotaciones de herramientas

Sugerencia destructiva: ❌ | Sugerencia idempotente: ✅ | Sugerencia de solo lectura: ✅ | Sugerencia de mundo abierto: ❌