MCP Reference: cloudcli.googleapis.com

El servidor de MCP de la CLI de Cloud proporciona herramientas para ejecutar comandos de la CLI de Cloud en un entorno de pruebas remoto.

Un servidor de Protocolo de contexto del modelo (MCP) actúa como proxy entre un servicio externo que proporciona contexto, datos o capacidades a un modelo de lenguaje grande (LLM) o una aplicación de IA. Los servidores de MCP conectan aplicaciones de IA a sistemas externos, como bases de datos y servicios web, y traducen sus respuestas a un formato que la aplicación de IA puede comprender.

Configuración del servidor

Debes habilitar los servidores de MCP y configurar la autenticación antes de usarlos. Para obtener más información sobre el uso de servidores de MCP remotos de Google y Google Cloud, consulta Descripción general de los servidores de MCP de Google Cloud.

Extremos del servidor

Un extremo de servicio de MCP es la dirección de red y la interfaz de comunicación (por lo general, una URL) del servidor de MCP que usa una aplicación de IA (el host para el cliente de MCP) para establecer una conexión segura y estandarizada. Es el punto de contacto para que el LLM solicite contexto, llame a una herramienta o acceda a un recurso. Los extremos de MCP de Google pueden ser globales o regionales.

El servidor de MCP de la API de ejecución de la CLI de Cloud tiene el siguiente extremo de MCP global:

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

Herramientas de MCP

Una herramienta de MCP es una función o capacidad ejecutable que un servidor de MCP expone a un LLM o una aplicación de IA para realizar una acción en el mundo real.

Herramientas

El servidor de MCP de cloudcli.googleapis.com tiene las siguientes herramientas:

Herramientas de MCP
run_gcloud_command

Ejecuta un solo comando de gcloud CLI dentro del proyecto de Google Cloud del usuario.

ADVERTENCIA DE SEGURIDAD CRÍTICA (POTENCIALMENTE DESTRUCTIVA): Esta herramienta puede crear, actualizar o borrar recursos de GCP (p.ej., gcloud compute instances delete). NO se limita a los comandos de solo lectura. Ten mucho cuidado.

COMANDOS PROHIBIDOS: Un agente NO DEBE ejecutar los siguientes comandos de gcloud (incluidas sus variantes alfa o beta): app deploy, app instances ssh, auth, billing, components, config, docker, feedback, info, init, meta y survey.

REGLAS DE EJECUCIÓN ESTRICTAS:

  1. DEBES proporcionar el parámetro "project" (es decir, project="projects/PROJECT_ID") cuando uses esta herramienta (se usa para la verificación de habilitación de la API de ejecución de la CLI de Cloud, la facturación, la cuota, etcétera). NO es lo mismo que la marca --project en los comandos de gcloud que se usan para especificar el proyecto en el que opera gcloud.
  2. Formato de marcas: SIEMPRE debes usar un signo "=" para separar las claves de las marcas de sus valores para todas las opciones largas. Correcto: --zone=us-central1-a o --project=my-project. Incorrecto: --zone us-central1-a o --project my-project.
  3. Proyecto de facturación: No puedes suponer ningún proyecto preconfigurado ni configuración de facturación en el entorno de ejecución. Para los comandos que no están dentro del alcance del proyecto (p.ej., nivel de carpeta o de organización) o situaciones específicas como Cloud Storage Requester Pays, DEBES pasar la marca --billing-project=PROJECT. Para los comandos dentro del alcance del proyecto, TAMBIÉN puedes especificar --billing-project=PROJECT para anular el proyecto de cuota, que entrará en vigencia para las APIs de GCP que no admiten la anulación de proyecto de recursos.
  4. Alcance del proyecto: SIEMPRE debes pasar la marca --project=PROJECT_ID para los comandos dentro del alcance del proyecto. No la uses para comandos a nivel de organización o carpeta. Si no proporcionas una --project flag para un comando dentro del alcance del proyecto, el proyecto de recursos se establecerá de forma predeterminada en el proyecto establecido en la marca --billing-project.
  5. Si especificas la marca --billing-project en el comando de gcloud, asegúrate de que el valor sea un ID del proyecto o un número de proyecto. El valor NO DEBE ser un valor especial (es decir, LEGACY, CURRENT_PROJECT, CURRENT_PROJECT_WITH_FALLBACK).
  6. Se DEBE especificar al menos uno de --project o --billing-project en la cadena de comandos.
  7. Operaciones asíncronas: Para las operaciones síncronas de larga duración (p.ej., crear una VM o una base de datos), SIEMPRE debes pasar la marca --async para evitar los tiempos de espera del agente.
  8. Limitación de la tasa de registros: Cuando uses gcloud logging read, SIEMPRE debes incluir una marca --limit (p.ej., --limit=100) para evitar los tiempos de espera de las credenciales y la conexión.
  9. Autocorrección: Si un comando muestra un error, analiza stderr, corrige la sintaxis o las marcas y vuelve a intentarlo en la siguiente iteración.
  10. input_files: Es una lista de archivos que se crearán en el entorno antes de ejecutar el comando (opcional). Cada archivo debe tener una "ruta de acceso" (relativa al directorio actual) y "contenido". El "contenido" debe ser texto simple que represente el contenido del archivo. Esto es útil para los comandos que leen archivos (p.ej., gcloud builds submit --config=cloudbuild.yaml --async --project=PROJECT_ID).

