Acceso para IA: referencia del servidor MCP y de la API del sitio

Para quién es esta guía: para cualquier IA —Claude Code, Cursor, Codex de OpenAI o un agente propio— que trabaja SOLA en la sesión de un cliente y necesita operar su sitio de YaDominios Cloud sin que nadie le explique nada. Todo lo que hace falta está en esta página.

En resumen

Dato	Valor
Servidor MCP	https://yapanel.yadominios.com/api/sitio/mcp (Streamable HTTP, sin sesión)
API HTTP	https://yapanel.yadominios.com/api/sitio/v1/<herramienta>
Autenticación	Authorization: Bearer ydk_…
Alcance	Un solo sitio por llave
Permisos	lectura o escritura
Límite	120 llamadas por minuto por llave
Caducidad	Ninguna; se revoca desde el panel

Inicio rápido

1. El dueño crea la llave

Esto lo hace la persona dueña del sitio, una vez. En el panel: YaDominios Cloud → tarjeta del sitio → «Acceso para IA».

Le pone un nombre que la identifique y elige el permiso. Para que la IA pueda cambiar cosas —variables, archivos, dominios— hace falta Lectura y escritura.

La llave empieza por ydk_ y se muestra una sola vez, junto con la configuración lista para copiar.

2. Se guarda en una variable de entorno

En la computadora donde trabaja la IA, en una variable llamada YADOMINIOS_LLAVE. Nunca dentro del repositorio ni en un archivo que se suba.

export YADOMINIOS_LLAVE="ydk_…"

3. Se conecta la herramienta y se comprueba

Elige tu herramienta en la sección siguiente. Para comprobar, llama a estado_del_sitio: tiene que devolver el nombre del sitio y el permiso de la llave.

Conectar tu herramienta

Claude Code

En el archivo .mcp.json de la raíz del proyecto:

{
  "mcpServers": {
    "yadominios": {
      "type": "http",
      "url": "https://yapanel.yadominios.com/api/sitio/mcp",
      "headers": { "Authorization": "Bearer ${YADOMINIOS_LLAVE}" }
    }
  }
}

O con un comando:

claude mcp add --transport http yadominios https://yapanel.yadominios.com/api/sitio/mcp --header "Authorization: Bearer $YADOMINIOS_LLAVE"

Cursor

En .cursor/mcp.json del proyecto (o ~/.cursor/mcp.json para todos). Cursor lee las variables con ${env:…}:

{
  "mcpServers": {
    "yadominios": {
      "url": "https://yapanel.yadominios.com/api/sitio/mcp",
      "headers": { "Authorization": "Bearer ${env:YADOMINIOS_LLAVE}" }
    }
  }
}

Codex de OpenAI

En ~/.codex/config.toml. Codex manda la llave en la cabecera Authorization a partir de la variable que le indiques:

[mcp_servers.yadominios]
url = "https://yapanel.yadominios.com/api/sitio/mcp"
bearer_token_env_var = "YADOMINIOS_LLAVE"

ChatGPT en la web

Hoy no: los conectores de ChatGPT en la web piden iniciar sesión con OAuth, y este servidor funciona con llave. Usa Codex, Claude Code o Cursor, o la API HTTP desde cualquier agente que pueda hacer peticiones.

Cualquier agente que haga peticiones HTTP

curl -s https://yapanel.yadominios.com/api/sitio/v1 \
  -H "Authorization: Bearer $YADOMINIOS_LLAVE"

// JavaScript
const r = await fetch("https://yapanel.yadominios.com/api/sitio/v1/estado_del_sitio", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.YADOMINIOS_LLAVE },
});
const { ok, resultado, error, mensaje } = await r.json();

# Python
import os, requests
r = requests.post(
    "https://yapanel.yadominios.com/api/sitio/v1/buscar_dominio",
    headers={"Authorization": f"Bearer {os.environ['YADOMINIOS_LLAVE']}"},
    json={"dominio": "mimarca.com"},
)
print(r.json())

Cómo responde la API

GET /api/sitio/v1 lista las herramientas que puede usar tu llave. Cada herramienta se llama con POST /api/sitio/v1/<nombre>, con sus argumentos como JSON en el cuerpo (o sin cuerpo si no lleva argumentos).

