Configurar Crafty mediante el servidor MCP

Usa esto cuando un agente deba crear y configurar contenido en un tenant de Crafty: sitios, páginas/bloques, colecciones/entradas, formularios, medios y publicación.

URL del servidor

El endpoint MCP es por tenant y se encuentra en la ruta /mcp del propio dominio del tenant:

https://<your-tenant-domain>/mcp

El tenant se identifica por el host de la solicitud, así que cada tenant tiene su propio endpoint. Si usas un host incorrecto, no se resolverá el tenant. Cada solicitud debe estar autenticada (token Bearer).

Autenticación

Hay dos familias, ambas con un token Bearer en cada solicitud:

Personal Access Token (PAT): la opción más sencilla

Genera un Personal Access Token de larga duración desde tu perfil de Crafty, eligiendo los scopes que necesites, y luego pégalo en la configuración del editor como cabecera Authorization: Bearer …. Es ideal para CLIs y configuraciones locales. Si deja de funcionar, regénéralo y actualiza la configuración.

OAuth 2.0: mediante un cliente MCP

Crea un "cliente MCP" en tu perfil de Crafty y elige un tipo de concesión (grant type):

• Authorization Code: flujo estándar con redirección del navegador para herramientas que abren un navegador (Claude.ai, Claude Code, Codex, Cursor, VS Code, ChatGPT). Selecciona la URI de redirección que corresponda a tu herramienta. La mayoría se registra sola (ver más abajo), así que un cliente manual solo es necesario cuando la herramienta pide un client_id.
• Device Code (RFC 8628): para clientes que no pueden abrir un navegador y admiten esta concesión; el cliente muestra un código que apruebas en el navegador.

Al crear el cliente manualmente en tu perfil se te muestran el client_id y un client_secret de un solo uso. Cópialo de inmediato (los PAT también muestran el token una sola vez). Los clientes que se registran automáticamente mediante discovery (por ejemplo, Claude.ai, Claude Code, Codex, Cursor, ChatGPT) se registran como clientes públicos y no reciben client secret.

Los clientes OAuth que admiten el autodescubrimiento de MCP (Claude.ai, Claude Code, Codex, Cursor, ChatGPT) pueden encontrar todo solo con la URL del servidor: el discovery se publica en /.well-known/oauth-protected-resource y /.well-known/oauth-authorization-server, con authorization_endpoint /oauth/authorize, token_endpoint /oauth/token, registration_endpoint dinámico /oauth/register, PKCE (S256) y las concesiones authorization_code + refresh_token. Las URI de redirección registradas deben ser https, un esquema de aplicación personalizado o http en una dirección de loopback (así funcionan los callbacks de CLI locales). Estos endpoints OAuth están en la raíz del tenant, no bajo /mcp.

Los clientes que implementan la especificación de autorización MCP 2026-07-28 pueden omitir el registro y usar un Client ID Metadata Document (CIMD): el client_id es una URL https que sirve los metadatos del cliente en JSON (client_id igual a esa URL, redirect_uris, y client_name opcional). Crafty anuncia client_id_metadata_document_supported: true, obtiene el documento en /oauth/authorize (solo direcciones públicas, sin redirecciones, 5 KB como máximo, en caché según el max-age de su Cache-Control) y exige que la redirect_uri esté listada en él. Solo se aceptan de esta forma los clientes públicos (token_endpoint_auth_method: "none"). El registro dinámico sigue funcionando para los clientes que aún lo usan.

Scopes

Al crear un token (PAT o cliente OAuth) concedes uno o más scopes. Los scopes se aplican por herramienta: una herramienta solo se anuncia si tu token tiene el scope requerido, y si la invocas sin ese scope falla con un error de MCP (Insufficient OAuth scope). Concede los scopes que el agente necesite:

Solicita los cuatro para tener acceso completo a la creación de contenido y a los envíos. Los scopes también se anuncian en el discovery de OAuth; el endpoint /mcp además exige un token autenticado válido en cada solicitud.

Conectar cada cliente

Reemplaza https://<tenant>/mcp por la URL de tu tenant y YOUR_PAT por un Personal Access Token.

Claude.ai (Authorization Code): ve a Customize → Connectors → + → Add custom connector, introduce la URL del servidor, haz clic en Connect y aprueba en el navegador (en planes Team/Enterprise, un Owner la añade primero en Organization settings → Connectors). Se registra automáticamente; si prefieres usar tu propio cliente, crea un cliente MCP Authorization Code con la URI de redirección https://claude.ai/api/mcp/auth_callback y pega su client_id/client_secret en Advanced settings del conector.

