# Servidor MCP

> Conecta Claude, ChatGPT, Cursor o tu propio agente a tu espacio de trabajo de watsi por MCP, con una clave de API u OAuth 2.1, y conoce cada herramienta y su alcance.

Source: https://docs.watsi.ai/mcp

- [Conecta con Claude](/mcp/claude)
    Búscalo como watsi en el directorio de conectores de Claude. Guía con capturas.
- [Conecta con ChatGPT](/mcp/chatgpt)
    Agrégalo con su URL como servidor MCP en ChatGPT. Guía con capturas.

**Configúralo con tu asistente en un paso**

Copia este prompt y pégalo en ChatGPT, Claude o tu agente de código (Claude Code, Cursor, Codex). El asistente agrega watsi como conector y se abre tu navegador para que inicies sesión en watsi y apruebes el acceso, como con cualquier otro conector. No hay clave de API que crear ni copiar. Al final, el asistente comprueba que la conexión funciona.

```text
Conecta mi espacio de trabajo de watsi a esta app de IA como servidor MCP remoto con OAuth. Haz tú todo lo que puedas y pídeme sólo lo que únicamente yo puedo hacer, de a un paso a la vez.

Datos de watsi:
• Servidor MCP: https://mcp.watsi.ai/mcp (Streamable HTTP; no hay endpoint /sse).
• Autenticación: OAuth 2.1 con registro dinámico de clientes. Se agrega sólo la URL, sin encabezados ni clave de API. El cliente abre el navegador, inicio sesión en watsi, elijo el espacio de trabajo y apruebo los permisos.
• No uses una clave de API ni me pidas una. Si el cliente no logra iniciar sesión, diagnostica el problema en lugar de cambiar a una clave.
• En la pantalla de watsi los permisos de lectura vienen marcados y los de escritura desmarcados. agents:write, knowledge:write y scheduling:write reescriben la configuración de mis agentes y pueden publicarla en mis canales.
• Documentación: https://docs.watsi.ai/mcp.md (léela si puedes navegar).

Paso 1: Pregúntame una sola cosa: si quiero sólo consultar mis datos o también hacer cambios, para decirme qué permisos marcar en la pantalla de watsi.
Paso 2: Agrega el servidor tú mismo si puedes correr comandos o editar archivos:
• Claude Code: corre claude mcp add --transport http watsi https://mcp.watsi.ai/mcp y luego pídeme escribir /mcp, elegir watsi y Authenticate. Se abre el navegador.
• Cursor: agrega a ~/.cursor/mcp.json un servidor llamado watsi con sólo url igual a https://mcp.watsi.ai/mcp. Luego pídeme abrir Cursor Settings, la sección de MCP, y dar clic en el botón para iniciar sesión junto a watsi. Se abre el navegador.
• Codex: corre codex mcp add watsi --url https://mcp.watsi.ai/mcp y luego codex mcp login watsi. Se abre el navegador.
• Otro cliente: agrégalo con sólo la URL como servidor HTTP remoto y usa su forma de iniciar sesión con OAuth.
Paso 2, si eres una app de chat: no puedes instalar conectores tú mismo. En Claude (web, escritorio o móvil), watsi está en el directorio de conectores de Claude: dime cómo encontrarlo buscando «watsi» y conectarlo. En ChatGPT, dame la ruta más corta para agregar un conector personalizado con esa URL. Al conectarlo se abre el inicio de sesión de watsi. Los menús cambian seguido: si no estás seguro de un nombre, dímelo y descríbeme qué buscar en lugar de inventarlo. Si mi plan no permite conectores personalizados, avísame.
Paso 3: Cuando inicie sesión, compruébalo con las herramientas de watsi: lista las herramientas que tienes, dime cuántos contactos tengo y resume mis tres conversaciones más recientes. Si algo falla (no se abre el navegador, un error al iniciar sesión, no aparecen las herramientas, se ve otro espacio de trabajo), diagnostícalo con la documentación de arriba y arréglalo tú si puedes.
```

