Qué vamos a construir

Al final de esta guía, Claude Code creará una página, la llenará de contenido, la publicará y la editará de nuevo, y una app Next.js que corre en tu máquina renderizará cada cambio. Nadie abre un panel de administración.

Intervienen tres piezas, y conviene mantenerlas separadas:

Tu app Next.js renderiza el sitio. Aquí es simple-blog, del repositorio de ejemplos de cmssy. cmssy nunca la renderiza ni la aloja.
Tu workspace de cmssy guarda el contenido y lo sirve a la app mediante la API de entrega.
@cmssy/mcp-server conecta Claude Code con ese workspace. Claude lee y escribe contenido a través de él. No toca tu código: el servidor no escribe archivos ni guarda estado local.

Requisitos previos

Node 22.13 o superior, y pnpm (npm también sirve)
Claude Code instalado
Un workspace de cmssy. El plan gratuito basta para esta guía.

Paso 1: Ejecuta la app de ejemplo

Clona el repositorio de ejemplos e inicia simple-blog:

git clone https://github.com/cmssy-io/examples
cd examples/simple-blog
pnpm install
cp .env.example .env.local
pnpm dev

Abre http://localhost:3000. La raíz redirige a /blog, que renderiza contenido de un workspace de demostración público. No necesitas una cuenta para este paso. A continuación, apunta la app a tu propio workspace.

Paso 2: Crea un API token

En el dashboard de cmssy, abre API Tokens y haz clic en Create Token. Ponle un nombre y, en Workspace, elige el workspace que usa este proyecto. Un token limitado a un workspace solo puede abrir ese workspace, que es todo lo que necesita un agente en un repositorio.

Copia el valor cs_... en cuanto aparezca. Se muestra una sola vez.

Un token no tiene permisos propios. Actúa como tú, con el rol que tienes en ese workspace, así que el token de un editor puede editar y el de un miembro de solo lectura solo puede leer.

Paso 3: Vincula la app a tu workspace

npx @cmssy/cli link --token cs_your_token

link obtiene el slug de tu organización, el slug del workspace y el draft secret, y los escribe en .env.local. Si el workspace aún no tiene un manifiesto de bloques, también sube el de la app. Ese manifiesto es la lista de tipos de bloque que la app puede renderizar, aquí prose y blog-index. Reinicia pnpm dev después.

El manifiesto es la razón por la que Claude no pondrá en una página un bloque que tu sitio no puede renderizar: el servidor rechaza los tipos de bloque que el manifiesto no lista.

Paso 4: Encuentra tu workspace ID

El servidor MCP recibe un workspace ID junto con el token. Abre los Settings de tu workspace. El ID está en Workspace Information.

Paso 5: Registra el servidor MCP

Añade .mcp.json a la raíz del proyecto. No contiene secretos, así que puedes subirlo al repositorio:

{
  "mcpServers": {
    "cmssy": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cmssy/mcp-server@latest"]
    }
  }
}

Guarda el token en tu shell. El servidor lee CMSSY_API_TOKEN y CMSSY_WORKSPACE_ID de su entorno, y Claude Code lo inicia con el tuyo:

export CMSSY_API_TOKEN=cs_your_token
export CMSSY_WORKSPACE_ID=your_workspace_id
claude

La primera vez que inicies claude en el proyecto, Claude Code pregunta si confías en el servidor MCP de .mcp.json. Apruébalo y ejecuta /mcp. Deberías ver cmssy conectado.

El servidor también acepta los flags --token y --workspace-id. Úsalos para una prueba local rápida, pero mantén el token fuera de los archivos que subes al repositorio.

Paso 6: Pregunta qué puede renderizar el sitio

Empieza con algo de solo lectura:

¿Qué tipos de bloque puede renderizar mi sitio y qué páginas existen?

Claude llama a list_block_types y list_pages. Los tipos de bloque que lista son los del manifiesto de tu app, con sus campos, así que Claude sabe que prose tiene un body de texto enriquecido antes de escribir nada.

Paso 7: Construye y publica una página