Claude Code (CLI):

# Opción A: PAT
claude mcp add --transport http crafty https://<tenant>/mcp \
  --header "Authorization: Bearer YOUR_PAT"

# Opción B: OAuth en el navegador (se registra automáticamente)
claude mcp add --transport http crafty https://<tenant>/mcp
# después, dentro de Claude Code: /mcp → crafty → Authenticate

Cursor (Authorization Code): añade lo siguiente a ~/.cursor/mcp.json y autoriza cuando se te pida (se registra automáticamente; para tu propio cliente usa la URI de redirección cursor://anysphere.cursor-deeplink/mcp/auth_callback):

{ "mcpServers": { "crafty": { "url": "https://<tenant>/mcp" } } }

VS Code (GitHub Copilot, PAT): añade lo siguiente a .vscode/mcp.json, luego abre Copilot Chat → modo Agent y selecciona las herramientas de Crafty. (Alternativa OAuth: cliente Authorization Code con la URI de redirección vscode://github.copilot-chat/mcp/auth_callback).

{ "servers": { "crafty": { "type": "http", "url": "https://<tenant>/mcp",
  "headers": { "Authorization": "Bearer YOUR_PAT" } } } }

Codex CLI (escribe en ~/.codex/config.toml):

# Opción A: PAT, leído desde una variable de entorno
export CRAFTY_MCP_TOKEN="YOUR_PAT"
codex mcp add crafty --url https://<tenant>/mcp --bearer-token-env-var CRAFTY_MCP_TOKEN

# Opción B: OAuth en el navegador (se registra automáticamente)
codex mcp add crafty --url https://<tenant>/mcp
codex mcp login crafty

ChatGPT (Authorization Code; Plus, Pro, Business, Enterprise, Education, web): activa Developer mode en Settings → Apps & Connectors → Advanced settings, haz clic en Create, pega la URL del servidor, elige OAuth y aprueba en el inicio de sesión de Crafty. Se registra automáticamente.

Catálogo de herramientas

Todas las herramientas devuelven una respuesta de texto JSON. Los IDs son enteros; los slugs son cadenas. La paginación es de 25 por página por defecto (per_page con máximo de 100 cuando se admite).

Lectura (crafty:read)

Envíos (crafty:submissions)

Los envíos de formularios pueden contener datos personales, por eso requieren su propio scope.

Escritura (crafty:write)

| configure_assistant | site_id y al menos un ajuste | environment (por defecto production), enabled, whatsapp_enabled, whatsapp_number, whatsapp_label, contact_form, hours (weekdays/saturday/sunday → { open, close } o null), timezone, greeting, suggestions (máximo 3), tone (friendly/formal/technical), guidelines, privacy_url, appearance (name, color, font, corners, position, avatar_on_launcher) | solo cambian las claves enviadas, null restablece el valor por defecto; el avatar se sube desde el panel; devuelve la configuración efectiva y el status | | configure_store | site_id | environment (por defecto production), enabled, currency, order_prefix, prices_include_tax, taxes, default_tax, delivery (enabled, fee, free_from, tax, zone), pickup (enabled, address), payment_methods (cash_on_delivery, pay_at_pickup, transfer), transfer_accounts, notify_emails, customer_emails, return_url, color, logo_media_id, font, corners, checkout_fields, checkout_analytics, captcha | solo administradores; enabled: true requiere que la tienda esté en el plan y crea (o adopta) la colección productos y la URL de pago; solo cambian las claves enviadas; solo con site_id únicamente lee; devuelve la configuración, open, el resumen de productos y checkout_url. Consulta online-store.md | | list_orders | site_id | environment, status, payment_status, search, limit, page | requiere el permiso orders (lectura) | | get_order | site_id, number | environment | el pedido con sus líneas (id para update_order), fields, metadata, payment_url, next_statuses e historial | | create_order | site_id, customer, fulfillment, payment_method, items | environment, address, fields, metadata, coupon, locale, expected_total | permiso de escritura orders; origen mcp; devuelve el pedido y su payment_url | | update_order | site_id, number | environment, claves de edición (items, fulfillment, payment_method, customer, address, fields, metadata, coupon, coupon_below_minimum), notify, status, paid, payment_reference, internal_note | solo edita pedidos abiertos no pagados (los metadatos siempre); las líneas antiguas conservan su precio; dispara order.updated | | list_coupons | site_id | environment, status, search | cupones con status, uses, orders, sales, discounted; requiere el permiso coupons (lectura) | | get_coupon | site_id, code | environment | las reglas de un cupón (productos como slugs) y sus resultados | | upsert_coupon | site_id, code | environment, name, type, value, max_discount, min_subtotal, applies_to, products, max_uses, max_uses_per_email, starts_at, ends_at, is_active | crea o modifica por código; un cupón ya usado conserva su código y tipo; requiere escritura en coupons | | delete_coupon | site_id, code | environment | elimina un cupón no usado, pausa uno usado | | configure_bookings | site_id | environment (por defecto production), enabled, timezone, hours (combinadas por día de la semana), closed_dates, min_notice_minutes, max_days_ahead, slot_interval, cancel_notice_minutes, auto_confirm, reminder_hours, payment_methods (pay_at_venue, transfer), address, phone, checkout_fields | solo administradores; enabled: true requiere reservas en el plan y crea (o adopta) las colecciones servicios y profesionales; solo cambian las claves enviadas; solo con site_id únicamente lee; devuelve la configuración, open, los slugs de servicios y profesionales y checkout_url. Consulta online-bookings.md | | get_booking_availability | site_id | environment, service, professional, from, to | sin service: los servicios y profesionales reservables; con él: huecos libres por día local (hasta 31 días), cada uno con los profesionales libres | | list_bookings | site_id | environment, from, to, status, professional, search, metadata, limit, page | requiere el permiso de reservas (lectura) | | get_booking | site_id, number | environment | la reserva con next_statuses, internal_note, customer_url y events | | create_booking | site_id, service, start, customer | environment, professional, payment_method, fields, metadata, outside_hours, internal_note, locale | permiso de escritura de reservas; origen mcp; un hueco ocupado responde SLOT_UNAVAILABLE | | update_booking | site_id, number | environment, start, professional, outside_hours, status, paid, payment_reference, internal_note, metadata | mueve la reserva, cambia el estado o la marca como pagada; devuelve la reserva y applied | | set_professional_schedule | site_id, professional | environment, mode (shop/own), hours | sin mode solo lee; los horarios propios siempre quedan dentro de los de la tienda | | manage_booking_blocks | site_id, action (list/create/delete) | environment, professional, repeat (once/weekly), from_date, to_date, all_day, start_time, end_time, weekdays, reason, id (para eliminar) | bloquea tiempo para un profesional o para toda la tienda; create devuelve cuántas reservas ya caen dentro | | upsert_assistant_answer | site_id, question, answer | environment (por defecto production), answer_id | añade una respuesta fija o edita la que tiene answer_id; el asistente la usa desde el siguiente mensaje del visitante | | delete_assistant_answer | site_id, answer_id | environment (por defecto production) | elimina una respuesta fija | | upsert_redirects | site_id, redirects | environment (por defecto production), dry_run | hasta 500 { source, destination, status_code? } por llamada, emparejadas por source; source es una ruta que empieza por / (sin espacios, ? ni #; se admiten los splats * y los :placeholders de Cloudflare Pages), destination una ruta o una URL http(s) absoluta, status_code 301 (por defecto) / 302 / 307 / 308; los elementos no válidos aparecen en failed y se omiten. Crafty hosting las escribe en _redirects en el siguiente despliegue (después de las reglas propias del sitio; límite de 2000 estáticas + 100 dinámicas); los frontends personalizados leen GET /api/v1/redirects | | delete_redirect | site_id, source | environment (por defecto production) | elimina una redirección |

Las herramientas del asistente siguen la sección Asistente del panel: los administradores siempre, los editores con acceso de lectura pueden leer y los editores con acceso de escritura pueden modificar.

Las herramientas de redirección siguen el permiso Pages: leer requiere acceso a páginas, modificar requiere acceso de escritura.

Publicación (crafty:publish)

Flujos de trabajo canónicos

Modelar contenido con tipos de bloque (recomendado)

1. list_sites → elige un site_id (o create_site).
2. Para cada sección del diseño, create_block_type (o get_block_type si ya existe). Usa un repeater para listas de elementos, stringList para listas de cadenas simples y reference / multiReference con model: "Media" para imágenes (súbelas primero); usa una colección solo para conjuntos grandes e independientes de registros.
3. create_page en el idioma por defecto con blocks: [{ block_type_id, data }, …]; corrige los errores blocks.N.data.… y revisa warnings. Para otros idiomas, ejecuta configure_locales una vez y luego upsert_translation por página (bloques por id desde get_page), o translate_content para que la IA lo traduzca una vez que la traducción con IA esté habilitada para el workspace y el sitio (configure_translation).
4. publish_page.
5. Para cambiar un esquema más adelante, update_block_type con la lista COMPLETA de campos (usa force: true solo si aceptas dejar huérfanos los datos que los bloques ya contienen).

Crear y publicar una página

1. list_sites → elige un site_id (o create_site).
2. get_block_type / list_block_types → anota cada id y su esquema de datos.
3. create_page con site_id, title y blocks: [{ block_type_id, data }, …].
4. publish_page con el page_id devuelto.

Contenido estructurado

1. list_collections (opcionalmente con site_id) → elige un collection_slug, o create_collection con sus fields (update_collection los cambia más adelante).
2. create_entry con collection_slug, site_id, slug y data.
3. update_entry para editar (cada edición guarda una revisión).

Formularios

1. create_form con site_id, name, slug y fields.
2. publish_form para que acepte envíos públicos.
3. list_form_submissions / get_form_submission para leer lo que enviaron los visitantes.

Medios

1. ¿Necesitas URL públicas permanentes? Primero manage_media_collection con site_id, key, is_public: true (si no, los archivos reciben URL firmadas con caducidad).
2. Desde una URL o un archivo pequeño: upload_media con url, site_id y alt (opcionalmente collection_name, sha256). Desde un archivo local: calcula shasum -a 256 <file>, llama a request_media_upload (con alt) y luego ejecuta el comando curl -T devuelto.
3. list_media para confirmar y obtener URL; asigna con update_media un texto alt a cada imagen de contenido que no lo tenga.

Migrar un sitio existente

Sigue migrate-to-crafty.md: rastrear → clasificar → modelar → import_media_from_urls → bulk_upsert_entries (borradores, primero dry_run) → upsert_redirects → revisión humana → publicar.

Editor visual

1. Prepara el frontend (consulta visual-editor.md).
2. configure_visual_editor con site_id, frontend_url, routes y render_mode.
3. Pide al usuario que abra Editar sitio en el admin para confirmar que la edición al hacer clic funciona.

Gestión de la caché de respuestas de la API

La API pública tiene una caché de respuestas basada en etiquetas (habilitada por entorno). Las anulaciones por sitio tienen prioridad sobre la configuración global.

• Desactiva la caché de un sitio antes de las ediciones masivas y vuelve a activarla al terminar:
  1. set_api_cache_status con site_id y enabled: false.
  2. Haz todos tus cambios de contenido (update_entry, update_page, etc.).
  3. set_api_cache_status con enabled: true.
  4. flush_api_cache con site_id (y opcionalmente resource) para borrar las entradas obsoletas.
• Vacía solo un tipo de recurso después de cambios puntuales:
  • flush_api_cache con site_id y resource: "entries" tras actualizar entradas.
  • flush_api_cache con site_id y resource: "pages" tras actualizar páginas.
• flush_api_cache sin resource (o con resource: "all") borra de una vez todas las respuestas en caché del sitio.

Solución de problemas

• 401 / error de autenticación: el token Bearer falta, no es válido o ha caducado; vuelve a conectar o regenéralo. Cada solicitud a /mcp debe llevar un token válido.
• Falta una herramienta o falla con Insufficient OAuth scope: el token no tiene el scope de esa herramienta. Las herramientas solo se anuncian si el token tiene el scope correspondiente (crafty:write para crear/editar, crafty:publish para publicar, crafty:submissions para leer envíos de formularios). Vuelve a emitir el token con los scopes que necesitas.
• Tenant no encontrado: host incorrecto; usa el dominio exacto del tenant. Los endpoints de token de OAuth están en la raíz del tenant (/oauth/...), no bajo /mcp.
• OAuth falla con un cliente creado manualmente: su tipo debe coincidir con el flujo (Authorization Code o Device Code), su URI de redirección debe ser exactamente la que usa la herramienta, y client_id/client_secret deben coincidir. Las herramientas que se registran automáticamente no necesitan cliente manual.
• Token/secreto perdido: client_secret y los PAT se muestran solo una vez al crearlos; regénéralos si los pierdes.