Ejemplos de comandos o patrones de gcloud:

  1. Leer registros de instancias de GCE con gravedad>=ERROR: gcloud logging read "severity>=ERROR AND resource.type='gce_instance'" --limit=10 --order=DESC --project=PROJECT_ID
    • Observa el uso de comillas para la expresión de filtro.
  2. Enumera todos los extremos de PSC: gcloud compute forwarding-rules list --project=PROJECT_ID
  3. Describe un extremo de PSC: gcloud compute forwarding-rules describe FORWARDING_RULE_NAME --region=REGION --project=PROJECT_ID
    • Observa el uso de "=" para la marca --region.
  4. Enumera todos los clústeres: gcloud container clusters list --project=PROJECT_ID
  5. Describe un clúster: gcloud container clusters describe CLUSTER_NAME --region=REGION --project=PROJECT_ID
  6. Enumera las instancias de procesamiento: gcloud compute instances list --project=PROJECT_ID
  7. Obtén la política de IAM para un proyecto: gcloud projects get-iam-policy PROJECT_ID --project=PROJECT_ID

Las cadenas de respuesta se formatean para la salida de la terminal de forma predeterminada (stdout o stderr). Usa la marca --format para cambiar el formato.
run_bq_command

Ejecuta un solo comando de la CLI de BigQuery (bq). Esta herramienta te permite ejecutar cualquier comando de bq en el proyecto del usuario, incluidos los comandos que crean, actualizan o borran recursos de GCP (es decir, mutaciones).

ADVERTENCIA DE SEGURIDAD CRÍTICA (POTENCIALMENTE DESTRUCTIVA): Esta herramienta puede crear, actualizar o borrar recursos de BigQuery (p.ej., bq rm, bq cancel, bq query). NO se limita a los comandos de solo lectura. Ten mucho cuidado.

COMANDOS PROHIBIDOS: Un agente NO DEBE ejecutar los siguientes comandos de bq: bq init, bq pyshell y bq shell.

REGLAS DE EJECUCIÓN ESTRICTAS:

  1. Se DEBE especificar al menos uno de --project_id o --quota_project_id en la cadena de comandos.
  2. ID del proyecto en comparación con el proyecto de cuota: La marca --project_id especifica el proyecto de recursos en el que opera el comando (refleja la marca --project de gcloud). La marca --quota_project_id especifica el proyecto al que se le cobra la facturación o la cuota de la llamada a la API de BigQuery descendente (refleja la marca --billing-project de gcloud). Si se especifica --project_id en el comando, se usará como el proyecto de facturación o cuota. Si no se especifica --project_id O se especifica --quota_project_id adicionalmente, el proyecto de facturación o cuota será el proyecto establecido en la marca --quota_project_id.
  3. Formato de marcas: SIEMPRE debes usar un signo "=" para separar las claves de las marcas de sus valores para todas las opciones largas. Correcto: '--project_id=my-project' o '--location=us'. Incorrecto: '--project_id my-project' o '--location us'. No uses espacios entre las marcas y sus valores.
  4. Sin valores predeterminados de configuración: El comando bq se ejecuta sin estado; no carga archivos de configuración locales como .bigqueryrc. Por lo tanto, para todas las operaciones regionales (p.ej., crear un conjunto de datos o consultar un conjunto de datos regional), DEBES especificar de forma explícita la marca --location (p.ej., --location=us o --location=EU).
  5. Operaciones asíncronas: Algunos comandos inician operaciones síncronas de larga duración (p.ej., ejecutar trabajos de consulta). SIEMPRE debes pasar la marca --nosync para estos comandos para evitar los tiempos de espera del agente.
  6. Restricciones de comandos: NO DEBES usar los siguientes comandos de bq: bq init, bq pyshell y bq shell. NO se admite el encadenamiento ni la canalización de comandos.
  7. Autocorrección: Si un comando muestra un error, analiza stderr, corrige la sintaxis o las marcas y vuelve a intentarlo en la siguiente iteración.

Entre los ejemplos de comandos de bq mutantes, se incluyen los siguientes: bq mk, bq rm, bq update, bq insert, bq query (sin --dry_run), etcétera. Uso: RunBq(command="bq query --project_id=PROJECT_ID 'SELECT 1'", project="projects/PROJECT_ID", input_files=[{"path": "PATH", "contents": "CONTENTS"}]) DEBES proporcionar el comando de bq completo como una sola cadena en el parámetro "command". DEBES proporcionar el parámetro "project" (formato: projects/PROJECT_ID) como el proyecto de ejecución de la API para la facturación, la habilitación de la API y las verificaciones de consumo de cuota.

Ejemplos de comandos o patrones de bq:

  1. Ejecuta una consulta: bq query --use_legacy_sql=false --project_id=PROJECT_ID 'SELECT * FROMproject.dataset.tableLIMIT 10'
  2. Crea un conjunto de datos: bq mk --dataset --location=us --project_id=PROJECT_ID myDataset
  3. Crea una tabla: bq mk --table --project_id=PROJECT_ID myDataset.myTable name:string,value:integer
  4. Quita un conjunto de datos: bq rm -f --dataset --project_id=PROJECT_ID myDataset
  5. Quita una tabla: bq rm -f -t --project_id=PROJECT_ID myDataset.myTable
  6. Actualiza la descripción de la tabla: bq update --description="New description" --project_id=PROJECT_ID myDataset.myTable
  7. Enumera los conjuntos de datos de un proyecto: bq ls --datasets=true --project_id=PROJECT_ID

Obtén especificaciones de herramientas de MCP

Para obtener las especificaciones de las herramientas de MCP para todas las herramientas de un servidor de MCP, usa el método tools/list. En el siguiente ejemplo, se muestra cómo usar curl para enumerar todas las herramientas y sus especificaciones disponibles actualmente en el servidor de MCP.

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