Servidor MCP — Cloady Docs

Cloady incluye un servidor MCP que permite a un agente de IA trabajar en tu cuenta: espacios de trabajo, apps, despliegues, variables de entorno, dominios, volúmenes, miembros, integraciones, facturación y tickets de soporte.

Qué es

El Model Context Protocol (MCP) permite que un cliente de IA descubra y llame a las herramientas de un servidor. Las operaciones de la referencia REST se convierten en herramientas de Cloady, y cada llamada va al endpoint correspondiente con tu token de API, con las mismas comprobaciones de permisos que tus propias solicitudes.

Ejecútalo en local por stdio como @cloady/mcp, o conéctate al endpoint alojado, https://cloady.com/api/mcp, que ofrece las mismas herramientas por Streamable HTTP sin instalar nada. El endpoint alojado excluye las herramientas que devuelven credenciales (revealVar, getDbCredentials, getVolumeKeys, createSshSession, getSshSession, createToken, startCardSetup, las herramientas de invitaciones, cuyos enlaces dan acceso a quien los abra, y las de importación desde otros proveedores), además de generateImage. También excluye la mayoría de las herramientas de Monitor: en el endpoint alojado, los agentes leen métricas y logs con queryAppMetrics, queryAppMetricsRange, queryAppLogs y queryWorkspaceMetrics. Todo lo excluido sigue disponible en el paquete local y en la API.

La conexión del directorio público de OpenAI usa https://cloady.com/api/mcp?profile=openai. Ofrece diagnóstico de aplicaciones, inspección del esquema de bases de datos, operaciones con repositorios y gestión de dominios. No ofrece la obtención de credenciales, los códigos de verificación, la configuración de pagos, los cambios de suscripción ni la creación o el cambio de tamaño de aplicaciones. Estas operaciones siguen disponibles en el panel de Cloady, la API REST y el paquete local @cloady/mcp. Cada acción de Git es una herramienta independiente.

Los clientes compatibles con OAuth pueden conectarse sin copiar una clave de API. Elige un alcance al dar tu consentimiento y revoca el token resultante en Account → API tokens cuando ya no lo necesites. Una conexión a nivel de cuenta puede acceder a todos los espacios de trabajo a los que pertenece tu cuenta, según lo que permitan su alcance y tu rol. Consulta la Política de privacidad para saber cómo se comparten, conservan y eliminan los datos.

Conectar

Crea un token en Account → API tokens y copia el secreto cldy_…: solo se muestra una vez. Necesitas Node 20 o posterior.

Claude Code

Terminal

claude mcp add cloady -e BEARER_TOKEN_CLOADY=cldy_… -- npx -y @cloady/mcp

Alojado, sin instalación

Terminal

claude mcp add --transport http cloady https://cloady.com/api/mcp --header "Authorization: Bearer cldy_…"

Cualquier cliente compatible con Streamable HTTP acepta la misma URL y la cabecera Authorization: Bearer. Cada solicitud actúa como el propietario del token, igual que con el paquete.

Claude Desktop / Cursor / cualquier cliente MCP

JSON

{
  "mcpServers": {
    "cloady": {
      "command": "npx",
      "args": ["-y", "@cloady/mcp"],
      "env": { "BEARER_TOKEN_CLOADY": "cldy_xxxxxxxxxxxxxxxx" }
    }
  }
}

API_BASE_URL cambia el host de destino si apuntas a algo distinto de https://cloady.com.

Herramientas

Hay una herramienta por cada operación de la API, con el mismo nombre que su id de operación: listVars, createVar, deployApp, execCommand, listDeploys. Los parámetros de ruta y de consulta son argumentos de primer nivel; lo que iría en un cuerpo JSON va en un objeto anidado requestBody. Así, createVar recibe workspaceSlug, appSlug, env y region, más requestBody: { key, value, isSecret }.

Cada app se ejecuta en una región y un entorno, y su nombre es único dentro de un espacio de trabajo y un entorno. env es production (el valor predeterminado), preview o development; region solo hace falta cuando existe una app con ese nombre en más de una región.

La lista completa, con todos los argumentos, está en la referencia de la API: todo lo que aparece allí es una herramienta. Algunas que conviene conocer:

Herramienta	Qué hace
`listWorkspaces`, `getWorkspace`	Espacios de trabajo con sus apps en `services`: estado, región, endpoints y límites.
`deployApp`	Crea una app desde el catálogo, un repo de git o una subida: `source` es `{type:"catalog", name}`, `{type:"git", repoUrl}` o `{type:"upload", uploadId}`, `region` indica dónde se ejecuta y `values` define los ajustes de instalación.
`updateApp`	Renombra, cambia de rama y escala; con `status: "stopped"` / `"running"` la detiene o la inicia.
`deleteApp`	Elimina la app y sus datos.
`listVars`, `createVar`, `updateVar`, `deleteVar`, `importVars`, `revealVar`	Variables de entorno y credenciales.
`listDeploys`, `createAppDeploy`, `redeployApp`, `rollbackDeploy`	Historial de despliegues, despliegues nuevos y reversión a uno anterior.
`execCommand`	Ejecuta un comando de shell en un contenedor en ejecución.
`readServiceLogs`	Las últimas 200 líneas de un servicio; `serviceName` es un servicio dentro de la app.
`listAppDomains`, `createDomain`, `listCertStatuses`	Dominios propios, y si HTTPS ya está listo en ellos.

deleteApp es destructiva. Elimina la app y sus datos de forma permanente, y no se puede deshacer.

Renombrar con updateApp es la forma segura de cambiar el nombre de una app: la app conserva sus datos y su dirección sigue al nuevo nombre. Una app llamada My Blog en el espacio de trabajo acme responde en my-blog-k7q2v9ze-acme.cloady.io, y al renombrarla pasa a la dirección del nuevo nombre. Nunca elimines una app para volver a crearla con otro nombre: eliminarla destruye sus datos.

Las cinco herramientas stream… (streamAppStatus, streamAppMetrics, streamActiveDeploy, streamDeployLogs, streamTicketMessages) devuelven el estado actual en una sola respuesta por llamada, en lugar de un flujo en directo, así que vuelve a llamarlas para seguir cómo avanza algo.

Alcances

Un token tiene un solo alcance, y este limita el rol con el que el token puede actuar en un espacio de trabajo: read actúa como viewer, deploy como developer y full puede llegar a owner. Cada operación sigue exigiendo el mismo rol que en el panel, así que un token con alcance full no puede eliminar nada en un espacio de trabajo donde solo eres viewer.

Un token también puede estar anclado a un solo espacio de trabajo; si se usa con otro, se rechaza con un error forbidden.

Errores

Los fallos llegan con el cuerpo de error del propio endpoint:

JSON

{ "error": { "code": "forbidden", "message": "API token scope 'read' cannot perform 'developer'-level actions" } }

Código	Qué significa
`unauthorized`	Falta el token o no es válido.
`phone_required`	El teléfono del propietario del token no está verificado. Verifícalo una vez en cloady.com y todas las herramientas funcionarán.
`forbidden`	Por el alcance, por el rol en el espacio de trabajo o porque el token está anclado a otro espacio de trabajo.
`not_found`	No existe ese espacio de trabajo, esa app o ese registro.
`region_required`	Hay una app con ese nombre en más de una región: pasa `region`.
`payment_required`	La app haría que el espacio de trabajo superara su asignación gratuita y no hay ninguna tarjeta registrada, o la tarjeta fue rechazada. El propietario del espacio de trabajo tiene que añadir una tarjeta en cloady.com, en Account → Billing.

Ejemplo de interacción

You: Install WordPress in the acme workspace, region usw1, then show me its settings.

Agent → listTemplates
  ← the catalog, including { "slug": "wordpress", … }

Agent → deployApp { workspaceSlug: "acme",
                    requestBody: { name: "My Blog", region: "usw1",
                                   source: { type: "catalog", name: "wordpress" } } }
  ← the created app: slug "my-blog", status "deploying"

Agent → listVars { workspaceSlug: "acme", appSlug: "my-blog" }
  ← its variables and generated credentials

Agent: Installed My Blog in usw1; it's deploying now. Here are its settings — …

En esta página