diff --git a/CLAUDE.md b/CLAUDE.md
index a858765..78fdfdb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -104,6 +104,18 @@ Do NOT modify web-base files — they are shared across all projects.
 9. Twig concatenation uses `~` operator: `'value=' ~ variable`
 10. `enlace` (link) fields already include slashes
 
+## MCP Tools
+
+This project has MCP tools for managing modules, records, media, and more. **Before starting any task, consult the tools reference for the correct workflow.**
+
+See [docs/mcp-tools-reference.md](docs/mcp-tools-reference.md) for the complete list of available tools and step-by-step workflows.
+
+Key workflows:
+- **Create module**: `create_module` → `add_module_to_record` → `set_module_config_vars` → images
+- **Edit module**: read vars → edit `index-base.tpl` → `compile_module`
+- **Add images**: `get_module_config_vars` → `upload_record_image` (fieldName from builder.json relations)
+- **Generate images**: `generate_image` → `upload_record_image` with returned URL
+
 ## Documentation
 
 - [docs/modular-system.md](docs/modular-system.md) — Modules, general sections, global variables
@@ -115,3 +127,4 @@ Do NOT modify web-base files — they are shared across all projects.
 - [docs/production-patterns.md](docs/production-patterns.md) — Real production patterns (header, zigzag, FAQ, forms)
 - [docs/vue-builder-rules.md](docs/vue-builder-rules.md) — CMS-VUE rules (tabs, colorpicker, components)
 - [docs/vue-builder-examples.md](docs/vue-builder-examples.md) — Vue builder examples (Banner Slideshow, etc.)
+- [docs/mcp-tools-reference.md](docs/mcp-tools-reference.md) — MCP tools reference, available tools, workflows
diff --git a/docs/mcp-tools-reference.md b/docs/mcp-tools-reference.md
new file mode 100644
index 0000000..adcac3d
--- /dev/null
+++ b/docs/mcp-tools-reference.md
@@ -0,0 +1,91 @@
+# MCP Tools Reference
+
+## Quick Reference
+
+| Tool | Categoría | Acción |
+|------|-----------|--------|
+| `create_module` | Módulos | Crea módulo nuevo (directorio + archivos + compila) |
+| `compile_module` | Módulos | Compila módulo tras editar index-base.tpl |
+| `check_module` | Módulos | Preview de cómo renderiza un módulo |
+| `check_module_usage` | Módulos | Qué páginas usan un módulo |
+| `set_module_example_data` | Módulos | Datos de ejemplo para editor visual |
+| `list_page_modules` | Registros | Lista módulos de una página |
+| `add_module_to_record` | Registros | Añade módulo a una página |
+| `remove_module_from_record` | Registros | Elimina módulo de una página |
+| `reorder_module` | Registros | Cambia posición de un módulo |
+| `toggle_module_visibility` | Registros | Muestra/oculta módulo |
+| `get_module_config_vars` | Registros | Lee variables de un módulo |
+| `set_module_config_vars` | Registros | Escribe variables de un módulo |
+| `list_table_records` | Registros | Buscar/listar registros con filtros |
+| `get_record` | Registros | Obtener un registro por num |
+| `create_or_update_record` | Registros | Crear o actualizar registros |
+| `delete_table_records` | Registros | Eliminar registros (destructivo) |
+| `upload_record_image` | Media | Subir imagen a campo de registro (desde URL) |
+| `generate_image` | Media | Generar imagen con IA y guardar en uploads |
+| `upload_image_to_assets` | Media | Subir imagen a /images/ del template |
+| `list_record_uploads` | Media | Listar uploads de un campo |
+| `replace_record_image` | Media | Reemplazar imagen existente |
+| `delete_record_upload` | Media | Borrar upload |
+| `reorder_record_uploads` | Media | Reordenar imágenes de un campo |
+| `refresh_acai_token` | Auth | Renovar token JWT expirado |
+| `orchestrate_task` | Orquestador | Guía paso a paso para tareas complejas |
+| `rollback_git` | Git | Recuperar cambios de git remoto |
+
+## Flujos de trabajo
+
+### Crear un módulo nuevo desde cero
+
+1. `create_module` — Crea el directorio con index-base.tpl, style.css, script.js y compila
+2. `add_module_to_record` — Añade el módulo a una página (tabla padre, ej: `apartados`)
+3. `set_module_config_vars` — Rellena las variables con contenido (textos, colores, opciones). **OBLIGATORIO** — sin esto el módulo no muestra nada
+4. Para imágenes: `generate_image` o `upload_record_image` usando el `recordNum` devuelto por set_module_config_vars
+5. Verificar con `check_module` o recargando la página
+
+### Editar un módulo existente
+
+1. `get_module_config_vars` — Leer el estado actual del módulo (variables, recordNums)
+2. Editar `index-base.tpl` con la tool `Write` o `Edit`
+3. `compile_module` — **OBLIGATORIO** tras cada edición de index-base.tpl
+4. Si cambias variables: `set_module_config_vars` para actualizar valores
+
+### Añadir/modificar imágenes de un módulo
+
+1. `get_module_config_vars` — Obtener el `recordNum` de builder_custom
+2. Leer `builder.json` del módulo para encontrar el `fieldName` real (ej: `image1`, NO el nombre de la variable)
+3. `upload_record_image` con:
+   - `tableName`: `"builder_custom"` (siempre sin cms_)
+   - `recordId`: el recordNum del paso 1
+   - `fieldName`: el campo de relations del builder.json (ej: `image1`)
+   - `imageUrl`: URL accesible desde Docker (ej: `http://localhost/cms/uploads/...`)
+4. `list_record_uploads` para verificar
+5. `reorder_record_uploads` si necesitas cambiar el orden
+
+### Generar imagen con IA
+
+1. `generate_image` con prompt descriptivo + style (photographic, digital-art, minimalist...)
+2. La imagen se guarda en `cms/uploads/generated/` y devuelve `dockerUrl`
+3. Usar esa `dockerUrl` con `upload_record_image` para asignarla a un módulo
+
+### Gestionar registros de una tabla
+
+1. `list_table_records` — Buscar registros con filtros (`where`, `order`, `limit`)
+2. `get_record` — Obtener un registro completo por num
+3. `create_or_update_record` — Crear o actualizar (la tabla sin prefijo `cms_`, PK es `num`)
+4. `delete_table_records` — Eliminar por IDs
+
+### Explorar el sitio
+
+1. `orchestrate_task` con workflow `explore_site` — Guía para entender la estructura
+2. `list_page_modules` — Ver qué módulos tiene cada página
+3. `get_module_config_vars` — Ver los datos de cada módulo
+4. `check_module` — Preview de cómo renderiza
+
+## Reglas importantes para todas las tools
+
+1. **tableName** siempre SIN prefijo `cms_` (ej: `apartados`, no `cms_apartados`)
+2. **Primary key** es siempre `num`, nunca `id`
+3. **Uploads** son arrays — acceder con `[0].urlPath`
+4. **fieldName de imágenes** viene de `builder.json` → `vars.NOMBRE.relations.builder_custom` (ej: `image1`), NO del nombre de la variable
+5. **recordId para imágenes** es el `num` de `builder_custom`, NO el sectionId del módulo
+6. Tras `set_module_config_vars`, TODAS las variables del módulo (incluyendo upload) reciben config-vars automáticamente
+7. Si el token expira (error 403), usar `refresh_acai_token`