// bien
{ "ok": true, "resultado": { … } }
// mal
{ "ok": false, "error": "solo_lectura", "mensaje": "«guardar_variable» cambia cosas y esta llave es de solo lectura…" }

Por MCP son las mismas herramientas, con los mismos nombres y argumentos. Un fallo de una herramienta llega dentro del resultado, con isError: true y el mismo código, para que la IA lo lea y corrija.

Las herramientas

Herramienta	Permiso	Argumentos	Qué hace
estado_del_sitio	lectura	—	Nombre, dominios, plan, repositorio y rama, versión en vivo frente a la de la rama y minutos de atraso.
leer_registro	lectura	limite (1–200)	Lo último que pasó: publicaciones, errores y avisos.
listar_variables	lectura	—	Variables de entorno. Los secretos salen con valor: null.
guardar_variable	escritura	clave, valor, secreto	Crea o reemplaza una variable. Se aplica al republicar.
borrar_variable	escritura	clave	Borra una variable. Se aplica al republicar.
republicar	escritura	—	Publica otra vez desde la rama conectada.
leer_correos	lectura	limite	Correos enviados con su estado (enviado, rebotado, fallido) y su error.
activar_correos_del_dominio	escritura	dominio	Activa el envío de un dominio conectado al sitio y deja su DNS listo.
listar_archivos	lectura	cursor	Archivos del almacén (env.BUCKET), de 500 en 500.
subir_archivo	escritura	clave, contenido_base64, tipo	Sube o reemplaza un archivo. Hasta 10 MB.
borrar_archivo	escritura	clave	Borra un archivo. Borrar lo que no existe no es error.
consultar_base	escritura	sql, params	SQL en la base del sitio (env.DB), con parámetros ? aparte.
mis_dominios	lectura	—	Dominios de la cuenta: estado, vencimiento y si ya están en este sitio.
buscar_dominio	lectura	dominio	Si está libre y su precio de venta por un año.
comprar_dominio	escritura	dominio, titular	Prepara la compra y devuelve el enlace de pago. La IA no paga.
conectar_dominio	escritura	dominio	Conecta un dominio o un subdominio a este sitio. Un subdominio se escribe en la zona de su dominio sin tocar el principal ni su correo; si el dominio está en otra empresa, devuelve los nameservers.
crear_sitio	escritura	nombre, repositorio, rama	Crea otro sitio en la misma cuenta y plan, con su propia base y almacén.

Recetas

Registrar un dominio y ponerlo en el sitio

La IA nunca paga. Prepara la compra, le da el enlace al dueño, y cuando el pago entra el dominio se registra solo.

POST /api/sitio/v1/buscar_dominio   { "dominio": "mimarca.com" }
→ { "ok": true, "resultado": { "dominio": "mimarca.com", "disponible": true, "precio": 14, "moneda": "USD" } }

POST /api/sitio/v1/comprar_dominio  { "dominio": "mimarca.com" }
→ { "ok": true, "resultado": { "precio": 14, "enlace_de_pago": "https://…", "aviso": "El dominio TODAVÍA NO está registrado…" } }

// el dueño abre el enlace y paga; luego:
POST /api/sitio/v1/mis_dominios
→ [ { "dominio": "mimarca.com", "estado": "activo", "vence": "2027-10-11", "conectado_a_este_sitio": false } ]

POST /api/sitio/v1/conectar_dominio { "dominio": "mimarca.com" }
→ { "ok": true, "resultado": { "listo_sin_hacer_nada": true, "que_falta": "Nada: ya quedó apuntado." } }

Si la cuenta no tiene ficha de titular, manda titular con nombre, apellido, telefono (con prefijo, ej. +13055550100), direccion, ciudad, region, codigoPostal y pais (dos letras, ej. US). Esos datos se publican en el registro del dominio: tienen que ser los del dueño.

Poner una clave de API y aplicarla

POST /api/sitio/v1/guardar_variable { "clave": "PASARELA_LLAVE", "valor": "…", "secreto": true }
POST /api/sitio/v1/republicar
POST /api/sitio/v1/estado_del_sitio   // comprueba versión en vivo y al_dia

Crear un sitio de pruebas

