MCP Reference: cloudcli.googleapis.com

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

Un servidor del 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 las 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 pueda comprender.

Configuración del servidor

Antes de usar los servidores de MCP, debes habilitarlos y configurar la autenticación. Para obtener más información sobre el uso de los servidores de MCP remotos de Google y Google Cloud, consulta la 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 MCP de la API de Cloud CLI Execution 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 a 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, 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 Cloud CLI Execution, la facturación, la cuota, etcétera). Este NO es el 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 el signo "=" para separar las claves de las marcas de sus valores en 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 que hay algún proyecto o configuración de facturación preconfigurados en el entorno de ejecución. Para los comandos que no se limitan a un proyecto (p.ej., a nivel de la carpeta o la organización) o situaciones específicas, como Cloud Storage Requester Pays, DEBES pasar la marca --billing-project=PROJECT. En el caso de los comandos con alcance para el proyecto, TAMBIÉN PUEDES especificar --billing-project=PROJECT para anular el proyecto de cuota, lo que tendrá efecto en las APIs de GCP que no admitan la anulación del proyecto de recursos.
  4. Alcance del proyecto: SIEMPRE DEBES pasar la marca --project=PROJECT_ID para los comandos con permiso del proyecto. No lo uses para comandos a nivel de la organización o la carpeta. Si no proporcionas una marca --project para un comando con alcance en el proyecto, el proyecto del recurso 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 que se agote el tiempo de espera del agente.
  8. Limitación de la velocidad de registro: Cuando uses gcloud logging read, SIEMPRE debes incluir una marca --limit (p.ej., --limit=100) para evitar que se agote el tiempo de espera de las credenciales y las conexiones.
  9. Autocorrección: Si un comando devuelve un error, analiza stderr, corrige la sintaxis o las marcas y vuelve a intentarlo en la siguiente iteración.
  10. input_files: (Opcional) Es una lista de archivos que se crearán en el entorno antes de ejecutar el comando. Cada archivo debe tener una "ruta de acceso" (relativa al directorio actual) y un "contenido". El campo "contents" debe ser texto sin formato 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. Lee los 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

De forma predeterminada, las cadenas de respuesta se formatean para la salida de la terminal (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 load, bq pyshell, 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 de nivel inferior (refleja la marca --billing-project de gcloud). Si se especifica --project_id en el comando, se usará como el proyecto de facturación o de cuota. Si no se especifica --project_id O, además, se especifica --quota_project_id, el proyecto de facturación o de cuota será el proyecto establecido en la marca --quota_project_id.
  3. Formato de marcas: SIEMPRE debes usar el signo "=" para separar las claves de las marcas de sus valores en 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 y evitar que se agote el tiempo de espera del agente.
  6. Restricciones de comandos: NO DEBES usar los siguientes comandos de bq: bq init, bq pyshell, bq shell. NO se admite la canalización ni el encadenamiento de comandos.
  7. Autocorrección: Si un comando devuelve 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 que realizan mutaciones, 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 * FROM project.dataset.table LIMIT 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="Nueva descripción" --project_id=PROJECT_ID myDataset.myTable
  7. Enumera los conjuntos de datos en un proyecto: bq ls --datasets=true --project_id=PROJECT_ID

Obtén las especificaciones de la herramienta de MCP

Para obtener las especificaciones de las herramientas de MCP para todas las herramientas en 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
}'