Integración de MCP
En las organizaciones modulares, la organización conectada necesita tener activo el módulo de CRM, además de los permisos requeridos por la integración. La API subyacente devuelve HTTP 403 con module_not_active cuando no hay acceso al CRM. Resuelve el acceso al módulo en Subscription antes de volver a intentarlo; cambiar solo la clave de API no corrige este error.
Scoutello proporciona un servidor remoto de Model Context Protocol (MCP) para acceder de forma controlada a los datos de la organización. Utiliza las mismas integraciones, claves de API, permisos, comprobaciones del tenant, límites de frecuencia y comportamiento de los registros que la API REST de Scoutello.
Usa MCP cuando un cliente o agente de IA deba descubrir y llamar a las operaciones de Scoutello como herramientas. Usa REST cuando una aplicación necesite endpoints HTTP convencionales o un cliente OpenAPI generado. Ambas interfaces utilizan el mismo contrato de datos subyacente.
Antes de conectarse
Una persona administradora de la organización debe crear una integración en Organization settings → Developer/API. Al crear o rotar su clave:
- Selecciona solo los permisos de lectura y escritura que necesite el cliente MCP.
- Guarda la clave completa
sctl_api_cuando se muestre. Scoutello la muestra una sola vez. - Guarda la clave en el secreto o la configuración de entorno del cliente MCP, no en el control de versiones.
La misma clave de integración puede llamar a REST y MCP. No es necesario ni recomendable crear una clave específica para MCP. Las claves sctl_mcp_ antiguas no se aceptan.
Valores de conexión
Configura el cliente con estos valores:
Transport: Streamable HTTP
URL: https://admin.scoutello.com/api/v1/mcp
Header name: Authorization
Header value: Bearer YOUR_API_KEY
Sustituye YOUR_API_KEY por la clave de integración guardada. Los formatos de configuración varían según el cliente, pero el transporte, la URL y el encabezado HTTP anteriores son siempre los mismos. Si un cliente no puede establecer Authorization, puede enviar la clave en x-api-key. No configures ambos encabezados.
La URL https://admin.scoutello.com/api/mcp heredada sigue disponible como alias de compatibilidad. Las conexiones nuevas deben usar el endpoint versionado /api/v1/mcp.
Verificar la conexión
Después de conectar el cliente, llama primero a la herramienta whoami. Devuelve información sobre la integración y la organización actuales, la expiración y el uso de las credenciales, el estado del límite de frecuencia y los permisos concedidos, sin exponer registros de la organización.
Si whoami identifica una organización o integración inesperada, desconecta el cliente y corrige su clave antes de llamar a otra herramienta.
Herramientas y permisos
El servidor MCP solo anuncia las herramientas concedidas por la clave actual. Un cliente no puede descubrir ni llamar a una herramienta de escritura usando únicamente el permiso de lectura correspondiente.
| Permiso de API | Herramientas MCP |
|---|---|
contacts.read | contacts_list, contacts_get, contacts_get_by_external_id |
contacts.write | contacts_batch_upsert |
tasks.read | tasks_list, tasks_get, tasks_get_by_external_id |
tasks.write | tasks_batch_upsert |
protocols.read | protocols_list, protocols_get, protocols_get_by_external_id |
protocols.write | protocols_batch_upsert |
opportunities.read | opportunities_list, opportunities_get, opportunities_get_by_external_id |
opportunities.write | opportunities_batch_upsert |
projects.read | projects_list, projects_get, projects_get_by_external_id |
projects.write | projects_batch_upsert (incluidas las actualizaciones de participantes) |
milestones.read | milestones_list, milestones_get, milestones_get_by_external_id |
milestones.write | milestones_batch_upsert |
members.read | members_list |
events.read | events_list, events_get, events_get_by_external_id |
events.write | events_batch_upsert |
mails.read | mails_list, mails_get |
mail-drafts.read | mail_drafts_list, mail_drafts_get, mail_drafts_get_by_external_id |
mail-drafts.write | mail_drafts_batch_upsert (solo para preparar la revisión humana) |
tags.read | tags_list |
whoami siempre está disponible para una conexión autenticada. Las entradas y los resultados de las herramientas siguen los mismos esquemas y envoltorios de respuesta que sus operaciones REST asociadas.
contacts_list acepta search acotados en los nombres, type, status y tagIds (un array de entre 1 y 50 identificadores que coincide con cualquiera de las etiquetas seleccionadas). Todos los tokens de búsqueda deben coincidir con un campo de nombre; todos los filtros se combinan con AND. Mantén estos filtros en cada página del cursor. Por ejemplo, { "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } encuentra cuentas existentes que coinciden sin tener que recorrer todo el inventario.
Los contactos de CRM que no son miembros y están vinculados a un inicio de sesión de Scoutello se pueden leer y referenciar, mientras que los campos de pertenencia y cuenta permanecen ocultos y las ediciones de contactos siguen protegidas. Una actualización que solo incluya un vínculo externo puede registrar un contacto legible mediante externalId, su scoutelloId y externalUpdatedAt opcional; omite todos los campos de CRM. En los reintentos posteriores o las actualizaciones de metadatos, omite scoutelloId. Consulta las reglas de vinculación y límites de los contactos.
Escribir de forma segura
Las herramientas de actualización masiva pueden modificar los datos de Scoutello de inmediato. Son idempotentes para la misma integración y los mismos ID externos, pero aun así conviene revisar el recurso, la organización y el alcance previstos antes de aplicar cambios.
Establece mode en validate para ejecutar la coincidencia y la validación sin escribir datos. Después de inspeccionar los resultados, repite la llamada con mode: "apply" para aceptar los registros válidos. MCP no expone operaciones de eliminación.
Pausar una integración rechaza las solicitudes REST y MCP que utilizan sus claves. La rotación reemplaza sus credenciales, y revocar deshabilita permanentemente todas las credenciales pertenecientes a la integración.
Solución de problemas
| Resultado | Qué comprobar |
|---|---|
401 error de autenticación | Confirma que la clave completa esté presente y que el encabezado use Bearer, sin comillas alrededor de la clave. |
403 error de autorización | Concede el alcance requerido rotando la clave de integración y, después, actualiza el cliente con la clave de reemplazo. |
404 en la URL de MCP | Confirma que la URL termine en /api/v1/mcp. Es posible que el servicio MCP aún no esté habilitado en ese entorno de Scoutello. |
429 error de límite de solicitudes | Espera hasta la hora de restablecimiento devuelta antes de volver a intentarlo. REST y MCP consumen la misma cuota de integración. |
| Falta una herramienta | Comprueba los alcances de la clave con whoami; las herramientas no disponibles se omiten deliberadamente del descubrimiento. |
Para consultar los campos de los registros, la paginación, el comportamiento de las operaciones masivas y los formatos de error, continúa con la referencia de la API de Scoutello.
Planificación de proyectos conectados
Crea un proyecto, después sus hitos y, a continuación, las tareas y los protocolos utilizando ID externos estables de la integración. El acceso a los nuevos hitos requiere milestones.read/milestones.write; concede members.read para consultar miembros asignables. Las credenciales existentes no amplían sus permisos automáticamente. Después de rotar o conceder acceso, actualiza el descubrimiento de herramientas e inspecciona whoami.
Usa los ID de cliente de los miembros para assignedContacts de proyectos e hitos, y los ID de usuario para assignedScoutelloUserIds de tareas o ownerScoutelloUserId de oportunidades. Las referencias de tareas y protocolos aceptan projectScoutelloId o projectExternalId, además de los pares equivalentes de hitos y oportunidades. Los enlaces que solo incluyen el hito infieren el proyecto; las discrepancias rechazan el elemento de la operación masiva. Los participantes del proyecto se actualizan de forma aditiva y las entradas omitidas se conservan.
Los protocolos admiten notas de proyectos e hitos sin contacto y el estado draft/final. Las importaciones de este trabajo conectado son silenciosas y nunca envían comunicaciones. Las herramientas de listado exponen los mismos filtros específicos de cada entidad para proyectos, estados, asignaciones y fechas de vencimiento que REST. Mantén los filtros exactos, incluido updatedSince, en cada página del cursor. Consulta la referencia de la API para ver el contrato completo y la semántica de valores nulos u omitidos.
Valida cada operación masiva dependiente, aplícala, inspecciona todos los resultados y vuelve a leer los registros antes de considerar completa la carga. Una simulación no puede resolver padres que solo existen en otra simulación. Al reintentar un enlace inicial ambiguo mediante scoutelloId, primero lee por ID externo; los ID de arranque no se pueden reproducir una vez que existe el enlace.
Instrucciones para agentes de proyectos comerciales
Cada contacto creado o reutilizado para un proyecto comercial debe hacer referencia explícita a ese proyecto mediante projectScoutelloId o projectExternalId en contacts_batch_upsert. Mencionar un proyecto en las notas o en un ID externo no constituye pertenencia. Las escrituras de contactos con referencias de proyecto también requieren projects.write. Vuelve a leer el contacto con contacts.read y projects.read, y verifica projectParticipations; conserva las pertenencias y los grupos existentes. Los contactos genéricos fuera de un proyecto no requieren una referencia de proyecto.
Mantén las empresas y las personas verificadas como contactos separados. Vincula una persona a la empresa con companyScoutelloId o companyExternalId, no únicamente con companyName. Los cambios de contacto, relación con la empresa y pertenencia son atómicos por elemento de la operación masiva; las referencias no válidas no dejan un contacto parcial. No inventes personas ni apliques etiquetas de procedencia.
Prepara los correos salientes con mail_drafts_batch_upsert, nunca como cuerpos de protocolo. Concede explícitamente los nuevos alcances mail-drafts.read y mail-drafts.write; la preparación también requiere contacts.read y projects.write. Las credenciales existentes no reciben permisos nuevos automáticamente. Usa un ID externo estable, expectedVersion: 0 para la creación, referencias explícitas al proyecto y al contacto, el ID de usuario de una persona aprobadora autorizada y un alcance de remitente organization o personal configurado. Nunca adivines la dirección del destinatario ni la configuración del remitente.
Mantén la investigación en content.notes; solo content.subject y content.body son contenido saliente. La creación del borrador garantiza que el contacto sea participante del proyecto. Las actualizaciones deben utilizar la versión devuelta por la lectura más reciente; los borradores revisados o enviados rechazan las ediciones. Los reintentos idénticos devuelven el borrador original sin crear otra revisión. Vuelve a leer su reviewUrl, draftVersion, contentHash, el estado de aprobación o envío y su mailScoutelloId final.
Solo la persona humana asignada puede aprobar y enviar mediante la pantalla de revisión existente. Las integraciones no pueden aprobar, despachar ni enviar, incluso con acceso de escritura a borradores. Conserva los protocolos originales al convertir borradores antiguos y establece referencias cruzadas con los reemplazos. Los fallos de entrega en cola o ambiguos requieren investigación, nunca un reenvío automático.
Preparación de publicaciones sociales
Concede social-channels.read, social-posts.read, social-post-drafts.read y social-post-drafts.write según sea necesario. members_list (members.read) puede descubrir los ID de usuario de las personas revisoras. Las herramientas sociales solo se anuncian cuando se concede su ámbito:
| Ámbito | Herramientas |
|---|---|
social-channels.read | social_channels_list |
social-posts.read | social_posts_list, social_posts_get |
social-post-drafts.read | social_post_drafts_list, social_post_drafts_get, social_post_drafts_get_by_external_id |
social-post-drafts.write | social_post_drafts_batch_upsert, social_media_create_upload, social_media_finalize_upload |
Lee las capacidades del canal y el historial creado por Scoutello, carga los recursos y, después, envía las variantes completas del canal con una persona revisora identificada. Las herramientas de carga devuelven instrucciones HTTP PUT: transfiere los bytes del archivo original fuera de MCP y, después, finaliza la carga con { "assetId": "..." }. No incrustes archivos codificados en base64 en los argumentos de las herramientas.
Usa expectedVersion: 0 para los borradores nuevos y la versión actual para las revisiones pendientes. mode: "validate" no realiza ninguna escritura. La herramienta devuelve la URL de revisión; solo una persona que use el panel puede aprobar la publicación o programación. No existe ninguna herramienta de MCP para aprobar, publicar, cancelar o eliminar una publicación. Consulta periódicamente las herramientas de borradores e historial para comprobar la aprobación, los motivos del rechazo y los resultados de entrega por canal. Los borradores revisados requieren un nuevo ID externo para propuestas posteriores.
Consulta publicaciones sociales para revisión humana para ver ejemplos de entrada, límites de carga, paginación y el comportamiento de las revisiones tardías.