Primero tiene que existir la rama en el repositorio (por ejemplo, la que publica tu Action de pruebas).

POST /api/sitio/v1/crear_sitio { "nombre": "mitienda-pruebas", "repositorio": "https://github.com/tu-usuario/tu-repo", "rama": "yapanel-pruebas" }
→ { "ok": true, "resultado": { "url": "https://mitienda-pruebas.sitios.dev" } }

El sitio nuevo tiene su propia base y su propio almacén. Para operarlo, el dueño crea una llave en ESE sitio: cada llave abre uno solo.

Un sitio de pruebas en un subdominio

Lo normal para un entorno de pruebas: staging.mimarca.com apuntando al sitio de pruebas, con mimarca.com intacto en producción. Se hace con la llave del sitio de pruebas:

POST /api/sitio/v1/conectar_dominio { "dominio": "staging.mimarca.com" }
→ { "ok": true, "resultado": { "listo_sin_hacer_nada": true, "que_falta": "Nada: ya quedó apuntado." } }

Solo se escribe el registro de staging dentro de la zona de mimarca.com: el dominio principal, su sitio y sus registros de correo no se tocan. El HTTPS ya lo cubre el certificado del dominio. Funciona si el dominio principal es de la misma cuenta, registrado aquí o conectado a uno de sus sitios; si no, responde dominio_ajeno.

Activar los correos del dominio

POST /api/sitio/v1/activar_correos_del_dominio { "dominio": "mimarca.com" }

Después se envía con la API de correos del sitio (ver la guía de correos desde tu dominio).

Errores

HTTP	Código	Qué significa	Qué haces
401	sin_llave	No llegó la llave	Mándala en Authorization: Bearer ydk_…
401	llave_invalida	Esa llave no existe	Revisa que esté completa
401	llave_revocada	El dueño la revocó; el mensaje dice cuándo	Pide una nueva. No reintentes
403	solo_lectura	La herramienta cambia cosas	Hace falta una llave de escritura
403	dominio_ajeno	Ese dominio no es de este sitio	Usa un dominio conectado al sitio
404	herramienta_desconocida	El nombre no existe	Lista las herramientas con GET /api/sitio/v1
409	no_disponible	El dominio ya está tomado	Busca otro
409	tope_de_sitios	El plan no admite más sitios	El dueño sube de plan
409	sin_repositorio	El sitio no está conectado a un repositorio	Se conecta en el panel
400	faltan_datos_titular	Falta la ficha del titular	Manda titular en comprar_dominio
400	subdominio_no_soportado	Es un subdominio y su dominio principal no está en YaDominios	Conecta primero el dominio principal a cualquiera de los sitios
429	demasiadas_llamadas	Más de 120 llamadas en un minuto	Espera un minuto

Seguridad

• Una llave abre un solo sitio, nunca la cuenta entera. El sitio sale de la llave: no se puede pedir otro.
• De la llave solo guardamos su huella. Si se pierde, no se recupera: se revoca y se crea otra.
• Nunca en el repositorio ni en un archivo que se suba. Siempre en una variable de entorno.
• Todo lo que la IA cambia queda en el registro del sitio con el nombre de la llave.
• La IA no puede pagar nada: comprar_dominio devuelve un enlace, y paga una persona.
• Si se filtra, el dueño la revoca desde los tres puntos de la llave. Deja de servir en ese mismo instante.

Instrucciones para la IA que lee esto

Opera el sitio con el servidor MCP «yadominios» o con la API https://yapanel.yadominios.com/api/sitio/v1.
1. Empieza siempre con estado_del_sitio: te dice qué sitio es y qué permiso tiene tu llave.
2. La llave está en la variable YADOMINIOS_LLAVE. Nunca la escribas en un archivo, un commit ni un mensaje.
3. Antes de cambiar algo (variables, archivos, base, dominios), dile al dueño qué vas a hacer.
4. Después de guardar o borrar variables, llama a republicar y comprueba con estado_del_sitio.
5. Para un dominio: buscar_dominio → comprar_dominio → pásale el enlace_de_pago al dueño → espera a que aparezca activo en mis_dominios → conectar_dominio.
6. Si recibes llave_revocada, detente y pide una llave nueva. Si recibes demasiadas_llamadas, espera un minuto.