# Herramienta MCP de AI Studio

La herramienta MCP ai_studio: sus operaciones más usadas, los permisos y scopes que piden y la compatibilidad con la antigua ai_prompts.

La herramienta `ai_studio` del servidor `utilia-work` deja que un asistente consulte, cree, modifique y organice los activos de IA de tu organización (prompts, skills, agentes, comandos y plugins) sin pasar por la aplicación, con los permisos de la persona que autorizó el token. Necesitas un token OAuth o una clave personal del servidor `utilia-work` con los scopes `dev:ai-studio:view` o `dev:ai-studio:manage`. Lo que hace cada activo y cómo se organizan se explica en la guía de [AI Studio](https://os.utilia.ai/docs/guides/ai-studio/overview).

## Cómo se invoca

La herramienta recibe siempre el parámetro `operation` y, después, los propios de cada operación:

```json
{
  "name": "ai_studio",
  "arguments": { "operation": "list", "type": "SKILL", "search": "facturas", "limit": 10 }
}
```

Tiene 58 operaciones en ocho bloques: activos, vínculos con otras fichas, colecciones, versiones, compartición, archivos adjuntos, exportación y catálogo compartido (marketplace). Esta página detalla los tres primeros, que son los más usados; la lista completa está en el `inputSchema` que devuelve `tools/list`.

## Activos

| Operación | Qué hace | Parámetros |
| - | - | - |
| `list` | Lista los activos a los que tienes acceso. Por defecto, en vista resumida. | `type`, `status`, `visibility`, `search` (en el nombre, la descripción y el slug), `collectionId`, `limit` (20 por defecto, 100 como máximo), `cursor`, `offset` y `response_format` (`concise` o `detailed`), todos opcionales. Un parámetro que la herramienta no conoce se ignora y se avisa en `_notices.ignoredFields`. |
| `get` | Devuelve un activo con su versión publicada y sus metadatos. | `id`: identificador o slug. |
| `create` | Crea un activo y su primera versión. | Obligatorios: `type` y `name`. Opcionales: `description`, `bodyMarkdown`, `frontmatter`, `visibility`, `departments`, `tags`, `collectionIds`, `iconName`, `color` y `version`. |
| `update` | Modifica un activo. Si cambias `bodyMarkdown` o `frontmatter`, se crea una versión nueva. | `id` y los campos que cambian. |
| `delete` | Borra el activo. Además del permiso, necesitas nivel de administración sobre ese activo. | `id`. |

```json
{
  "operation": "create",
  "type": "PROMPT",
  "name": "Resumen de reunión",
  "description": "Genera un acta con puntos, decisiones y tareas a partir de la transcripción.",
  "bodyMarkdown": "Eres un asistente que resume reuniones...",
  "tags": ["meet", "resumen"]
}
```

La herramienta no ejecuta activos contra ningún modelo: la antigua operación `execute` se retiró y devuelve un error de operación no válida. Para obtener el texto de un prompt con sus variables ya sustituidas, usa `ai_studio(operation: 'use', id, variables)`, que reemplaza cada `{{variable}}` y devuelve el texto final para que lo uses en tu propio cliente de IA. Cada llamada suma un uso al activo, igual que `record_use`.

## Vínculos con otras fichas

| Operación | Qué hace | Parámetros |
| - | - | - |
| `link_to_entity` | Vincula el activo a una ficha del ecosistema, como un elemento de trabajo, un proyecto o una oportunidad. | `id`, `entityType` y `entityId`. |
| `search_by_entity` | Lista los activos vinculados a una ficha. | `entityType` y `entityId`. |

```json
{
  "operation": "link_to_entity",
  "id": "redactor-de-respuesta-comercial",
  "entityType": "OPPORTUNITY",
  "entityId": "cl9xy0000exampleopp01"
}
```

## Colecciones

| Operación | Qué hace | Parámetros |
| - | - | - |
| `list_collections` | Lista las colecciones de tu organización, con su árbol. | Ninguno. |
| `create_collection` | Crea una colección; con `parentId` queda dentro de otra. | `name` y, opcionales, `description`, `parentId`, `iconName` y `color`. |

## Permisos y scopes

Cada operación pide el permiso de tu usuario y el scope del token. Además, cada una comprueba tu acceso al activo concreto: su visibilidad y lo que se haya compartido contigo.

| Operación | Permiso | Scope |
| - | - | - |
| `list`, `get`, `search_by_entity` | `AI_STUDIO_VIEW` | `dev:ai-studio:view` |
| `list_collections` | `AI_STUDIO_VIEW` o `AI_STUDIO_MANAGE_COLLECTIONS` | `dev:ai-studio:view` |
| `create` | `AI_STUDIO_CREATE` | `dev:ai-studio:manage` |
| `update`, `link_to_entity` | `AI_STUDIO_EDIT` | `dev:ai-studio:manage` |
| `delete` | `AI_STUDIO_DELETE` | `dev:ai-studio:manage` |
| `create_collection` | `AI_STUDIO_MANAGE_COLLECTIONS` | `dev:ai-studio:manage` |
| `use` | `AI_STUDIO_VIEW` | `dev:ai-studio:manage`, porque suma un uso al activo |
| `ai_prompts`: `list`, `get` y `use` | `AI_STUDIO_VIEW` | `dev:prompts:view` |

Los conjuntos `dev:read` y `dev:full` incluyen los scopes de lectura. Todas las consultas se limitan a tu organización, también para el rol Super Administrador: nadie ve ni toca activos de otra organización por esta vía. Qué permisos trae cada rol se explica en [AI Studio: permisos y roles](https://os.utilia.ai/docs/guides/ai-studio/permissions).

## Compatibilidad con `ai_prompts`

La herramienta `ai_prompts`, anterior a AI Studio, sigue funcionando sobre los activos de tipo prompt:

- `ai_prompts(operation: 'list')` equivale a `ai_studio(operation: 'list', type: 'PROMPT')`.
- `ai_prompts(operation: 'get', id)` equivale a `ai_studio(operation: 'get', id)` y comprueba que el activo sea un prompt.
- `ai_prompts(operation: 'use', id, variables)` equivale a `ai_studio(operation: 'use', id, variables)`: sustituye las variables del prompt y devuelve el texto final, sin llamar a ningún modelo.

Está marcada como obsoleta, no se anuncia por defecto y se retirará el 8 de enero de 2027, pero responde por compatibilidad hasta entonces. Si empiezas una integración, usa `ai_studio`: cubre todos los tipos de activo y las operaciones de vínculos, colecciones, versiones y `use`.

## Errores frecuentes

| Mensaje | Causa |
| - | - |
| «Activo '...' no encontrado. Usa ai_studio(operation: 'list')...» | El identificador no existe o no tienes acceso al activo. |
| «Operación no válida: ...» | `operation` no es ninguna de las válidas. El mensaje enumera las operaciones, pero no todas: la lista completa es la del `inputSchema`. |
| «Se requiere el parámetro "operation"» | Falta `operation`. |
| «Permiso denegado. Requiere: ...» | Falta el permiso `AI_STUDIO_*` de la operación. |

## Siguiente paso

Vincula los prompts y skills que use tu equipo a sus oportunidades o proyectos con `link_to_entity`, y recupéralos desde la ficha con `search_by_entity`: así el asistente trabaja con el mismo criterio que el equipo.