# Herramientas MCP de chat

Las herramientas chat_channels, chat_messages y chat_agents con las que un asistente de IA consulta y organiza los canales del Chat en nombre de una persona.

Además de la API para aplicaciones, el Chat tiene un servidor MCP para que un asistente de IA (Claude, ChatGPT u otro cliente compatible) consulte y organice los canales **en nombre de la persona que lo conecta**: puede hacer lo mismo que esa persona en el Chat, y nada más.

No lo confundas con la API para aplicaciones: son dos superficies distintas. Esta página trata del MCP.

**API del chat o MCP del chat**

## API para aplicaciones (/api/external/v1/chat)

Actúa con la identidad de tu aplicación, autenticada con su clave de API. Puede publicar mensajes. Se gobierna por los scopes de la aplicación y por la concesión de cada canal.

## MCP del chat (/api/mcp/chat)

Actúa en nombre de la persona que conecta su asistente, con un token de OAuth. No publica mensajes. Se gobierna por los scopes del token, los permisos de esa persona y su papel en cada canal.

## Conectarse

El servidor es `/api/mcp/chat` y aparece como «Chat» en [Ajustes › Integraciones › Conecta tu IA](https://os.utilia.ai/dashboard/settings/connect-ai). Cómo conectar un cliente y autorizarlo está en [Conecta tu IA](https://os.utilia.ai/docs/guides/connect-ai/overview).

Al autorizar, concede solo los scopes que necesites:

| Scope | Qué permite |
| - | - |
| `chat:channels:view` | Ver tus canales, su detalle y sus miembros. |
| `chat:messages:view` | Leer y buscar mensajes de esos canales. |
| `chat:channels:create` | Crear canales. |
| `chat:channels:manage` | Editar y archivar canales. |
| `chat:members:manage` | Añadir y retirar miembros. |
| `chat:agents:view` | Ver los agentes de IA de tus canales. |
| `chat:agents:manage` | Instalar, configurar, pausar, reanudar y retirar agentes de IA. |

Un token con scopes de lectura nunca puede escribir: cada operación de escritura exige su propio scope.

Además del scope, cada operación pide el permiso de la persona: `CHAT_CONVERSATIONS_VIEW` para ver canales, `CHAT_MESSAGES_VIEW` para leer mensajes, `CHAT_CHANNEL_CREATE` para crear, `CHAT_CHANNEL_EDIT` para editar o archivar, `CHAT_PARTICIPANTS_ADD` y `CHAT_PARTICIPANTS_REMOVE` para los miembros y `CHAT_AGENTS_MANAGE` para los agentes. Las escrituras exigen también ser propietario o administrador del canal, como en el propio Chat.

> **Nota: Solo canales**
>
> El MCP trabaja únicamente con canales. No lista ni deja abrir conversaciones directas, grupos ni conversaciones del portal del cliente, aunque la persona esté en ellos. Lo mismo vale para mensajes, miembros y agentes.

## chat_channels

Consulta y organiza los canales de la persona.

| Operación | Qué hace | Parámetros | Scope |
| - | - | - | - |
| `list` | Lista tus canales. | `includeArchived` (opcional, `false` por defecto) | `chat:channels:view` |
| `get` | Detalle de un canal. | `channelId` | `chat:channels:view` |
| `list_members` | Miembros de un canal. | `channelId` | `chat:channels:view` |
| `create` | Crea un canal. | `name`; opcionales `description`, `isDiscoverable` y `userIds` (hasta 100) | `chat:channels:create` |
| `update` | Cambia el nombre o la descripción. | `channelId`; `name` o `description` | `chat:channels:manage` |
| `archive` | Archiva un canal. | `channelId` | `chat:channels:manage` |
| `add_member` | Añade a una persona. | `channelId`, `userId` | `chat:members:manage` |
| `add_members` | Añade hasta 100 personas, con un resultado por cada una. | `channelId`, `userIds` | `chat:members:manage` |
| `remove_member` | Retira a una persona. | `channelId`, `userId` | `chat:members:manage` |

Con `create` y `userIds` creas el canal con sus miembros de una vez; quien conecta el asistente entra siempre como propietario. Con `add_members`, un identificador erróneo no impide añadir a los demás.

```json
{
  "operation": "create",
  "name": "Alertas de infraestructura",
  "description": "Avisos de la sala de servidores",
  "userIds": ["usr_12ab", "usr_7a1b"]
}
```

`archive` y `remove_member` cambian el canal para todos sus participantes, así que la herramienta los marca para que el cliente pida confirmación.

## chat_messages

Lee los mensajes de un canal. Solo lectura, con el scope `chat:messages:view`.

| Operación | Qué hace | Parámetros |
| - | - | - |
| `list` | Mensajes de un canal, paginados por cursor. | `channelId`; opcionales `cursor` y `limit` (de 1 a 100, 50 por defecto) |
| `get` | Detalle de un mensaje. | `messageId` |
| `search` | Busca texto dentro de un canal. | `channelId`, `query`; opcional `limit` (de 1 a 100) |

Nunca devuelve respuestas privadas de la IA de otras personas. Por MCP no se pueden publicar mensajes: para eso está el [endpoint de publicación](https://os.utilia.ai/docs/developers/chat-platform/post-messages) de las aplicaciones.

## chat_agents

Consulta y gestiona los agentes de IA de tus canales.

| Operación | Qué hace | Scope |
| - | - | - |
| `list`, `get` | Agentes instalados y su detalle. | `chat:agents:view` |
| `install` | Instala un agente publicado en AI Studio. | `chat:agents:manage` |
| `update` | Cambia nombre, herramientas, acceso a la web y límites. | `chat:agents:manage` |
| `pause`, `resume` | Pausa o reactiva un agente. | `chat:agents:manage` |
| `remove` | Lo retira del canal. | `chat:agents:manage` |

El paquete de scopes `chat:write` no incluye `chat:agents:manage`; `chat:full` sí.

## Ejemplos de peticiones al asistente

- «¿En qué canales estoy?» → `chat_channels` con `list`.
- «Crea un canal para las alertas del servidor con Marta y Luis.» → `chat_channels` con `create` y `userIds`.
- «Busca dónde se habló de la incidencia del jueves.» → `chat_messages` con `search`.

## Siguiente paso

Si lo que quieres es que una aplicación tuya publique en el Chat, no un asistente en nombre de alguien, sigue con [Publicar mensajes](https://os.utilia.ai/docs/developers/chat-platform/post-messages).