El servidor habla el [Model Context Protocol](https://modelcontextprotocol.io) por **Streamable HTTP** en un solo endpoint:

```http
POST https://mcp.watsi.ai/mcp
```

No hay endpoint `/sse` ni sesión que mantener viva: cada solicitud lleva su credencial. Cada herramienta es una de las [acciones de la API](/api/overview), con el mismo alcance; lo que puedes hacer por MCP también lo puedes hacer por REST.

> **Beta**

El servidor MCP está en beta: el catálogo crece y algunas herramientas pueden cambiar de forma. Los cambios que afecten a integraciones se anuncian en [Novedades](/changelog).

## Autenticación

Dos formas, y las dos resuelven a **un solo espacio de trabajo**:

- **Clave de API.** La misma clave `wats_live_…` de la API REST, como token bearer: `Authorization: Bearer wats_live_…`. Úsala en los clientes que tú configuras (Claude Desktop, Claude Code, Cursor, tus propios agentes). Se crea en [watsi.ai/workspace/settings/api-keys](https://watsi.ai/workspace/settings/api-keys) ([detalles](/guides/authentication)).
- **OAuth 2.1.** Para los clientes web que no pueden mandar un encabezado propio (Claude.ai, ChatGPT). El cliente se registra solo (registro dinámico de clientes), tú inicias sesión en watsi, eliges el espacio de trabajo y apruebas los alcances. watsi.ai es el servidor de autorización y el servidor MCP lo anuncia en `https://mcp.watsi.ai/.well-known/oauth-protected-resource`.

En la pantalla de consentimiento de OAuth, los alcances de lectura se conceden al aprobar; cada alcance de **escritura** aparece desmarcado y sólo se concede si lo marcas. Si no marcas nada, la sesión es de sólo lectura. Para agregar una escritura después, vuelve a conectar y márcala: la nueva conexión reemplaza a la anterior, así que marca todas las escrituras que quieras conservar.

Cada llamada exitosa queda registrada (qué credencial, qué herramienta, cuándo), y las llamadas tienen un límite por credencial más holgado que el de la API REST, para que un agente pueda paginar.

## Herramientas

Para ver, área por área, qué puedes hacer por MCP y con el Asistente y qué pide confirmación, ve [Qué puedes hacer](/mcp/capabilities).

Estas tablas se generan de las herramientas que el servidor registra, así que no pueden quedarse atrás. Aun así, el catálogo autoritativo es el que tu cliente recibe con `tools/list`: si el servicio detrás de una herramienta no está disponible en un entorno, el servidor la retira ahí en lugar de anunciarla y fallar.

### Lectura

| Herramienta | Alcances | Qué hace |
| --- | --- | --- |
| `resources_get` | `resources:read` | Metadatos de un archivo de la biblioteca de recursos. |
| `resources_list` | `resources:read` | Archivos de la biblioteca de recursos, paginados. |
| `list_contacts` | `contacts:read` | Contactos, los más recientes primero; busca por nombre, teléfono o correo. |
| `find_conversations` | `conversations:read` | Conversaciones con filtros (estado, asignado, etapa, fechas, sin responder) y un total. |
| `get_conversation` | `conversations:read` | Una conversación: sus mensajes más el resumen de IA. |
| `conversation_list_notes` | `conversations:read` | Las notas internas de una conversación, que sólo ve el equipo. |
| `list_quick_replies` | `conversations:read` | Tus mensajes rápidos y las acciones rápidas que ocultaste. |
| `contact_list_channels` | `contacts:read` | Lista los canales y fuentes de un contacto. |
| `pending_merge_list` | `contacts:read` | Lista los posibles contactos duplicados que esperan revisión. |
| `lifecycle_ads_list` | `lifecycle:read` | Las carpetas, imágenes y videos de la sección Ads de un cliente. |
| `lifecycle_case_file` | `lifecycle:read` + `billing:read` | El expediente de un contacto: chat, citas, facturación, llamadas previas. |
| `lifecycle_get_transcript` | `lifecycle:read` | El texto de una llamada grabada. |
| `search_messages` | `conversations:read` | Búsqueda de texto completo en el contenido de los mensajes. |
| `find_message_templates` | `templates:read` | Plantillas de mensaje de WhatsApp y su estado de aprobación. |
| `list_appointments` | `scheduling:read` | Próximas citas del calendario. |
| `workspace_overview` | `analytics:read` | Analíticas principales: volumen, tasa de respuesta de IA, tendencias. |
| `workspace_payment_history` | `billing:read` | Pagos anteriores (paquetes de créditos y facturas). |
| `workspace_billing_status` | `billing:read` | Plan, estado de la suscripción, créditos y asientos. |
| `workspace_credit_usage` | `billing:read` | Consumo de créditos en un periodo, por día. |
| `workspace_settings` | `workspace:read` | Nombre, zona horaria e integraciones activas del espacio de trabajo. |
| `list_integrations` | `integrations:read` | Canales e integraciones conectados. |
| `voice_calling_config` | `agents:read` | Configuración de llamadas telefónicas del agente. |
| `list_voice_calls` | `agents:read` | Llamadas recientes, entrantes y salientes. |
| `diagnose_phone_calling` | `agents:read` | Por qué el espacio de trabajo puede o no recibir llamadas, paso a paso. |
| `escalation_breakdown` | `analytics:read` | Escalamientos a una persona: tasa, tiempos, por tema, etapa y agente. |
| `appointment_stats` | `scheduling:read` + `workspace:read` | Tasas de confirmación, asistencia e inasistencia de citas. |
| `agent_performance_overview` | `analytics:read` | Métricas de conversaciones y respuesta por agente. |
| `profiling_report` | `analytics:read` | Cómo respondieron los contactos a un campo de perfilamiento. |
| `lead_attribution` | `analytics:read` | De dónde vinieron los leads (anuncios, enlaces, fuentes). |
| `ads_pipeline_funnel` | `analytics:read` | El embudo de anuncios de un periodo, de la impresión en Meta a la venta, paso por paso. |
| `appointment_booking_failures` | `analytics:read` | Las citas que el agente no pudo agendar por la configuración del espacio, agrupadas por motivo. |
| `meta_ads_performance` | `analytics:read` | Anuncios de Meta: gasto, clics y resultados por anuncio, y los prospectos que trajeron a Watsi. |
| `content_performance` | `analytics:read` | Publicaciones de Instagram y Facebook: vistas, alcance e interacción, contra el periodo anterior. |
| `content_audience` | `analytics:read` | Quién sigue la cuenta de Instagram y los mejores horarios para publicar. |
| `advisor_at_risk_conversations` | `analytics:read` | Conversaciones que están agotando su tiempo de respuesta ahora mismo. |
| `prepare_analytics_export` | `analytics:read` | Un enlace de 15 minutos al CSV de conversaciones, publicaciones o anuncios de Meta que exporta el tablero. |
| `funnel_conversion` | `analytics:read` | El embudo de conversión de la página Embudo en un periodo: conversaciones, contactos perfilados, citas y asistencias. |
| `list_leads` | `leads:read` | La bandeja de leads: los formularios y las personas que captaron. |
| `refresh_leads` | `leads:read` | Pedirle a Meta los leads nuevos (una vez por minuto) y después la bandeja. |
| `list_workspace_members` | `workspace:read` | Miembros del equipo e invitaciones pendientes. |
| `list_agents` | `agents:read` | Los agentes de IA del espacio de trabajo. |
| `get_agent_config` | `agents:read` | La configuración completa de un agente. |
| `list_calendar_blocks` | `scheduling:read` | Bloqueos de calendario: tiempo en que un asesor, un tipo o el espacio no se agenda. |
| `list_appointment_types` | `scheduling:read` | Tipos de cita: duración, si están activos, página pública de reserva. |
| `get_appointment_type_schedule` | `scheduling:read` | El equipo, los descansos y el horario semanal de un tipo de cita. |
| `list_campaigns` | `campaigns:read` | Campañas de WhatsApp con su estado y sus números, como las muestra la página Campañas. |
| `get_campaign` | `campaigns:read` | Una campaña: plantilla, número que envía, programación, horario, números y costo estimado. |
| `list_campaign_recipients` | `campaigns:read` | A quién llegó una campaña y qué pasó con cada mensaje. |
| `list_tickets` | `tickets:read` | Los tickets de soporte que puedes ver, los más urgentes primero, con sus conteos. |
| `get_ticket` | `tickets:read` | Un ticket: sus campos, el contacto, quién lo atiende y toda su historia. |
| `list_ticket_types` | `tickets:read` | Los tipos de ticket, con los campos que pide cada uno. |
| `list_agent_versions` | `agents:read` | Las versiones guardadas de un agente, y cuál sirve cada canal. |
| `list_google_ads_conversion_actions` | `integrations:read` | Las conversiones de Google Ads registradas y qué etapas del embudo reporta cada una. |
| `list_learned_answers` | `agents:read` | Las respuestas aprendidas de un agente: las sugeridas de las respuestas del equipo y las guardadas. |
| `find_similar_learned_answer` | `agents:read` | La respuesta aprendida guardada más parecida a una sugerencia, para actualizarla en vez de agregar otra. |
| `list_spaces` | `scheduling:read` | Las salas, oficinas o unidades donde se agendan citas. |
| `list_space_blocks` | `scheduling:read` | El tiempo en que un espacio no se puede agendar. |
| `list_comment_automations` | `integrations:read` | Automatizaciones de comentarios: las reglas que contestan comentarios de Instagram y Facebook. |
| `list_comment_automation_activity` | `integrations:read` | Qué hizo cada automatización con cada comentario. |
| `list_operator_commands` | `workspace:read` | Tus comandos del menú ⌘K y los comandos que un comando puede repetir. |
| `list_quotes` | `quotes:read` | Cotizaciones, filtradas por estado, contacto, unidad, desarrollo o asesor. |
| `get_quote` | `quotes:read` | Una cotización: totales, calendario de pagos, unidad, estado y link del cliente. |
| `list_quotable_properties` | `quotes:read` | Unidades disponibles para cotizar, con desarrollo y precio. |
| `get_quoting_setup` | `quotes:read` | Esquemas de venta y sus reglas, formas de pago y lo que falta configurar. |
| `search_meetings` | `meetings:read` | Videollamadas pasadas por lo dicho, contacto, fecha, asesor o resultado. |
| `get_meeting` | `meetings:read` | Una videollamada: contacto, asesor, duración, estado y quién habló. |
| `get_meeting_summary` | `meetings:read` | El resumen con IA de una videollamada: puntos y próximos pasos. |
| `get_meeting_transcript` | `meetings:read` | La transcripción de una videollamada en Markdown. |
| `list_upcoming_meetings` | `meetings:read` | Las próximas citas y si el asistente entrará a cada una. |
| `get_meeting_assistant_settings` | `meetings:read` | A qué citas entra el asistente en todo el espacio. |
| `list_voice_catalog` | `agents:read` | Las voces que puede usar el agente telefónico y cuál usa hoy. |
| `get_quote_pdf_link` | `quotes:read` | Un link de 15 minutos al PDF de una cotización. |
| `list_contract_templates` | `quotes:read` | Las plantillas de contrato y las variables que pide cada una. |
| `get_quote_contract` | `quotes:read` | El contrato de una cotización tuya: estado, plantilla, valores y lo que falta. |
| `conversations_report` | `analytics:read` | De qué te escriben, por tema, en un rango de fechas. |
| `broadcast_status` | `analytics:read` | Cómo salió un envío masivo: aceptados, entregados, leídos y bloqueados por Meta. |
| `activation_progress` | `workspace:read` | En qué paso de /configuration y /onboarding va el espacio de trabajo. |
| `notification_settings` | `workspace:read` | Los avisos del espacio de trabajo y tus propias preferencias. |

### Escritura

Cada una exige un alcance `:write` explícito y se anuncia al cliente como mutación (`readOnlyHint: false`, y `destructiveHint` cuando reemplaza o borra), para que te pregunte antes de llamarla. La primera llamada de una acción en dos pasos, la que sólo responde una vista previa y un `confirmToken`, no cambia nada y se anuncia como lectura (`readOnlyHint: true`). `openWorldHint` es `true` en las herramientas que salen de tu espacio de trabajo: una URL que tú das, un envío a un cliente, una página pública u otro sistema, como Meta, Google Ads o Google Meet.

| Herramienta | Alcances | Qué hace |
| --- | --- | --- |
| `conversation_set_status` | `conversations:write` | Pone o quita el estado propio del espacio de trabajo a un chat. |
| `conversation_assign` | `conversations:write` | Asigna una conversación a un miembro, por nombre, correo o id. |
| `conversation_unassign` | `conversations:write` | Deja una conversación sin responsable, con un motivo opcional. |
| `conversation_resolve` | `conversations:write` | Marca una conversación como resuelta. |
| `conversation_reopen` | `conversations:write` | Reabre una conversación resuelta, cancelada o escalada. |
| `conversation_escalate` | `conversations:write` | Escala una conversación al equipo, con un motivo. |
| `conversation_set_agent` | `conversations:write` | Pausa el agente de IA en una conversación por un tiempo, o lo reanuda. |
| `conversation_set_agent_enabled` | `conversations:write` | Prende o apaga el agente de IA en una conversación de forma permanente, no como pausa. |
| `conversation_set_active_agent` | `conversations:write` | Elige qué agente le contesta al cliente de una conversación desde su siguiente mensaje. |
| `conversation_mark_read` | `conversations:write` | Marca una conversación como leída o no leída. |
| `conversation_set_observers` | `conversations:write` | Agrega o quita miembros que observan al contacto de una conversación. |
| `conversation_add_note` | `conversations:write` | Agrega una nota interna a una conversación. |
| `conversation_edit_note` | `conversations:write` | Cambia el texto de una nota interna. |
| `conversation_delete_note` | `conversations:write` | Borra una nota interna (pide `note:delete`). |
| `quick_reply_create` | `conversations:write` | Guarda un mensaje rápido para tu caja de texto. |
| `quick_reply_set_hidden` | `conversations:write` | Oculta una acción rápida de tu caja de texto, o la vuelve a mostrar. |
| `chat_status_create` | `conversations:write` | Crea un estado propio para las conversaciones del espacio de trabajo. |
| `chat_status_update` | `conversations:write` | Renombra un estado propio o le cambia el emoji. |
| `chat_status_reorder` | `conversations:write` | Cambia el orden de los estados de las conversaciones. |
| `contact_set_blocked` | `conversations:write` | Bloquea o desbloquea un contacto: el agente deja de contestarle. |
| `contact_update` | `contacts:write` | Edita un contacto: nombre, teléfono, correo, relación, calidad del lead, estado y observadores. |
| `contact_assign_advisor` | `contacts:write` | Pone o quita el asesor de un contacto. Al asesor nuevo se le avisa. |
| `crm_edit_note` | `crm:write` | Edita el texto de una nota en el perfil de un contacto. |
| `contact_add_channel` | `contacts:write` | Agrega un canal o fuente a un contacto. Un canal que ya es de otro contacto se rechaza. |
| `contact_remove_channel` | `contacts:write` | Quita un canal de un contacto. |
| `pending_merge_reject` | `contacts:write` | Rechaza un posible duplicado: los dos contactos siguen separados. |
| `crm_update_task` | `crm:write` | Edita, completa, reabre o reasigna una de tus tareas de seguimiento. |
| `attachment_create_upload` | `agents:write` | Da una URL firmada de corta duración para subir un archivo. |
| `attachment_finalize` | `agents:write` | Adjunta un archivo subido a Recursos, a una propiedad o al conocimiento. |
| `attachment_import_url` | `agents:write` | Descarga un enlace público https:// y lo adjunta en una sola llamada. |
| `lifecycle_ads_create_folder` | `lifecycle:write` | Crea una carpeta en la sección Ads de un cliente. Se puede repetir. |
| `lifecycle_ads_create_upload` | `lifecycle:write` | Da una URL firmada para subir una imagen o video. Se puede repetir. |
| `lifecycle_ads_finalize_upload` | `lifecycle:write` | Revisa un anuncio subido y lo hace visible en la sección Ads. |
| `lifecycle_ads_import_url` | `lifecycle:write` | Copia una imagen o video de un enlace público https:// a una carpeta. |
| `lifecycle_ads_move` | `lifecycle:write` | Mueve anuncios a otra carpeta, p. ej. los aprobados de Borradores a Aprobados. |
| `lifecycle_ads_copy` | `lifecycle:write` | Copia anuncios a otra carpeta sin quitar los originales. Se puede repetir. |
| `lifecycle_ads_reorder` | `lifecycle:write` | Fija el orden manual de los anuncios de una carpeta. |
| `lifecycle_ads_update_item` | `lifecycle:write` | Anota qué skill hizo un anuncio, su versión, de cuál deriva y notas. |
| `lifecycle_attach_file` | `lifecycle:write` | Da una URL firmada para adjuntar un archivo al expediente de un contacto. |
| `lifecycle_record_call` | `lifecycle:write` | Registra lo que concluyó una llamada en su transcripción. |
| `lifecycle_set_step` | `lifecycle:write` | Mueve a un paso la línea de tiempo de un espacio de trabajo vinculado. |
| `update_voice_calling_config` | `agents:write` | Cambia la configuración de llamadas telefónicas. |
| `create_agent` | `agents:write` | Crea un agente de IA. |
| `update_agent_config` | `agents:write` | Cambia la configuración de un agente. |
| `add_agent_knowledge` | `knowledge:write` | Agrega un documento a la base de conocimiento de un agente. |
| `delete_agent_knowledge` | `knowledge:write` | Elimina un documento de la base de conocimiento de un agente. |
| `set_assignment_policy` | `agents:write` | Define cómo se asignan las conversaciones al equipo. |
| `set_member_schedules` | `scheduling:write` | Define el horario de trabajo de los miembros para la agenda. |
| `book_appointment` | `scheduling:write` | Prepara una cita: vista previa y confirmToken. Al confirmar se le avisa al cliente. |
| `reschedule_appointment` | `scheduling:write` | Prepara mover una cita a otra hora; confirm_action la ejecuta. |
| `cancel_appointment` | `scheduling:write` | Prepara cancelar una cita; confirm_action la ejecuta. |
| `update_appointment` | `scheduling:write` | Prepara editar el correo, las notas o el nombre de una cita; confirm_action la ejecuta. |
| `accept_appointment_request` | `scheduling:write` | Prepara confirmar una solicitud de cita pendiente; confirm_action la ejecuta. |
| `decline_appointment_request` | `scheduling:write` | Prepara rechazar una solicitud de cita con un motivo; confirm_action la ejecuta. |
| `create_calendar_block` | `scheduling:write` | Bloquea tiempo del calendario, una vez o recurrente; no se avisa a nadie. |
| `update_calendar_block` | `scheduling:write` | Cambia o pausa un bloqueo de calendario. |
| `delete_calendar_block` | `scheduling:write` | Quita un bloqueo de calendario para que su tiempo vuelva a agendarse. |
| `add_appointment_type_member` | `scheduling:write` | Agrega a una persona al equipo de un tipo de cita. |
| `remove_appointment_type_member` | `scheduling:write` | Quita a una persona del equipo de un tipo de cita. |
| `create_appointment_type_break` | `scheduling:write` | Agrega un descanso semanal a un tipo de cita. |
| `update_appointment_type_break` | `scheduling:write` | Cambia o pausa un descanso de un tipo de cita. |
| `delete_appointment_type_break` | `scheduling:write` | Quita un descanso de un tipo de cita. |
| `set_appointment_type_weekly_rules` | `scheduling:write` | Reemplaza el horario semanal de un tipo de cita. |
| `create_campaign_draft` | `broadcast:write` | Guarda un borrador de campaña: plantilla, número que envía, regla de audiencia; no envía nada. |
| `update_campaign_draft` | `broadcast:write` | Edita un borrador de campaña; no envía nada. |
| `pause_campaign` | `broadcast:write` | Pausa una campaña en curso; reanudarla se hace en la app. |
| `create_ticket` | `tickets:write` | Abre un ticket para un contacto, por tipo. |
| `claim_ticket` | `tickets:write` | Empieza a atender un ticket. |
| `add_ticket_note` | `tickets:write` | Deja un comentario del equipo en un ticket. |
| `prepare_ticket_update` | `tickets:write` | Previsualiza un cambio a un ticket (estado, prioridad, quién lo atiende) y da un token para confirmarlo. |
| `create_ticket_type` | `tickets:write` | Agrega un tipo de ticket, con los campos y motivos de cierre que pide. |
| `update_ticket_type` | `tickets:write` | Cambia los campos, el responsable, el SLA o si está activo un tipo de ticket. |
| `rename_agent_version` | `agents:write` | Cambia el título de una versión guardada de un agente. |
| `restore_agent_version` | `agents:write` | Regresa el borrador de un agente a una versión guardada. |
| `publish_agent_version` | `agents:write` | Publica una versión guardada en un canal donde el agente ya está. |
| `test_agent` | `agents:write` | Manda un mensaje de prueba a un agente y lee su respuesta; no le llega a ningún cliente. |
| `generate_product_faqs` | `agents:write` | Genera las preguntas frecuentes de una propiedad con sus datos; se publican en su página pública y el agente las usa. |
| `set_stage_google_ads_conversion` | `agents:write` | Elige la conversión de Google Ads que reporta una etapa del embudo al entrar, o la quita. |
| `crawl_agent_website` | `knowledge:write` | Lee una página web pública y la agrega a la base de conocimiento de un agente. |
| `retrain_agent_knowledge` | `knowledge:write` | Vuelve a procesar documentos de la base de conocimiento de un agente. |
| `import_agent_qa_pairs` | `knowledge:write` | Agrega pares de pregunta y respuesta a la base de conocimiento de un agente, como un documento. |
| `save_learned_answer` | `knowledge:write` | Guarda una respuesta aprendida sugerida, corregida si hace falta; el agente la usa al procesarse. |
| `dismiss_learned_answer` | `knowledge:write` | Descarta una respuesta aprendida sugerida; el agente nunca la aprende. |
| `create_learned_answer` | `knowledge:write` | Le enseña a un agente un par de pregunta y respuesta directamente. |
| `edit_learned_answer` | `knowledge:write` | Corrige una respuesta aprendida guardada; la anterior responde hasta que la nueva se procese. |
| `delete_learned_answer` | `knowledge:write` | Borra una respuesta aprendida guardada; el agente deja de usarla. |
| `create_appointment_type` | `scheduling:write` | Crea un tipo de cita: duración, anticipación, confirmación, agente. |
| `update_appointment_type` | `scheduling:write` | Cambia un tipo de cita, o deja de ofrecerlo. |
| `mark_appointment_attendance` | `scheduling:write` | Marca si el cliente asistió a una cita que ya terminó, con los mismos seguimientos que en la app. |
| `mark_appointment_sale` | `scheduling:write` | Registra si una cita que ya terminó acabó en venta. |
| `create_space` | `scheduling:write` | Crea un espacio donde se pueden agendar citas. |
| `update_space` | `scheduling:write` | Cambia un espacio, o los asesores a los que van sus chats. |
| `create_space_block` | `scheduling:write` | Bloquea un espacio para un tipo de cita o para todos. |
| `update_space_block` | `scheduling:write` | Cambia un bloqueo de un espacio. |
| `delete_space_block` | `scheduling:write` | Quita un bloqueo de un espacio, para que vuelva a agendarse. |
| `create_comment_automation` | `automations:write` | Crea una automatización de comentarios, siempre como borrador. |
| `update_comment_automation` | `automations:write` | Edita una automatización en borrador o pausada. |
| `pause_comment_automation` | `automations:write` | Pausa una automatización activa. |
| `duplicate_comment_automation` | `automations:write` | Copia una automatización como borrador nuevo. |
| `update_notification_matrix` | `notifications:write` | Cambia qué avisos reciben los administradores y los miembros, por correo y push. |
| `create_operator_command` | `commands:write` | Guarda un comando del menú ⌘K para ti. |
| `update_operator_command` | `commands:write` | Renombra, reasigna o vuelve a grabar uno de tus comandos. |
| `delete_operator_command` | `commands:write` | Borra uno de tus comandos. |
| `prepare_set_workspace_timezone` | `workspace:write` | Prepara cambiar la zona horaria del espacio; confirm_action hace el cambio. |
| `prepare_company_logo_upload` | `workspace:write` | Pide una URL firmada para subir un logo nuevo. |
| `set_company_logo` | `workspace:write` | Pone la imagen subida como logo del espacio. |
| `revoke_member_invite` | `members:write` | Cancela una invitación pendiente; no se le avisa a nadie. |
| `prepare_comment_automation_activation` | `automations:write` | Prepara activar una automatización; confirm_action la enciende. |
| `set_meeting_assistant` | `meetings:write` | Enciende o apaga el asistente en una cita. |
| `update_meeting_assistant_settings` | `meetings:write` | Define a qué citas entra el asistente. |
| `create_quote_draft` | `quotes:write` | Crea una cotización en borrador para una unidad, con las reglas del esquema. |
| `update_quote_draft` | `quotes:write` | Cambia un borrador: contacto, esquema, descuento, vigencia o nota. |
| `send_quote` | `quote_sends:write` | Muestra lo que se enviaría y da un confirmToken. No envía nada. |
| `confirm_quote_send` | `quote_sends:write` | Envía la cotización cuando la persona confirmó la vista previa. |
| `confirm_action` | `agents:write` + `automations:write` + `broadcast:write` + `members:write` + `messages:write` + `quote_sends:write` + `quotes:write` + `scheduling:write` + `templates:write` + `tickets:write` + `workspace:write` | Ejecuta una escritura preparada con su confirmToken, ya confirmada. Pide el alcance de la acción del token. |
| `prepare_message_template_submission` | `templates:write` | Revisa el borrador de una plantilla de WhatsApp y da un confirmToken para enviarla a Meta. |
| `prepare_template_broadcast` | `broadcast:write` | Muestra el envío de una plantilla aprobada a un grupo de contactos. No envía nada. |
| `cancel_template_broadcast` | `broadcast:write` | Detiene una difusión; lo ya entregado no se recupera. |
| `prepare_member_invite` | `members:write` | Muestra la invitación a un compañero por correo. No invita a nadie. |
| `prepare_phone_number_request` | `agents:write` | Muestra la solicitud de un número a watsi. No registra nada. |
| `create_contact` | `contacts:write` | Crea un contacto, o actualiza el que tiene ese teléfono, wa_id o correo. |
| `crm_tag_customer` | `crm:write` | Agrega una etiqueta a un contacto. Apagada por omisión en cada espacio. |
| `crm_untag_customer` | `crm:write` | Quita una etiqueta de un contacto. Apagada por omisión en cada espacio. |
| `crm_create_note` | `crm:write` | Agrega una nota a un contacto. Apagada por omisión en cada espacio. |
| `crm_create_task` | `crm:write` | Crea una tarea de seguimiento de un contacto. Apagada por omisión en cada espacio. |
| `crm_update_funnel_stage` | `crm:write` | Mueve una conversación de etapa del embudo. Apagada por omisión en cada espacio. |
| `set_quote_status` | `quotes:write` | Cancela una cotización en borrador o enviada. |
| `duplicate_quote` | `quotes:write` | Copia una cotización como borrador tuyo, como «Duplicar». |
| `create_quote_contract` | `quotes:write` | Crea el contrato en borrador de una cotización tuya ya enviada. |
| `update_quote_contract` | `quotes:write` | Elige la plantilla de un contrato en borrador y llena sus variables. |
| `create_quote_scheme` | `quotes:write` | Crea un esquema de venta: plan de pagos, descuento máximo, precio mínimo e impuestos. |
| `update_quote_scheme` | `quotes:write` | Cambia un esquema de venta; cada cotización nueva usa el cambio. |
| `update_quote_payment_method` | `quotes:write` | Cambia la etiqueta de un método de pago o si se ofrece. |
| `prepare_inventory_unit_update` | `quotes:write` | Prepara cambiar el precio o el estado de una unidad (llega al agente); confirm_action lo aplica. |
| `prepare_quote_contract_send` | `quote_sends:write` | Prepara enviarle un contrato al cliente; confirm_action lo envía. |
| `conversation_reply` | `messages:write` | Muestra la respuesta al cliente de una conversación, dentro de su ventana. No envía nada. |
| `conversation_send_template` | `messages:write` | Muestra el envío de una plantilla aprobada en una conversación. No envía nada. |
| `conversation_react` | `messages:write` | Muestra la reacción con un emoji a un mensaje, o quitarla. No envía nada. |
| `conversation_forward` | `messages:write` | Muestra el reenvío de un mensaje a otras conversaciones. No envía nada. |
| `start_conversation` | `broadcast:write` | Muestra abrir una conversación de WhatsApp con un número o un contacto por plantilla. No envía nada. |

> **Escrituras que reescriben tu agente**

Los alcances `agents:write`, `knowledge:write` y `scheduling:write` reescriben la configuración de tus agentes y pueden publicarla en tus canales conectados, así que son opcionales en los dos caminos: los marcas al crear la clave en **Configuración › Desarrollador**, o en la pantalla de consentimiento de una conexión OAuth. Nunca se otorgan por omisión.

Las herramientas `lifecycle_*` son la excepción: sirven al proceso interno de acompañamiento de clientes de watsi, su alcance `lifecycle:write` sólo lo emite el equipo de watsi, y una conexión por OAuth —como Claude o ChatGPT— no las lista ni puede llamarlas. No las necesitas para tu integración.

Una conexión por OAuth tampoco tiene las herramientas de facturación (`workspace_billing_status`, `workspace_credit_usage`, `workspace_payment_history`), el envío de cotizaciones y contratos (`send_quote`, `confirm_quote_send`, `prepare_quote_contract_send`), `update_quote_payment_method` ni `prepare_phone_number_request`, y no se le ofrecen los alcances `billing:read` y `quote_sends:write`: los directorios de conectores no admiten herramientas de cobro o de venta. Con una clave de API siguen disponibles, por MCP y por REST.

### Contactos y CRM

`create_contact` crea un contacto, o actualiza el que ya tiene ese teléfono, `wa_id` o correo (alcance `contacts:write`). `crm_tag_customer`, `crm_untag_customer`, `crm_create_note`, `crm_create_task` y `crm_update_funnel_stage` etiquetan, agregan notas y tareas de seguimiento y mueven la etapa del embudo de una conversación (alcance `crm:write`). Los dos alcances son casillas opcionales en la pantalla de consentimiento de OAuth y en **Configuración › Desarrollador**.

> **Apagadas por omisión**

Las cinco escrituras de CRM están **apagadas por omisión en cada espacio de trabajo**, y todavía no se encienden desde la app: para usarlas, escríbele al soporte de watsi. Mientras estén apagadas, la llamada responde `403` con el código `CRM_WRITE_DISABLED` y no escribe nada.

Una tarea se crea a nombre del miembro detrás de la credencial.

`set_quote_status` cancela una cotización en borrador o enviada; no llega al cliente.

### Reportes y estado del espacio de trabajo

- `conversations_report`: de qué te escriben, por tema, en un rango de fechas. El porcentaje de cada tema es sobre las conversaciones ya clasificadas, no sobre el total.
- `broadcast_status`: cómo salió un envío masivo: aceptados, entregados, leídos y los bloqueados por código de Meta (por ejemplo 131049, el límite de mensajes de marketing por persona).
- `activation_progress`: en qué paso de `/configuration` y de `/onboarding` está el espacio de trabajo.
- `notification_settings`: los avisos que tiene configurados el espacio de trabajo y las preferencias propias del miembro detrás de la credencial.

### Adjuntar archivos

Tres de las herramientas de escritura suben un archivo a tu espacio de trabajo: a **Recursos** (lo que el agente envía a tus clientes), a las **fotos, el plano o el brochure de una propiedad**, o a la **base de conocimiento**. Exigen `agents:write`, y un documento de conocimiento además `knowledge:write`.

- **Si tu cliente puede hacer peticiones HTTP** (Claude Code, un script): `attachment_create_upload` devuelve una URL firmada de corta duración, envías el archivo con un `PUT` y luego `attachment_finalize` lo adjunta.
- **Si no puede** (un chat como Claude.ai o ChatGPT): `attachment_import_url` descarga un enlace público `https://` y lo adjunta en una sola llamada. Las direcciones privadas o locales se rechazan (`ATTACHMENT_URL_NOT_ALLOWED`).

El servidor revisa el tipo y el tamaño del archivo que realmente se guardó: PDF, imágenes, audio y MP4 para Recursos (hasta 20 MB); PNG, JPEG, WebP o GIF para las fotos y el plano (hasta 5 MB, máximo 20 fotos por propiedad); PDF para el brochure; PDF, DOCX, TXT, MD o CSV para el conocimiento (hasta 10 MB).

### Cotizaciones

`create_quote_draft` y `update_quote_draft` arman y cambian borradores con las reglas del esquema de venta; nada llega al cliente. Enviar es en **dos pasos**: `send_quote` responde la vista previa y un `confirmToken`, y sólo `confirm_quote_send` envía, cuando la persona confirmó. El token es de la misma persona, dura 10 minutos y deja de servir si la cotización cambia. Detalles en [Cotizaciones por API y MCP](/guides/quotes-api).

`duplicate_quote` copia una cotización que puedes ver como un borrador nuevo tuyo, con las mismas reglas del esquema: si el original pasa del descuento máximo o queda bajo el precio mínimo, se rechaza y no se guarda nada. `get_quote_pdf_link` devuelve un link al PDF que sirve 15 minutos y abre también los borradores; quien tenga el link puede abrirlo en ese tiempo, así que no lo compartas fuera del equipo (al cliente se le manda con `send_quote`). Las dos piden un miembro detrás de la credencial.

**Contratos.** `get_quote_contract` lee el contrato de una cotización tuya y `list_contract_templates` las plantillas con sus variables; `create_quote_contract` lo crea en borrador (sólo para una cotización ya enviada, aceptada, apartada o cerrada) y `update_quote_contract` elige la plantilla y llena las variables mientras sea borrador. Enviarlo es en **dos pasos**: `prepare_quote_contract_send` responde la vista previa (a dónde va, la plantilla) y un `confirmToken`, y `confirm_action` lo envía en PDF por correo o WhatsApp, una sola vez. Se rechaza mientras falte una variable obligatoria. Sólo el asesor de la cotización lo lee, lo llena o lo envía. El envío (`prepare_quote_contract_send` y su confirmación) llega a esta conexión cuando se habilite en el servidor; hasta entonces no aparece en `tools/list`, y leer y llenar el contrato ya funcionan.

**Configuración del cotizador.** `create_quote_scheme` y `update_quote_scheme` crean y cambian un esquema de venta (su plan de pagos, el descuento máximo, el precio mínimo por m², los impuestos, la moneda, a qué desarrollo aplica y si es el predeterminado), y `update_quote_payment_method` cambia la etiqueta de un método de pago o si se ofrece: cambian lo que ofrece **cada cotización que se escriba después**, sin enviarle nada a nadie, y las ya enviadas conservan lo que llevaban. Cambiar una unidad sí llega a los clientes, así que va en **dos pasos**: `prepare_inventory_unit_update` responde una vista previa y un `confirmToken`, y `confirm_action` cambia el precio, la moneda o el estado de la unidad una sola vez. El agente cotiza el precio nuevo desde su siguiente respuesta, una unidad que deja de estar disponible sale de su página pública y de sus anuncios, y marcarla `available` libera el apartado (se rechaza mientras la aparte una cotización ya enviada, `UNIT_RESERVED_BY_SENT_QUOTE`). Los datos bancarios de un método de pago no se cambian por MCP: son la cuenta a la que cada cotización le pide pagar al cliente, y se cambian en Cotizador → Configuración. Toman los ids de `get_quoting_setup` y `list_quotable_properties` (una unidad también por su código). Piden `quotes:write` y un miembro con el permiso de administrar el cotizador (o, para un método de pago, el de administrar métodos de pago). El precio de una unidad se cambia en la unidad: el del catálogo se calcula de sus unidades.

**`confirm_action` canjea cualquier `confirmToken`.** Las acciones que llegan a un cliente se hacen en dos pasos: la primera llamada sólo responde una vista previa y un `confirmToken`. `confirm_action` recibe ese token y ejecuta la escritura que preparó, sin importar cuál fue; canjea los de `send_quote`, los de `prepare_quote_contract_send` (el contrato de una cotización), los de las cuatro acciones de citas (abajo) y los de las cuatro de [Plantillas, difusiones, invitaciones y números en dos pasos](/guides/two-step-actions), y `confirm_quote_send` sigue funcionando igual. Necesitas el alcance de la acción del token: `quote_sends:write` para una cotización, `scheduling:write` para una cita, y `templates:write`, `broadcast:write`, `members:write` o `agents:write` para las demás. Una conexión que no tiene ninguno de esos alcances no ve la herramienta. Lo que se ejecuta viaja en el token (la acción, el registro y sus datos), así que esta llamada no puede cambiarlo. Se rechaza si el token venció, es de otra persona o de otro espacio de trabajo, el registro cambió desde la vista previa, o no es de una acción que se pueda confirmar (`ACTION_CONFIRMATION_UNSUPPORTED`). Cada acción conserva sus propios códigos de error, por ejemplo `QUOTE_SEND_CONFIRMATION_STALE`.

### Citas

Agendar, mover, cancelar o editar una cita le avisa al cliente, así que también son en **dos pasos**. `book_appointment`, `reschedule_appointment`, `cancel_appointment` y `update_appointment` no cambian nada: revisan la petición y responden una vista previa (la hora en UTC y en la zona de tu espacio de trabajo, la persona y la conversación) más un `confirmToken`. `confirm_action` con ese token hace el cambio. Por REST, cada una se confirma en su propia ruta `…/confirm`.

- **La hora.** Manda la hora UTC (`startAt`, `newStartAt`) o la hora local sin zona (`startAtLocal`, `newStartAtLocal`) junto con `timezone`; nunca las dos. Sin fin, una cita nueva dura lo que su tipo de cita, y una que se mueve conserva su duración. Una hora en el pasado se rechaza (`SLOT_IN_PAST`), y si tu espacio de trabajo no tiene zona horaria configurada tienes que mandar `timezone` (`TIMEZONE_REQUIRED`).
- **La cita.** `bookingId` es un id de `list_appointments`. `conversationId` liga una cita nueva a una conversación de tu espacio de trabajo; una conversación de otro espacio de trabajo se rechaza (`CONVERSATION_NOT_IN_WORKSPACE`), y un `appointmentTypeId` de otro espacio de trabajo también (`APPOINTMENT_TYPE_NOT_FOUND`). Con `replaceExistingAppointments`, la vista previa dice qué cita se reemplaza (`replacesBookingId`) y la confirmación reemplaza esa y ninguna otra: si el contacto ya tiene otra cita activa, se rechaza (`REPLACEMENT_TARGET_CHANGED`).
- **Quién puede.** Hace falta `scheduling:write`. Un miembro sin el permiso «cambiar cualquier cita» sólo mueve, cancela o edita las citas asignadas a él, y agenda para sí mismo; una cita de otra persona responde `APPOINTMENT_NOT_FOUND`, y no puede reemplazarla con `replaceExistingAppointments` (`APPOINTMENT_REPLACE_FORBIDDEN`). Las citas se cambian a nombre de un miembro: una llave de API sin miembro se rechaza (`MEMBER_REQUIRED`). Una cita nueva respeta el horario de su tipo de cita: una hora fuera de él se agenda desde Calendario.
- **El asesor.** Toda cita nueva queda en el calendario de alguien, y la vista previa dice de quién (`advisor`). En un tipo de cita, un miembro con «cambiar cualquier cita» recibe al asesor que el equipo del tipo asigna a esa hora, como en las citas que agenda el agente (`NO_MEMBER_AVAILABLE` si nadie del equipo puede); sin ese permiso, la cita es para quien la agenda. La confirmación la agenda para ese asesor, y si ya no puede a esa hora responde `ADVISOR_UNAVAILABLE`. Una hora que el tipo de cita no ofrece se rechaza ya en la vista previa (`SCHEDULE_VIOLATION`), tanto al agendar como al mover.
- **Solicitudes pendientes.** Una cita que espera la aprobación del equipo (`pending_confirmation`) se confirma con `accept_appointment_request` o se rechaza con `decline_appointment_request` (con un `reason`), también en dos pasos. No le mandan nada al cliente: disparan el webhook `appointment.updated` a tus integraciones, y un rechazo no se puede deshacer. Una cita que ya no está pendiente responde `APPOINTMENT_NOT_PENDING`.
- **Asistencia.** `mark_appointment_attendance` (`scheduling:write`) marca si el cliente asistió a una cita que ya terminó: `attended: true`, `false` (no llegó) o `null` (quitar la marca). Va en un paso y tiene los mismos efectos que marcarla en la tarjeta del chat: la tarjeta se reescribe, la secuencia post-venta se programa o se cancela y, donde el espacio de trabajo usa el día del asesor o «Citas sin faltas», un «no llegó» programa el mensaje al cliente para reagendar 30 minutos después (corregir la marca en ese tiempo lo cancela). Una cita que todavía no termina responde `APPOINTMENT_NOT_ENDED` (400) y una que el miembro no puede ver, `APPOINTMENT_NOT_FOUND`. La marca queda a nombre de un miembro: una llave de API sin miembro detrás responde `MEMBER_REQUIRED`.
- **Bloqueos de calendario.** `create_calendar_block`, `update_calendar_block` y `delete_calendar_block` cierran tiempo para que nada se agende en él (ids de `list_calendar_blocks`). No le avisan a nadie, así que van en un paso. Un bloqueo nombra a un asesor (`userId`), un tipo de cita (`appointmentTypeId`) o, sin ninguno, todo el espacio de trabajo, lo que pide el permiso «bloquear el calendario del espacio»; un miembro que sólo ve su calendario bloquea sólo a sí mismo o a sus tipos. Uno recurrente lleva `startTime`/`endTime` leídos en su `timezone`.
- **Campañas.** `list_campaigns`, `get_campaign` y `list_campaign_recipients` leen las campañas de WhatsApp con `campaigns:read` (un alcance opcional: hay que marcarlo al crear la clave o al conectar): su estado, sus números, su costo estimado y a quién llegó cada envío. `sent` es lo que Meta aceptó, no lo que se entregó. Una campaña de otro espacio de trabajo responde `NOT_FOUND`, y una llave de API sin miembro se rechaza (`MEMBER_REQUIRED`). Con `broadcast:write`, `create_campaign_draft` y `update_campaign_draft` guardan y editan un borrador (no envía nada; la audiencia es una regla, nunca ids de contactos) y `pause_campaign` detiene una campaña en curso. Lanzarla y reanudarla se hacen en la app.
- **Anuncios, contenido y conversaciones en riesgo.** `meta_ads_performance` lee el panel de anuncios de Meta (gasto, clics, resultados por anuncio y, con `includeProspects`, los prospectos, ingresos y ROI que cada anuncio trajo); `content_performance` y `content_audience` leen la analítica de las publicaciones de Instagram y Facebook y quién sigue la cuenta; `advisor_at_risk_conversations` lista las conversaciones asignadas que están agotando su tiempo de respuesta (sin reasignación por SLA, contra el SLA de referencia). Sin `includeProspects`, `attributionAvailable` es `null`. Piden `analytics:read` y una credencial con un miembro detrás (`MEMBER_REQUIRED` sin él), y respetan los permisos de ese miembro: los anuncios y el contenido piden además la función de Meta marketing del espacio de trabajo, y un miembro que sólo ve sus conversaciones recibe sólo las suyas. Se leen de lo que la sincronización diaria guarda (`lastSyncedAt` dice de cuándo es).
- **Embudo de conversión.** `funnel_conversion` (`analytics:read`) da el embudo de un periodo con los mismos números que la página Embudo, porque los calcula la misma función: cuántas conversaciones entraron, cuántos contactos quedaron perfilados, cuántos agendaron y cuántos asistieron, con la conversión y lo que se pierde en cada paso, más las inasistencias, las etapas del embudo del espacio de trabajo, los agentes con más conversaciones y los motivos de descarte. `range` acepta `1d`, `7d`, `30d` o `90d`; para un periodo con nombre manda `from` y `to`, y el periodo usado vuelve en `period`. `entered` cuenta conversaciones y los demás pasos cuentan contactos. Se lee con lo que ve el miembro detrás de la credencial (`MEMBER_REQUIRED` sin él).
- **Exportar a CSV.** `prepare_analytics_export` responde un enlace para descargar en CSV una tabla del tablero (`dataset`: `conversations`, `content_posts` o `meta_ads`), el mismo archivo que da el botón «Exportar». No devuelve las filas: el enlace abre durante 15 minutos, sólo para el miembro que lo pidió, y al abrirlo se vuelven a comprobar su acceso y sus permisos; cada descarga queda registrada (qué tabla y cuántas filas, nunca su contenido). Un archivo tiene como máximo 5 000 filas (`maxRows`); si hay más, su nombre termina en `max5000` y la cabecera `X-Export-Truncated` es `true`. Pide `analytics:read` y un miembro detrás de la credencial; `conversations` es un archivo de contactos (nombre, teléfono y el resumen de IA de cada conversación), así que pide además `contacts:read`. La bandeja de leads no se exporta.
- **Leads.** `list_leads` lee la bandeja de leads: los formularios del espacio de trabajo (Meta, TikTok, Google y sus formularios web) y las personas que captaron, con su teléfono, correo y respuestas. Lee lo guardado y no llama a Meta. `refresh_leads` le pide antes a Meta los leads que todavía no llegaban y puede sumar leads nuevos a la bandeja; se permite una vez por minuto por espacio de trabajo, y dentro de ese minuto responde lo guardado con `refreshed: false` y `refreshSkipped: "throttled"`. Cada llamada devuelve hasta 100 leads (`limit`) y responde `total` y `truncated`; los filtros (`source`, `formId`, `search`) se aplican antes de que la bandeja salga de Watsi. Las dos piden `leads:read`, un alcance de lectura que se concede sólo si se marca (y que `leads:write` no incluye), y una credencial con un miembro detrás (`MEMBER_REQUIRED` sin él).
- **Automatizaciones de comentarios.** Las reglas que contestan los comentarios de tus publicaciones, reels y anuncios de Instagram o de tu página de Facebook, en público o por DM. `list_comment_automations` y `list_comment_automation_activity` las leen con `integrations:read`. `create_comment_automation`, `update_comment_automation`, `pause_comment_automation` y `duplicate_comment_automation` piden `automations:write` y van en un paso, porque ninguna le contesta a nadie: una regla nace como borrador, y una regla activa no se edita (se pausa, se edita y se vuelve a activar). Activarla sí va en dos pasos: `prepare_comment_automation_activation` responde una vista previa y un `confirmToken`, y `confirm_action` la enciende. Conectar la cuenta de Instagram o la página de Facebook y borrar una regla se hacen en la página Automatizaciones.
- **Tickets.** La mesa de soporte de tu espacio de trabajo. Estas herramientas aparecen en `tools/list` en cuanto se habiliten en este servidor; mientras tanto no se listan (requiere la función Tickets; sin ella toda llamada responde `TICKETS_NOT_ENABLED`). `list_tickets`, `get_ticket` y `list_ticket_types` leen con `tickets:read`; `create_ticket`, `claim_ticket` y `add_ticket_note` escriben con `tickets:write`, en un paso, porque le llegan a tu equipo y nunca al cliente. Los dos alcances son casillas desmarcadas al conectar: un ticket lleva lo que un cliente reportó. Ves lo que ves en la app: un miembro sin el permiso de toda la mesa lee sólo los tickets de sus contactos y los que atiende, abrir un ticket pide el permiso de crear, y sumarse a un ticket que otra persona atiende pide el de asignar. Un ticket se nombra por su id o su folio (`REP-0148`), un tipo por su clave y una persona por nombre o correo. Un contacto tiene un solo ticket vivo por tipo, así que un segundo se rechaza con `TICKET_YA_EXISTE` y el folio del primero. Una llave sin miembro detrás se rechaza (`MEMBER_REQUIRED`). Mover un ticket (estado, prioridad, título, motivo, resolución, quién lo atiende, los campos del tipo) va en dos pasos, porque marcarlo resuelto le avisa al cliente: `prepare_ticket_update` responde lo que cambia, de qué a qué, si se le avisará al cliente y un `confirmToken`, que se canjea con `confirm_action` (por REST, `POST /v1/actions/tickets/update/confirm`). El token caduca si el ticket cambia antes (y, si el cambio toca quién lo atiende, si alguien más se sumó), y sólo se canjea una vez. Un incidente con tickets abiertos debajo, o una caída de zona sin confirmar, no se resuelve ni se cierra por aquí (`TICKET_HAS_OPEN_CHILDREN`, `TICKET_AREA_OUTAGE_UNCONFIRMED`): en la app eso también resuelve cada ticket hijo, avisándole a cada cliente, o silencia el detector de caídas. `create_ticket_type` y `update_ticket_type` agregan y cambian los tipos de ticket (campos, motivos de cierre, responsable por defecto, SLA, si está activo) en un paso, con `tickets:write` y el permiso de configurar la mesa; borrar un tipo se hace en la app.

- **Notificaciones.** `update_notification_matrix` (`notifications:write`) cambia celdas de la matriz de notificaciones —un evento, `admin` o `member`, `email` o `push`— y cuánto antes de una cita sale su recordatorio; todas las celdas de una llamada se escriben juntas. Es la página Configuración → Notificaciones, así que pide un miembro con el permiso de configuración del espacio, y un evento que tu espacio no tiene responde `NOTIFICATION_EVENT_NOT_AVAILABLE`. Pide una credencial con un miembro detrás (`MEMBER_REQUIRED`). Los comandos del menú ⌘K del propio miembro (`*_operator_command`, `commands:write`) llegan a MCP y REST en una entrega posterior.
- **Configuración del espacio.** Cambiar la zona horaria va en dos pasos con `workspace:write`: `prepare_set_workspace_timezone` responde una vista previa (la zona actual y la nueva, y cuántos tipos de cita, reglas de horario, descansos y bloqueos tienen zona propia) y un `confirmToken`, y `confirm_action` hace el cambio una sola vez. El horario semanal es hora de reloj, así que todos los horarios que se ofrecen a tus clientes pasan a la zona nueva, y esas filas también; volver a la zona anterior no les devuelve la suya. Las citas conservan su instante. Acepta un nombre IANA estricto (`America/Mexico_City`, o `UTC`); un desfase como `+05:00` o una abreviatura como `EST` es `INVALID_TIMEZONE`, y el token se rechaza si alguna zona cambió desde la vista previa. `revoke_member_invite` (`members:write`) recibe el correo invitado o el id de la invitación y no le manda correo a nadie; un correo que comparten dos invitaciones pendientes es `INVITE_AMBIGUOUS`. Las dos piden una credencial con un miembro detrás. Poner el logo del espacio llega a MCP y REST en una entrega posterior.
- **Bloqueos de calendario.** `create_calendar_block`, `update_calendar_block` y `delete_calendar_block` cierran tiempo para que nada se agende en él (ids de `list_calendar_blocks`). No le avisan a nadie, así que van en un paso. Un bloqueo nombra a un asesor (`userId`), un tipo de cita (`appointmentTypeId`) o, sin ninguno, todo el espacio de trabajo, lo que pide el permiso «bloquear el calendario del espacio»; un miembro que sólo ve su calendario bloquea sólo a sí mismo o a sus tipos. Un asesor o tipo de otro espacio de trabajo se rechaza (`CALENDAR_BLOCK_TARGET_NOT_FOUND`), y piden una llave de API creada por un miembro (`MEMBER_REQUIRED`). Uno recurrente lleva `startTime`/`endTime` leídos en su `timezone`.
- **El agente de una conversación.** `conversation_set_agent_enabled` (`conversations:write`) prende o apaga el agente de IA en una conversación y así se queda hasta que alguien lo cambie; `conversation_set_agent` es la pausa por unos minutos. `conversation_set_active_agent` elige qué agente le contesta a ese cliente desde su siguiente mensaje (un agente de tu espacio de trabajo): como un traspaso de etapa del embudo, ese agente lee la conversación desde ahí con un resumen de lo anterior, y la elección dura hasta que la conversación cambie de etapa; `null` la devuelve al agente de su etapa. El agente al que pertenece la conversación (`ownerAgentId`) no cambia. Siguen las mismas reglas que el interruptor del agente en el chat, con los mismos efectos, y piden `chat:reply`, una persona del equipo detrás de la llamada y una conversación que esa persona pueda ver. En un chat marcado 👤 Personal, `conversation_set_agent_enabled` no prende el agente: responde `PERSONAL_CHAT_NEEDS_OWNER` (409) sin cambiar nada, porque prenderlo ahí también marcaría al contacto como cliente para siempre. Eso lo decide quien atiende el chat en la app, con «No es personal».
- **Respuestas aprendidas.** Las parejas de pregunta y respuesta que un agente aprende de las respuestas de tu equipo en los chats («Responder y enseñar»). `list_learned_answers` y `find_similar_learned_answer` (`agents:read`) las leen; incluyen preguntas que escribieron tus clientes. `save_learned_answer`, `create_learned_answer`, `edit_learned_answer`, `delete_learned_answer` y `dismiss_learned_answer` (`knowledge:write`) guardan una sugerida, enseñan una nueva, corrigen o borran una guardada, o descartan una sugerida. Una guardada es un documento que el agente consulta en cuanto se procesa, sin publicar nada; nunca cambia las preguntas y respuestas configuradas. Piden una llave de API creada por un miembro (`MEMBER_REQUIRED`) con los mismos permisos que la app: responder chats y enseñarle al agente para lo que se hace desde un chat (y el chat tiene que ser uno que ese miembro pueda ver; si no, `NOT_FOUND`), editar el agente para la lista de todo el agente, corregir y borrar. Guardar, enseñar y corregir tienen un tope por espacio de trabajo y por minuto (`RATE_LIMITED`). En el asistente de la app, guardar, enseñar, corregir y borrar son una tarjeta que aplicas con un clic.
- **Conocimiento del agente.** `crawl_agent_website` lee una página web pública (`https` y sólo direcciones públicas) y la agrega a la base de conocimiento como un documento; `import_agent_qa_pairs` agrega hasta 100 pares de pregunta y respuesta como un documento que el agente consulta, sin cambiar las preguntas y respuestas configuradas del agente; `retrain_agent_knowledge` vuelve a procesar hasta 50 documentos (ids de `get_agent_config`) y dice cuáles no pudo. Piden `knowledge:write`, una llave de API creada por un miembro (`MEMBER_REQUIRED`) que pueda editar el agente, y un documento o agente de otro espacio de trabajo se rechaza (`NOT_FOUND`). Sin `agentId` el documento es del agente predeterminado del espacio de trabajo. Si el agente ya tiene ese contenido se devuelve su documento (`alreadyExisted: true`); si lo tiene otro agente o todo el espacio de trabajo, se rechaza (`KNOWLEDGE_ALREADY_EXISTS`, con el nombre de quién). Un documento que todavía se procesa no se vuelve a entrenar (`skipped`). Hay un tope por espacio de trabajo y por minuto (`RATE_LIMITED`, con `retryAfterSeconds`). En el asistente de la app, agregar documentos (`add_agent_knowledge`), agregar una página o importar preguntas es una tarjeta que aplicas con un clic. `add_agent_knowledge` también marca `alreadyExisted: true` cuando el agente ya tenía ese contenido, y reporta como fallido (`KNOWLEDGE_ALREADY_EXISTS`) un documento que ya es de otro agente; acepta hasta 10 llamadas por espacio de trabajo y por minuto (`RATE_LIMITED`).
- **Preguntas frecuentes de una propiedad.** `generate_product_faqs` (`agents:write`) genera las preguntas frecuentes de una propiedad del catálogo a partir de los datos que ya tiene guardados y reemplaza las que tenía: se publican en su página pública y el agente las usa al hablar de ella. Devuelve las preguntas y respuestas guardadas. Cada llamada vuelve a generar y cuesta una llamada al modelo; un espacio de trabajo tiene 20 cada 10 minutos (`RATE_LIMITED` después, sin gastar nada). Si la llamada se corta por tiempo pudo haberse guardado igual: revisa la propiedad con `get_agent_config` antes de reintentar. Pide un catálogo inmobiliario, un miembro con `agent:config:write` o `workspace:settings:write` y una propiedad que ese miembro pueda ver.
- **Conversiones de Google Ads por etapa.** `list_google_ads_conversion_actions` (`integrations:read`) lista las conversiones que el espacio de trabajo registró y qué etapas del embudo reporta cada una. `set_stage_google_ads_conversion` (`agents:write`) elige qué conversión reporta una etapa cuando un contacto entra en ella, o la quita con `conversionActionId: null`; aplica desde la siguiente entrada a la etapa y guarda una versión del agente, como el editor. Las dos responden con un código, nunca con una lista vacía: `GOOGLE_ADS_NOT_ENABLED` si el espacio de trabajo no tiene conversiones de Google Ads, `GOOGLE_ADS_NOT_CONNECTED` si Google Ads no está conectado y `GOOGLE_ADS_NOT_CONFIGURED` si no hay cuenta ni conversión registradas (quitar una etapa sí se puede sin conexión). Además `GOOGLE_ADS_ACTION_NOT_FOUND` y `FUNNEL_STAGE_NOT_FOUND`. Si al espacio de trabajo todavía no se le activó el envío de conversiones, la respuesta trae un aviso en `warnings`. Si Watsi tiene pausado el envío de conversiones, la etapa queda configurada y empieza a reportar cuando se reanuda.
- **Probar un agente.** `test_agent` (`agents:write`) le manda un mensaje a un agente en una conversación de prueba y devuelve su respuesta, como el Playground de la app. El turno corre sólo con las herramientas de lectura del agente: puede revisar disponibilidad y buscar en la base de conocimiento, y no agenda, mueve ni cancela una cita, no abre un ticket, no manda un link de pago, no crea un pedido borrador, no le pasa la conversación a una persona, no actualiza el perfil de un contacto ni manda un seguimiento. La conversación de prueba se guarda aparte de la bandeja, y empezar una crea un contacto en el CRM para el miembro que la empezó. Devuélvele el `conversationId` que responde para seguir la prueba, y `agentVersionId` para probar una versión guardada en lugar del borrador. Pide una llave de API creada por un miembro que pueda usar el Playground (si no, `MEMBER_REQUIRED`); un chat que no sea una conversación de prueba de ese agente se rechaza (`NOT_FOUND`). Cada llamada es un turno nuevo, y un espacio de trabajo corre como máximo 60 por hora (después, `TEST_AGENT_RATE_LIMITED`). Ya está en el asistente de la app y llega a MCP y REST cuando se habilite en esos servidores; hasta entonces no aparece en `tools/list` ni en `/openapi.json`.
- **Versiones del agente.** Cada vez que se guarda un agente queda una versión. `list_agent_versions` (`agents:read`) las lista, de la más nueva a la más vieja, con los canales que sirven cada una ahora. `rename_agent_version` cambia el título de una versión; `restore_agent_version` regresa el borrador y el playground a una versión (también regresan el nombre, la descripción y el horario del negocio que guarda; los canales siguen con la versión que sirven); `publish_agent_version` hace de una versión la que reciben los clientes en un canal donde el agente YA está, y es como se regresa a una anterior. Las tres escrituras piden `agents:write`, una llave de API creada por un miembro (`MEMBER_REQUIRED`) y los mismos permisos que la app: editar el agente para renombrar y restaurar, prender canales para publicar. Un canal donde el agente no está se rechaza: conectarlo se hace en la app.
- **Tipos de cita.** `list_appointment_types` y `get_appointment_type_schedule` leen qué se puede agendar y quién lo atiende cuándo. `add_appointment_type_member` / `remove_appointment_type_member` cambian el equipo de un tipo, `create_`/`update_`/`delete_appointment_type_break` sus descansos semanales, y `set_appointment_type_weekly_rules` reemplaza su horario semanal (reemplazo completo: manda la semana entera). Piden el permiso «editar tipos de cita» y una llave de API creada por un miembro; una persona de otro espacio de trabajo en un equipo se rechaza (`APPOINTMENT_TYPE_MEMBER_NOT_FOUND`).

- **Tipos de cita.** `list_appointment_types` y `get_appointment_type_schedule` leen qué se puede agendar y quién lo atiende cuándo. `add_appointment_type_member` / `remove_appointment_type_member` cambian el equipo de un tipo, `create_`/`update_`/`delete_appointment_type_break` sus descansos semanales, y `set_appointment_type_weekly_rules` reemplaza su horario semanal (reemplazo completo: manda la semana entera). Piden el permiso «editar tipos de cita» y una llave de API creada por un miembro; una persona de otro espacio de trabajo en un equipo se rechaza (`APPOINTMENT_TYPE_MEMBER_NOT_FOUND`). `create_appointment_type` y `update_appointment_type` crean y cambian el tipo mismo (sin `agentId`, un tipo nuevo es del agente predeterminado del espacio de trabajo, y se crea habilitado y en la página pública de reservas; `isEnabled: false` deja de ofrecerlo; eliminar un tipo se hace en la página de Calendario), con las mismas reglas que la página de Calendario; un agente, espacio o plantilla de WhatsApp de otro espacio de trabajo se rechaza (`AGENT_NOT_FOUND`, `SPACE_NOT_FOUND`, `TEMPLATE_NOT_FOUND`), igual que un tipo fuera del alcance de datos del miembro de la llave (`APPOINTMENT_TYPE_NOT_FOUND`). Estos dos todavía no aparecen en la lista; llegan en cuanto la plataforma termine de habilitarlos (en el asistente de la app ya funcionan).
- **Espacios.** `list_spaces` lee las salas, oficinas o unidades donde se agendan citas; `create_space` y `update_space` las crean y cambian (nombre, color, orden y `assignedMemberIds`, los asesores a los que van sus chats). Piden el permiso «configuración del espacio de trabajo». Un espacio se elimina sólo en la página de Calendario, porque eliminarlo quita sus bloqueos y desliga sus citas. `list_space_blocks`, `create_space_block`, `update_space_block` y `delete_space_block` cierran un espacio de `startAt` a `endAt` para un tipo de cita (`appointmentTypeId`) o, sin él, para todos — eso pide el permiso «bloquear el calendario del espacio de trabajo». Un miembro que sólo ve su propio calendario bloquea sólo los tipos a los que pertenece. Un espacio, un tipo de cita o un asesor de otro espacio de trabajo se rechaza (`SPACE_NOT_FOUND`, `CALENDAR_BLOCK_TARGET_NOT_FOUND`, `SPACE_MEMBER_NOT_FOUND`). No le avisan a nadie, así que van en un paso.
- **El token.** Dura 10 minutos, es de la misma persona y deja de servir si la cita cambió desde la vista previa (`APPOINTMENT_CONFIRMATION_STALE`). Confirmar el mismo token dos veces no agenda dos citas, ni siquiera con `replaceExistingAppointments`.

## Conéctate con un solo comando

¿Prefieres hacerlo tú? En **Claude Code**, agrega el servidor y luego escribe `/mcp`, elige `watsi` y **Authenticate**: se abre tu navegador para que inicies sesión en watsi. Sin clave de API.

```bash
claude mcp add --transport http watsi https://mcp.watsi.ai/mcp
```

Si tu cliente no puede iniciar sesión con OAuth, usa una clave de API como en los pasos de abajo.

## Configura un cliente paso a paso

### Crea una clave de sólo lectura

Abre [watsi.ai/workspace/settings/api-keys](https://watsi.ai/workspace/settings/api-keys) (**Configuración → Desarrollador → Claves API**), pulsa **Crear Clave API** y deja sólo los permisos de lectura que necesites. Copia la clave: sólo se muestra una vez.

### Agrega el servidor a Claude Desktop

Edita `claude_desktop_config.json` (Configuración → Desarrollador → Editar configuración) y agrega una entrada `watsi`. Claude Desktop se conecta a servidores HTTP remotos con `mcp-remote`:

```json claude_desktop_config.json
{
  "mcpServers": {
    "watsi": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.watsi.ai/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}
```

### …o Cursor y otros clientes HTTP

Los clientes que hablan Streamable HTTP de forma nativa (Cursor, Windsurf, agentes propios) toman la URL y los encabezados directamente. En Cursor, en `.cursor/mcp.json`:

```json .cursor/mcp.json
{
  "mcpServers": {
    "watsi": {
      "url": "https://mcp.watsi.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

### Pregunta

Reinicia el cliente y pregunta sobre tu espacio de trabajo en lenguaje normal. El modelo elige la herramienta, la llama con tu clave y responde con tus datos en vivo.

## Claude y ChatGPT

Las apps de chat llaman a los servidores MCP desde su propia nube y no pueden mandar una clave fija, así que inician sesión con **OAuth**: inicias sesión en watsi, eliges el espacio de trabajo y apruebas los alcances. No hay encabezado que configurar ni clave que pegar.

- **Claude** (web, escritorio y móvil): watsi está en el directorio de conectores de Claude. Búscalo como «watsi» y conéctalo. Paso a paso: [Conecta watsi con Claude](/mcp/claude).
- **ChatGPT**: agrega `https://mcp.watsi.ai/mcp` como conector personalizado. Paso a paso: [Conecta watsi con ChatGPT](/mcp/chatgpt).

> **Note**

ChatGPT advierte que un conector personalizado no está verificado por ChatGPT: es lo normal para cualquier servidor que agregas por URL.

## Preguntas de ejemplo

- «¿Cuántos contactos nuevos tuve esta semana?»
- «¿Qué conversaciones llevan más de un día esperando respuesta?»
- «Resume la conversación con María García.»
- «¿Cómo cambió mi tasa de respuesta de IA respecto al mes pasado?»
- «¿Por qué se están escalando conversaciones a una persona?»

- [Autenticación](/guides/authentication)
    Claves, alcances y límites.
- [Todas las rutas](/api/overview)
    La misma superficie, por REST.