Crea una página /blog con un blog index que liste sus páginas hijas.
Debajo, añade un post llamado "Hello from Claude Code" con dos párrafos
cortos en un bloque prose. Rellena todos los idiomas que el workspace
tenga activados y publica ambas páginas.

Claude trabaja con get_site_config (para ver tus idiomas), create_page, add_block_to_page y publish_page. Claude Code pregunta antes de ejecutar cada herramienta que aún no hayas permitido, así que ves cada escritura antes de que ocurra.

Actualiza http://localhost:3000/blog. El índice lista el nuevo post, y el post se renderiza con el componente prose de la propia app.

Paso 8: Edita y vuelve a publicar

Reescribe el primer párrafo de "Hello from Claude Code" para que mencione
MCP y cambia su título SEO. Luego publícalo.

Las ediciones llegan primero al borrador de la página. Tu sitio sirve solo la versión publicada, así que nada cambia en la app hasta que se ejecuta publish_page. Después, actualiza y el texto nuevo está ahí: en desarrollo, Next renderiza cada petición desde cero.

Para un párrafo dentro de un artículo largo, Claude puede usar patch_block_content, que envía solo la parte modificada en lugar de todo el HTML.

Decide qué puede hacer Claude sin preguntar

Claude Code pregunta antes de cada llamada MCP que no hayas permitido. Permitir las lecturas es seguro. Deja las escrituras, y sobre todo publish_page y delete_page, con confirmación. En .claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__cmssy__list_block_types",
      "mcp__cmssy__list_pages",
      "mcp__cmssy__get_page",
      "mcp__cmssy__get_site_config"
    ]
  }
}

El servidor etiqueta sus herramientas para el cliente: las de lectura como solo lectura, y las que borran, publican o registran un reembolso como destructivas.

Paso a producción

En producción, simple-blog cachea cada página hasta una hora (revalidate = 3600), así que una publicación aparecería con retraso. Activa las actualizaciones inmediatas con una ruta de revalidación y un webhook:

import { createCmssyRevalidateRoute } from "@cmssy/next/server";

export const POST = createCmssyRevalidateRoute({
  secret: process.env.CMSSY_WEBHOOK_SECRET,
});

Ponlo en app/api/revalidate/route.ts y suscribe un webhook a content.changed que apunte a esa ruta. Claude puede crear el webhook con create_webhook. El signing secret se devuelve una sola vez, así que ponlo directamente en CMSSY_WEBHOOK_SECRET en tu hosting. La ruta verifica la firma e invalida los cache tags de cmssy.

¿Sin token? Inicia sesión

Claude Code también puede usar el servidor MCP alojado de cmssy, que te hace iniciar sesión desde el navegador en lugar de usar un token:

claude mcp add --transport http cmssy https://api.cmssy.io/mcp

Ejecuta /mcp y autentícate. Tú eliges qué workspaces puede usar Claude y si obtiene solo lectura o lectura y escritura. Las herramientas son las mismas, pero cada una recibe el workspace como org/workspace, así que una sola conexión puede servir a varios workspaces. Usa la configuración con token para CI o cualquier entorno sin navegador.

Solución de problemas

Cada llamada devuelve "Not authorized": el token fue revocado o ha caducado, o no puede abrir el workspace indicado en CMSSY_WORKSPACE_ID. El servidor arranca igualmente con un token inválido, así que ver "connected" en /mcp no prueba que el token sea válido.
El servidor no aparece: las variables no se exportaron en la shell que inició claude. Sin token, el servidor termina al arrancar.
Falta una herramienta que esperas: puede que npx tenga en caché una versión antigua. Compara npx -y @cmssy/mcp-server --version con npm view @cmssy/mcp-server version.
Se rechaza un bloque: su tipo no está en el manifiesto del workspace. Pide a Claude que ejecute list_block_types y use uno que sí esté.

La referencia completa, con cada herramienta y el permiso que requiere, está en la documentación del servidor MCP. Los tokens se explican en API tokens.

Conecta Claude Code a tu CMS headless mediante MCP