Referencia de herramientas MCP

Esta referencia reúne el contrato de las herramientas MCP que más usan los integradores: las cuatro del dominio de integraciones (aplicaciones externas, credenciales, ajustes de integración de la organización y estado del dominio), las ampliaciones del CRM, el servidor de Finanzas y el calendario laboral de RRHH. Para cada operación indica el permiso que necesita tu usuario, el scope que necesita el token y si exige confirmación.

Otras herramientas tienen página propia: Marketing, tickets, AI Studio y el buscador global y los avisos. Si es tu primera conexión, empieza por Primeros pasos con MCP.

Cómo se autoriza cada operación

Cada operación pasa por estas comprobaciones, en este orden. Las tablas de esta página dan, para cada una, el permiso, el scope y si exige confirm.

Aplicaciones externas y credenciales

Cuatro herramientas cubren el dominio de integraciones:

En la aplicación, las aplicaciones externas se gestionan en Ajustes › Creadas por tu empresa, necesitas entrar con tu cuenta.

integrations

Es la herramienta con la que registras tu propia integración, la suscribes a eventos y vigilas su salud. También explora el catálogo de aplicaciones y gestiona las que tu empresa tiene instaladas.

Instalar una aplicación del catálogo no se hace por MCP: exige que una persona vea la ficha, acepte sus permisos y elija la persona responsable. Tampoco comprar una de pago, cambiar de plan, reactivar la suscripción ni pagar un cobro pendiente: piden consentimiento y pago en pantalla. Las fichas que publica una cuenta de desarrollador se gestionan en el servidor de desarrolladores, no aquí. catalog_list y catalog_get devuelven la dirección de la ficha para que el asistente te ofrezca abrirla. Lo que hace la empresa está en Explorar e instalar aplicaciones.

Las renovaciones (apps_regenerate_api_key, apps_webhooks_regenerate_secret y apps_widget_identity_regenerate_secret) piden a la persona, si tiene la verificación en dos pasos, que las confirme en el móvil: la primera llamada responde APPROVAL_REQUIRED con un número, la persona elige ese número en la aplicación y la llamada se repite igual, con twoFactorApprovalId. Por MCP nunca se aceptan códigos. La aplicación de iPhone que hay hoy en la App Store todavía no aprueba estas confirmaciones; hasta que llegue la próxima versión, quien tenga la verificación activada renueva las claves desde la ficha de la aplicación, con su código. La clave nueva se devuelve una sola vez y no se guarda en ninguna parte.

El SDK de JavaScript no tiene todavía un método para apps_update_scopes (appsUpdate solo cambia los datos descriptivos): para sustituir los scopes de una aplicación, invoca la herramienta por JSON-RPC.

Ejemplo: crear una aplicación y configurar su webhook. Los SDK necesitan una sesión OAuth autorizada para el servidor utilia-work, como se explica en Primeros pasos con MCP.

const created = await sdk.mcp.integrations.appsCreate({
  name: 'Mi integración',
  slug: 'mi-integracion',
  description: 'Integración personalizada.',
  websiteUrl: 'https://miempresa.com',
});
 
await sdk.mcp.integrations.appsWebhooksUpdateConfig(created.app.id, {
  webhookUrl: 'https://miempresa.com/webhooks/utilia',
  webhookEnabled: true,
  webhookEvents: ['TICKET_CREATED', 'INVOICE_PAID'],
});
 
const test = await sdk.mcp.integrations.appsWebhooksTest(created.app.id);
console.log(test.success ? `Entregado: ${test.statusCode}` : test.error);

Cómo verificar en tu servidor la firma de las entregas se explica en Firma HMAC de los webhooks.

api_credentials

Gestiona las claves de API de tu organización. Con ella un asistente de IA puede hacer todo lo que se hace en Ajustes, Claves de API, con las mismas reglas y, para lo delicado, con tu confirmación en el móvil.

Claves de API de la organización (utk_, 10). Son las de Claves de API de la organización: cada una actúa en nombre de una persona responsable y nunca puede más que ella. Las operaciones org_keys_* llaman al mismo servicio que la pantalla, así que se aplican igual:

• la persona responsable;
• el techo de permisos y el plan de cada módulo;
• la regla de que solo un Super Administrador nombra responsable a otra persona;
• el modo restringido y la auditoría.

Crear, cambiar y renovar exigen además Integraciones en el plan; ver y revocar, no. La persona responsable puede revocar su clave aunque no gestione claves, pero el asistente necesita el scope integrations:credentials:manage, y ese scope solo puede autorizarlo quien gestiona claves. Si no lo tiene, que la revoque desde la pantalla.

Lo que fabrica o amplía acceso se confirma en el móvil. Crear, renovar, ampliar permisos, alargar o quitar la caducidad y cambiar de responsable siguen el ciclo de siempre:

1. La primera llamada devuelve errorCode: APPROVAL_REQUIRED.
2. El móvil enseña qué clave es, a nombre de quién y con qué permisos.
3. Cuando la persona lo aprueba, repites la misma llamada, con los mismos datos y con twoFactorApprovalId.

La confirmación solo vale para esa clave con esos datos: una instrucción escondida en un documento no basta para fabricar una clave. Sin la verificación en dos pasos activada, estas operaciones se rechazan con TWO_FACTOR_NOT_ENABLED.

Las operaciones generales (list, get, get_usage, rotate y revoke) no tocan estas claves. list no las enseña y avisa de cuántas hay; las demás remiten a su operación org_keys_*.

Credenciales personales y de aplicación (7). Son las credenciales de un usuario (PERSONAL) y las recortadas de una aplicación externa (EXTERNAL_APP). Las de cuenta de servicio (SERVICE_ACCOUNT) ya no se crean, porque no sirven para entrar en ningún sitio. Para conectar un programa, usa org_keys_create. Al rotar, el secreto nuevo se muestra una sola vez y el anterior sigue valiendo 24 horas.

Estas siete aceptan también SETTINGS_ORGANIZATION_EDIT en lugar de API_CREDENTIALS_MANAGE: basta con uno de los dos.

Reglas de create y rotate:

• Nadie da a una credencial lo que no tiene. Si no eres Super Administrador, solo puedes conceder scopes cuyo permiso tienes. Si pides alguno más, la llamada se rechaza con errorCode: CREDENTIAL_SCOPE_AUTHORITY_EXCEEDED y el mensaje dice cuáles sobran. El acceso total (*) solo lo concede el Super Administrador. Esto se comprueba antes de pedir la confirmación, para que nadie apruebe en el móvil algo que se va a rechazar.
• Confirmación en el móvil, con el mismo ciclo de APPROVAL_REQUIRED y twoFactorApprovalId. Exige tener la verificación en dos pasos activada.
• Con la organización en modo restringido no se crea ninguna credencial; consultarlas y revocarlas sigue funcionando.

const { secret, previousValidUntil } = await sdk.mcp.apiCredentials.rotate(
  credentialId,
  { reason: 'Rotación trimestral' },
);
 
console.log('Secreto nuevo:', secret);
console.log('El anterior vale hasta:', previousValidUntil);

org_integrations_settings

Agrupa ajustes de integración de la organización anteriores al dominio de aplicaciones externas. Vive en el servidor utilia-crm. Si vienes de una versión antigua de los SDK, esta herramienta es la que antes se llamaba integrations: consulta la guía de migración.

La herramienta aparece en tools/list con los conjuntos crm:read, crm:full, dev:read o dev:full, o con cualquier scope de lectura del CRM, pero cada operación exige además su propio scope, que es el de la tabla.

Claves de API v1 de la organización (8). Además del permiso, la clave tiene que haberla creado tu usuario y pertenecer a tu organización.

api_keys_create y api_keys_regenerate siguen las mismas reglas de confirmación que api_credentials: la primera llamada devuelve APPROVAL_REQUIRED, se repite con twoFactorApprovalId tras aprobar en el móvil, y sin la verificación en dos pasos activada se rechazan con TWO_FACTOR_NOT_ENABLED. Con la organización en modo restringido no se crea ninguna clave.

Por compatibilidad con las integraciones anteriores al 28 de agosto de 2026, un token con scopes del CRM o del dominio de trabajo puede leer las claves aunque no lleve integrations:credentials:view. Para gestionarlas hay que pedir siempre integrations:credentials:manage.

Formularios de captación (11). Se corresponden con Ajustes › CRM › Formularios de captación, necesitas entrar con tu cuenta.

integrations_overview

Da el estado del dominio de integraciones en una sola llamada, pensado para un copiloto o un panel. Es de solo lectura y su respuesta se guarda en caché 30 segundos por organización y operación. health, quickstart y app_diagnosis leen del mismo diagnóstico que la pestaña Pruebas de cada aplicación y que GET /external/v1/diagnostics, así que no se contradicen.

app_diagnosis exige EXTERNAL_APPS_VIEW, el mismo permiso que la ficha de la aplicación en el panel: con permisos personalizados, INTEGRATIONS_OVERVIEW_VIEW solo da el resumen. Busca la aplicación dentro de tu organización: si no está o está eliminada, responde APP_NOT_FOUND, exista o no en otra. Su respuesta tiene la forma de GET /external/v1/diagnostics, con la voz de quien administra la organización: «Concede el permiso…» en vez de «Pide a un administrador…». Se llama con tools/call; en los SDK, appDiagnosis(appId) (app_diagnosis) llega con la 4.6.0.

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "integrations_overview",
    "arguments": { "operation": "app_diagnosis", "appId": "ckapp1234567890" }
  }
}

const status = await sdk.mcp.integrationsOverview.status();
const health = await sdk.mcp.integrationsOverview.health();
 
console.log(`Aplicaciones activas: ${status.apps.active}/${status.apps.total}`);
 
if (health.overall !== 'healthy') {
  console.warn('La peor parada:', health.worstApp?.appName, health.worstApp?.verdict);
  for (const app of health.appsNeedingAttention) {
    console.warn(`${app.appName}: ${app.status}`);
  }
}

Los campos son los de la respuesta del servidor: la peor parada va en worstApp (appId, appName, errorRate, lastErrorAt, status y verdict) y las que hay que revisar, en appsNeedingAttention. Los tipos de los SDK con estos nombres, y app_diagnosis como método, llegan con la 4.6.0: con una versión anterior, worstApp.name siempre llegaba vacío y en Python status() fallaba al validar (Versiones y compatibilidad).

Qué cuenta quickstart como pendiente y qué solo recomienda:

• missingConfig (pasos que faltan): que no haya ninguna aplicación; que una aplicación activa con permisos de facturas tenga la facturación apagada, que va primero y nombra las aplicaciones, porque cada factura que intenten emitir se rechaza con BILLING_NOT_ENABLED; cada bloqueo del diagnóstico de las aplicaciones activas, con las aplicaciones que lo tienen; y que haya aplicaciones que envían facturas por correo sin ningún dominio de envío verificado.
• recommendations (no son pasos pendientes): lo que el plan no incluye, porque no se arregla configurando; los avisos del diagnóstico de cada aplicación; y los avisos a tu servidor, que son opcionales porque una aplicación que solo llama a la API funciona sin ellos.

nextAction sigue este orden: crear la primera aplicación; activar la facturación apagada, con la operación apps_billing_update_config de integrations (solo un Super Administrador, con un motivo de al menos 20 caracteres); el primer bloqueo de una aplicación, que remite a app_diagnosis; verificar un dominio de envío; y, con todo lo necesario hecho, los avisos a tu servidor como opcionales.

Es el mismo diagnóstico que resume en una línea el bloque Estado de la ficha de cada aplicación (Panel de aplicaciones externas).

Permisos por rol

De los seis roles de UTILIA OS, solo dos traen permisos de integraciones por defecto: Super Administrador, todos, y Gerente, los de consulta y los de gestionar los errores de las aplicaciones. Vendedor, Asistente, Visualizador y Comercial Externo («Otros roles» en la figura) no traen ninguno.

API_CREDENTIALS_MANAGE solo lo trae el rol Super Administrador: un Gerente no gestiona credenciales aunque su token lleve el scope.

Conjuntos de scopes:

Eventos y conexiones con otros módulos

Tu aplicación puede suscribirse, en webhookEvents, a eventos de todo el ecosistema. El catálogo completo, con el contenido de cada aviso, está en Avisos: contenido y catálogo de eventos, y apps_webhooks_list_supported_events lo devuelve por MCP. Algunos ejemplos:

• Leads: LEAD_CREATED, LEAD_QUALIFIED, LEAD_DISQUALIFIED y LEAD_CONVERTED. Un formulario de captación crea un lead en el CRM, y con él llega LEAD_CREATED.
• Clientes y contactos: CLIENT_CREATED, CLIENT_UPDATED y CONTACT_CREATED.
• Facturas y presupuestos: INVOICE_PAID, INVOICE_PAYMENT_FAILED, INVOICE_REFUNDED y BUDGET_SIGNED.
• Tickets de soporte: TICKET_CREATED, TICKET_REPLIED, TICKET_RESOLVED y TICKET_CONVERTED.
• Archivos: FILE_UPLOADED.
• Errores de tu aplicación: ERROR_REPORTED, ERROR_RESOLVED y ERROR_REOPENED. Tu aplicación los reporta en POST /api/external/v1/errors/report; se agrupan por huella, ERROR_REPORTED se emite la primera vez y integrations_overview: health los tiene en cuenta en su veredicto.

Cada aviso lleva la versión de su contenido en la cabecera X-Utilia-Schema-Version y en payload.meta.schemaVersion. Los eventos broadcast llegan a todas las aplicaciones suscritas; los directed, solo a la aplicación dueña del recurso.

La facturación por aplicación se apoya en el módulo de Finanzas: sus facturas y cobros se consultan con apps_billing_list_invoices y apps_billing_list_payments, y los eventos INVOICE_PAID, INVOICE_PAYMENT_FAILED e INVOICE_REFUNDED te avisan del resultado de cada cobro.

CRM (servidor utilia-crm)

Las herramientas canónicas del CRM tienen operaciones que comparten reglas con la API externa (/external/v1/leads y /external/v1/clients). Esta sección recoge las que más usan los integradores.

Cualificar, descartar y convertir leads; desactivar clientes

Los conjuntos crm:write y crm:full incluyen crm:leads:update y crm:clients:update.

El motivo de set_qualified y de set_disqualified viaja en reason, y se guarda en las notas internas del lead. set_qualified acepta también notes como alias heredado, que es el que usan hoy los métodos setQualified y set_qualified de los SDK; si llegan los dos, manda reason.

Anotar un correo sin enviarlo

crm_interactions_quick: log_email deja constancia de un correo saliente en el historial del cliente, pero no envía nada. Su respuesta trae delivered: false, que es su estado normal, no un fallo. to y body son obligatorios, y con scheduledFor la interacción queda programada en vez de completada.

Anotar no es avisar. Si un asistente usa log_email para «avisar al cliente», dará por comunicado algo que nadie ha recibido. Los correos de verdad salen por las herramientas que los envían: el presupuesto con crm_budgets, la factura con crm_invoices, la campaña con marketing_campaigns.

Grupos de empresas

El CRM agrupa empresas bajo una matriz, en dos niveles: matriz y filiales.

get y list de crm_clients devuelven parentClientId, hierarchyRole (PARENT, SUBSIDIARY o STANDALONE) y parent { id, name }; el nombre de la matriz solo llega si la matriz está dentro de tu alcance. list acepta los filtros parentClientId y hierarchyRole, y la búsqueda por texto encuentra las filiales también por el nombre de su matriz, solo entre las matrices que puedes ver.

Operaciones de grupo en crm_clients_info:

crm_clients acepta parentClientId en create y en update, y en los dos casos exige CLIENTS_MANAGE_HIERARCHY sobre las dos empresas. En create, el permiso se comprueba antes de crear y el vínculo se aplica después del alta: si el vínculo falla, el cliente queda creado y el error lo dice con su identificador. En update, la jerarquía se procesa primero y, si no puedes gestionarla, no se aplica ningún cambio.

convert_to_invoice de crm_budgets acepta receiverClientId (alias receiver_client_id) para emitir la factura a la matriz del cliente del presupuesto en lugar de a la propia empresa; cualquier otro receptor se rechaza. Pide el aplicativo Finanzas en el plan de la organización, los tres permisos BUDGETS_EDIT, INVOICES_VIEW e INVOICES_CREATE (con receptor alternativo, además acceso a la matriz) y los tres scopes crm:budgets:update, crm:invoices:view y crm:invoices:create; con issueDirectly, también crm:invoices:issue. Ningún scope de lectura basta.

Campos personalizados

Cada organización define campos personalizados para clientes, contactos, leads y oportunidades. crm_clients, crm_contacts, crm_leads y crm_opportunities exponen ese catálogo y permiten escribir sus valores.

list_custom_fields devuelve el catálogo activo de la entidad de la herramienta. Consúltalo antes de escribir para conocer las claves válidas y sus tipos.

Cada campo trae key, label, type (TEXT, NUMBER, DATE, BOOLEAN, SELECT, MULTISELECT, CURRENCY, URL, EMAIL o PHONE), description, isRequired, isMultiline, sortOrder y, en las listas, sus options activas ({ value, label }).

Para escribir valores, create y update aceptan customFields con la forma { clave: valor }. El servicio valida el tipo, la obligatoriedad, la opción y el formato, y sus errores llegan legibles. Los valores vuelven también en get y list.

{
  "operation": "update",
  "id": "cli_123",
  "customFields": {
    "sector_vertical": "retail",
    "fecha_alta_manual": "2026-07-01",
    "cliente_estrategico": true
  }
}

Escribir valores exige el scope de escritura de la entidad (crm:clients:update, crm:contacts:create...); crm:custom-fields:view solo lee el catálogo. Crear, editar, reordenar, archivar o eliminar campos se hace con crm_settings (apartado siguiente).

Configuración del CRM

crm_settings configura lo mismo que Ajustes > CRM en la aplicación: las etapas del embudo de ventas, el catálogo de campos personalizados de clientes, contactos, leads y oportunidades, los motivos de pérdida y la puntuación de leads. Usa los mismos servicios, validaciones y registros de auditoría que la aplicación.

Las lecturas aceptan también crm:settings:manage. Ningún conjunto concede crm:settings:manage, tampoco crm:full: se pide por su nombre.

Cómo usarla:

• Plan. Toda la herramienta pide el aplicativo CRM. Las etapas y los motivos de pérdida piden además Oportunidades, y la puntuación, Leads. Los campos de leads y de oportunidades piden la capacidad de su ficha.
• Los borrados exigen confirm: true. Sin él no se ejecuta nada y la respuesta (errorCode: CONFIRMATION_REQUIRED) explica qué pasará con los datos.
• delete_stage: si la etapa tiene oportunidades, moveToStageId es obligatorio y se mueven todas a esa etapa; las abiertas registran el cambio en su historial y su probabilidad no cambia. Un embudo conserva siempre dos etapas. list_pipelines da opportunityCount por etapa. Si no indicas pipelineId, se usa el embudo por defecto.
• delete_custom_field: sin valores, se borra. Activo y con valores, no se puede borrar: archívalo con update_custom_field e isArchived: true, que conserva los valores. Archivado y con valores, se borra y su valor se quita de todos los registros. Las operaciones de campos piden entityType (CLIENT, CONTACT, LEAD u OPPORTUNITY); key y type no cambian después de crear el campo, y una opción con valores se archiva, no se elimina.
• delete_loss_reason: un motivo en uso o del sistema se archiva y las oportunidades lo conservan; uno propio sin uso se borra.
• update_lead_scoring sustituye la configuración entera: lee antes con get_lead_scoring. preview_lead_scoring dice cuántos leads quedarían calientes, templados y fríos con unos umbrales, sin guardar nada.

Automatizaciones del CRM

crm_automations gestiona las automatizaciones sobre leads y oportunidades. Solo trabaja con automatizaciones del CRM, y marketing_automations, solo con las de Marketing: ningún token de un lado ve ni toca las del otro.

Cómo usarla:

• El orden recomendado es describe_catalog, validate, create y activate con confirm: true.
• describe_catalog devuelve los disparadores y acciones disponibles con su configuración, los límites del validador y los datos reales de tu organización: etapas de cada embudo, formularios de captación activos, etiquetas y estados de lead y de oportunidad. Así no hay que adivinar claves.
• validate comprueba una definición entera sin guardar nada, con los mismos validadores que el guardado y la activación, y devuelve valid, problems y notes en castellano.
• Las automatizaciones nacen en borrador. activate exige confirm: true y revalida todos los pasos; delete también exige confirm: true.
• update con steps y replace_steps sustituyen el flujo entero: solo en borrador o en pausa, y cancelan las ejecuciones en curso. Las ramas de un paso CONDITION viajan en branchTrueOrder y branchFalseOrder. Para un paso suelto, add_step, update_step y remove_step.
• bulk_set_status activa o pausa hasta 25 automatizaciones a la vez y devuelve el resultado de cada una en results y summary: un fallo no detiene al resto y reintentar solo los fallidos es seguro. Para activar exige confirm: true.
• test_trigger prueba el flujo con un contacto, como el botón «Probar flujo» de la aplicación. Con dryRun: true (por defecto) solo simula; con dryRun: false crea una ejecución de prueba real, marcada como prueba y fuera de las métricas. La prueba se hace siempre sobre un contacto, aunque el disparador sea de lead o de oportunidad.
• duplicate crea una copia en borrador con el nombre «X (copia)» o el que indiques.
• En el CRM, el paso SEND_EMAIL exige además EMAIL_MARKETING_VIEW, porque usa las plantillas de Marketing.
• create_from_template acepta crm-lead-cooling-alert, crm-form-lead-welcome, crm-negotiation-follow-up-task y crm-unresponsive-lead-reassign, que también devuelve list_templates.
• Lo que cambies por MCP se refleja solo en la página de automatizaciones del CRM que tengas abierta.

marketing_automations tiene las mismas operaciones de eficiencia: validate con EMAIL_MARKETING_VIEW y marketing:automations:view; replace_steps y bulk_set_status con EMAIL_MARKETING_EDIT, y duplicate con EMAIL_MARKETING_CREATE, las tres con marketing:automations:manage.

Analítica y cualificación de leads

crm_leads_stats es de solo lectura. Pide LEADS_VIEW y el scope crm:leads:view, y cada persona agrega solo las filas que vería en un listado. El período se indica con days (de 1 a 366, 90 por defecto) y se calcula en la zona horaria de la organización.

En crm_leads:

• set_temperature fija la temperatura del lead a mano (temperature) o la devuelve al cálculo automático (auto: true, incompatible con temperature). Fijarla marca temperatureIsManual, y la puntuación deja de recalcularla. Pide LEADS_EDIT y crm:leads:update.
• list acepta los filtros temperature, scoreMin y scoreMax (de 0 a 100), source, industry, leadFormId y utmSource.
• get incluye profileScore, behaviorScore, temperatureIsManual y firstContactedAt.

Motivos de pérdida y analítica de oportunidades

• crm_opportunities: list_loss_reasons devuelve el catálogo de motivos de pérdida de la organización (id, label, sortOrder, isSystem, isArchived, requiresCompetitor, requiresDetail e inUseCount); con includeArchived: true incluye los archivados. Pide OPPORTUNITIES_VIEW o LEADS_VIEW y el scope crm:opportunities:view o crm:leads:view.
• crm_opportunities_workflow: lose acepta lossReasonId, que tiene preferencia sobre el texto libre lostReason: el servidor valida el motivo, aplica sus exigencias de competidor y detalle y copia su etiqueta a lostReason. Acepta también postMortemNotes, para lo aprendido.

crm_opportunities_stats tiene tres análisis más, con period (30d, 90d o 365d; 90d por defecto) y el scope crm:opportunities:view:

Los nombres antiguos analytics_loss_reasons y analytics_top_contributors son operaciones obsoletas: ya no se anuncian en tools/list, pero siguen respondiendo con el mismo contrato que loss_reasons y by_owner hasta el 8 de enero de 2027, con un aviso en _notices.deprecatedOperation que nombra la sustituta.

Contraseñas de aplicación de otra persona

La herramienta observability del servidor utilia-crm deja ver y retirar las contraseñas de aplicación con las que una persona de tu organización conecta la unidad de red del Gestor de archivos. Es lo mismo que el bloque Contraseñas de aplicación de su ficha en Ajustes › Usuarios.

Las dos primeras exigen además el Gestor de archivos en el plan y el permiso concedido sobre toda la organización (alcance Todo). Quien no es Super Administrador solo ve y retira las de las personas que puede administrar: un Gerente con estos permisos, las de Vendedor, Asistente, Visualizador y Comercial Externo. Una persona de otra organización responde como si no existiera.

Seguridad y privacidad de la organización

La herramienta org_security_privacy del servidor utilia-crm hace lo mismo que Ajustes › Seguridad y Ajustes › Privacidad, con los mismos permisos y las mismas reglas. Ningún conjunto concede sus scopes: se piden por su nombre.

Cada escritura exige confirm: true y la confirmación en el móvil, así que la persona necesita tener activada la verificación en dos pasos: la primera llamada devuelve APPROVAL_REQUIRED con el número que hay que elegir en la aplicación, y después se repite la misma llamada con twoFactorApprovalId. La confirmación solo vale para esa operación con esos mismos datos.

Las respuestas no llevan nunca el enlace de descarga de una exportación: indican downloadAvailable cuando está lista.

Finanzas (servidor utilia-finance)

El servidor utilia-finance (POST https://os.utilia.ai/api/mcp/finance, nombre en el intercambio inicial: UTILIA Finance MCP) es el propietario canónico de la facturación, la tesorería y la fiscalidad de UTILIA OS. Expone 25 herramientas: 11 de facturación, tesorería y fiscalidad (con nombres y scopes crm:invoices:*, crm:treasury:* y crm:fiscal:* heredados de su origen en el CRM) y 14 exclusivas con scopes finance:*. La autorización OAuth usa el recurso /api/mcp/finance (ver Descubrimiento de OAuth) y los scopes se documentan en Scopes y recursos.

Estas 11 herramientas se publicaban también en el servidor utilia-crm. Desde el 8 de julio de 2026 esas copias están obsoletas: dejan de anunciarse en el tools/list del servidor CRM, aunque siguen respondiendo a tools/call con el mismo nombre, esquema y permisos hasta su retirada definitiva (prevista para el 8 de enero de 2027). Para cualquier flujo financiero conecta este servidor.

Facturación

Cobros recurrentes: comprobación previa y contacto de facturación

Un cobro recurrente con automation: "AUTO" emite y envía cada factura solo, pero solo puede enviarla si el cliente tiene un contacto de facturación principal y activo. Sin él, la factura se emite y el correo se omite. Por eso crm_subscriptions comprueba antes de cada cobro si la factura podrá emitirse, llegar al cliente y cobrarse, con las mismas reglas que la ficha del cobro recurrente en la aplicación.

check_readiness (solo lectura, no guarda nada) tiene dos formas:

• Con id: comprueba una suscripción guardada. Exige RECURRING_INVOICES_VIEW sobre su cliente, como get.
• Con clientId y automation (AUTO o DRAFT), y opcionalmente invoiceType (STANDARD o SIMPLIFIED), paymentMethod, bankIban y chargeMode (MANUAL o AUTO_STRIPE): comprueba los datos de un alta ANTES de crearla. Exige poder crear cobros recurrentes para ese cliente (RECURRING_INVOICES_CREATE con su alcance).

Las dos van con el scope crm:invoices:view o con crm:invoices:update (para quien solo puede crear cobros). Devuelven readiness y un nextStep general:

severity es BLOCKING cuando la factura no podrá emitirse y WARNING cuando se emitirá, pero no se enviará, no se cobrará sola o le faltará un dato de pago. Los códigos son:

Los nextStep nunca inventan datos: lo que tiene que confirmar la persona va como marcador entre ángulos (por ejemplo, '<NIF>'). El único valor real que proponen es el primero de suggestedEmails, los correos que se pueden dar de alta como contacto de facturación: el de la ficha del cliente, si el usuario tiene CLIENTS_VIEW, y los de sus contactos del CRM, si tiene CONTACTS_VIEW, cada uno con su alcance. Es una sugerencia: confírmala con la persona antes de usarla.

billingContact en create. data.billingContact (email y name opcional) garantiza, antes de generar la primera factura y en la misma transacción que la suscripción, un contacto de facturación principal y activo del cliente con ese correo: lo crea o, si ya existía, lo reactiva y lo pasa a principal. Es la doble puerta de siempre:

• El usuario necesita BILLING_CONTACTS_MANAGE. Sin él, la respuesta es un 403 con errorCode: "BILLING_CONTACTS_MANAGE_REQUIRED" y no se crea nada.
• El token necesita finance:billing-contacts:manage (también lo concede finance:full; en el servidor utilia-crm, donde sigue la copia obsoleta, vale crm:clients:update). Sin él, la respuesta es INSUFFICIENT_SCOPE antes de crear nada. crm:invoices:update permite crear el cobro, no el contacto, y finance:write tampoco lo concede.

Lo que devuelven las demás operaciones:

• create y update devuelven readiness (con el nextStep de cada incidencia; null si no se pudo calcular) y warnings, lo que se guardó distinto de lo pedido. Por ejemplo, el cobro con tarjeta guardado como manual porque la organización tiene apagado el cobro automático, o un contacto de facturación que ya existía y se ha reactivado como principal.
• El nextStep de create dice qué hacer después. Si la primera factura se emitió pero el correo se omitió por falta de contacto, indica el orden: primero billing_contacts: create y después crm_invoices_workflow: send con confirm: true. Enviarla antes volvería a omitir el correo.
• get devuelve readiness si la suscripción está ACTIVE o PAUSED, y null en las demás.
• list devuelve readinessIssueCodes en cada fila: los códigos de la comprobación de las suscripciones ACTIVE o PAUSED, calculados por lote. Lista vacía si no falta nada o si la suscripción ya no factura.

Flujo recomendado para un alta con automation: "AUTO":

{ "operation": "check_readiness", "clientId": "cli_123", "automation": "AUTO" }

Si devuelve BILLING_CONTACT_MISSING, confirma el correo con la persona y pásalo en el alta:

{
  "operation": "create",
  "data": {
    "name": "Mantenimiento web",
    "clientId": "cli_123",
    "automation": "AUTO",
    "startDate": "2026-11-01",
    "lines": [{ "name": "Cuota mensual", "unitPrice": 65, "taxType": "IGIC_7" }],
    "billingContact": { "email": "administracion@cliente.es" }
  }
}

La misma comprobación está en la API REST interna: GET /api/finance/recurring-invoices/:id/readiness y POST /api/finance/recurring-invoices/readiness, y el listado GET /api/finance/recurring-invoices trae readinessIssueCodes en cada fila.

Campos fiscales de las líneas (IGIC: exención y comerciante minorista)

Las líneas de crm_invoices (create/update) y de los presupuestos (crm_budgets, servidor utilia-crm) aceptan campos fiscales adicionales:

• taxType: en el sistema IGIC admite, además de los tipos con porcentaje, los valores EXEMPT (exenta) y NOT_SUBJECT (no sujeta).
• igicOperationType: clasificación de la línea en el régimen especial del comerciante minorista del IGIC. En ventas: IGIC_RETAIL (venta minorista exenta; exige taxType: "EXEMPT" y la causa minorista la aplica el motor por defecto) o IGIC_GENERAL. Exige que la organización tenga el régimen declarado en su configuración fiscal (igicRetailerMode distinto de IGIC_RETAILER_NONE).
• exemptionReason: causa estructurada de la exención, obligatoria con taxType: "EXEMPT" en IGIC salvo en el régimen del pequeño empresario. Valores: EXEMPT_IGIC_RETAILER, EXEMPT_IGIC_INTERNAL, EXEMPT_EXPORT, EXEMPT_OTHER y EXEMPT_IGIC_SMALL_BUSINESS (régimen del pequeño empresario del IGIC, con la mención «Exención franquicia fiscal»). La causa decide la mención legal que se imprime en la factura. Dentro de un periodo del régimen del pequeño empresario, el motor pone esa causa en las líneas exentas sin causa de un documento IGIC y rechaza las líneas IGIC con cuota, también IGIC_0. El estado del régimen se consulta con finance_settings: get_small_business_regime.
• exemptionNote: texto explicativo de la exención (máximo 300 caracteres), obligatorio con exemptionReason: "EXEMPT_OTHER"; viaja a la mención legal impresa.

En presupuestos, estos campos se propagan a la factura o a la suscripción al convertir. Las líneas de gasto (expenses) aceptan también igicOperationType con un tercer valor propio, IGIC_COMMON (gasto común a las dos actividades); en un gasto clasificado como IGIC_RETAIL la cuota de IGIC soportada no es deducible.

Tesorería y fiscalidad

Captura de rectificativas recibidas

fiscal_capture permite consultar y guardar los hechos fiscales de una rectificativa recibida asociada a un gasto. La captura conserva la referencia original, la causa, las fechas, la elección de período y las pruebas de deducción. No modifica los importes del gasto ni el documento original, no genera pagos o asientos y no presenta declaraciones.

Se requieren el aplicativo finance y la capacidad finance.tax_models. Mientras Impuestos esté en «Próximamente», fiscal_capture no está disponible para tu organización. El servicio comprueba los permisos y el alcance de cada gasto y referencia; ser Super Administrador no sustituye los scopes del token ni el plan. Las listas OR del catálogo no reemplazan estas comprobaciones conjuntas. No se ha añadido una excepción para tokens antiguos. finance:read y finance:write por sí solos no conceden crm:fiscal:manage; solicita los scopes necesarios.

El SDK usa POST /api/mcp/finance con el token OAuth autorizado para ese servidor. No hay ruta REST externa equivalente.

Ejemplo de input sin confirmar, conservado para revisión:

{
  "expectedRevision": null,
  "cause": "RETURN",
  "causeOccurredOn": null,
  "causeKnownOn": null,
  "original": { "expenseId": "expense-original" },
  "amountRepresentation": "DIFFERENCE_SIGNED",
  "settlement": {
    "route": "UNRESOLVED",
    "targetFiscalPeriodId": null,
    "reimbursementEvidenceIds": []
  },
  "evidenceFileIds": [],
  "confirm": false
}

Envía expectedRevision: null en la primera captura; para editar, consulta la captura y usa su revisión. Las fechas y referencias que admiten null deben enviarse explícitamente: omitirlas no equivale a desconocerlas. confirm es un booleano y no acepta "false" como texto. Confirmar requiere fechas reales y hechos explícitos; no acredita automáticamente su efecto fiscal.

original acepta exactamente una referencia: { expenseId } o { external: { number, issuedOn, supplierTaxId, evidenceFileId } }. Una referencia externa puede guardarse para revisión; no prueba por sí sola que el cálculo esté cubierto. Los archivos deben pertenecer a la organización y ser accesibles al actor. No se aceptan invoiceId, autoría, organización, sellos ni importes del gasto en esta captura recibida.

deduction es opcional; si lo envías debe contener originalUse, originalFiscalPeriodId, evidenceFileIds, previousAdjustmentReferences y allocations. Cada asignación lleva originalTaxId, previouslyDeducted y deductibleAfterCorrection, con importes decimales como cadenas, por ejemplo "210.00". No deduzcas estos hechos de la deducibilidad actual del gasto. En recibidas, reimbursementEvidenceIds debe estar vacío.

Consulta y guardado devuelven la misma vista: { capture: { id, revision, confirmedAt } | null, input: objeto | null, status: "COMPLETE" | "REVIEW_REQUIRED", reasons: string[] }. Sin captura, capture e input son null. Revisa siempre status y reasons: conservar los hechos no habilita todas las ramas fiscales ni supone que una declaración esté lista para exportar.

En JavaScript, usando como input el objeto anterior:

const { data: actual } = await sdk.mcp.fiscalCapture.getExpenseRectification(expenseId);
const { data: guardada } = await sdk.mcp.fiscalCapture.saveExpenseRectification(
  expenseId, { ...input, expectedRevision: actual.capture?.revision ?? null },
);
const { data: lote } = await sdk.mcp.fiscalCapture.saveExpenseRectifications([
  { expenseId, input: { ...input, expectedRevision: guardada.capture?.revision ?? null } },
]);

En Python, entrada es el diccionario del ejemplo; los mismos métodos están disponibles sin await en UtiliaSDKSync:

from utilia_sdk.mcp.fiscal_capture_types import ExpenseRectificationInput, ExpenseRectificationBatchItem
 
actual = await sdk.mcp.fiscal_capture.get_expense_rectification(expense_id)
entrada["expectedRevision"] = actual.capture.revision if actual.capture else None
guardada = await sdk.mcp.fiscal_capture.save_expense_rectification(
    expense_id, ExpenseRectificationInput.model_validate(entrada),
)
lote = await sdk.mcp.fiscal_capture.save_expense_rectifications([
    ExpenseRectificationBatchItem(expense_id=expense_id, input=ExpenseRectificationInput.model_validate(entrada)),
])

El lote es secuencial y parcial: un fallo no revierte los elementos guardados ni impide procesar los siguientes. Devuelve succeeded, failed y summary: { total, ok, failed }. Cada éxito lleva index y data: { expenseId, id, revision, status, reasons }; cada fallo lleva index, code y message. Usa el índice para identificar la entrada que falló. El resumen no incluye hechos externos, fotografías de datos ni historial.

Para un reintento, conserva los mismos hechos y expectedRevision. Cada intento vuelve a comprobar el acceso y la equivalencia en el servicio; no hay atomicidad del lote ni una cola o recibo adicional. Un cambio de hechos, revisión o contexto fiscal puede dar conflicto y exigir una nueva consulta. Los errores fiscales estables son VAT_RECTIFICATION_CAPTURE_INVALID, VAT_RECTIFICATION_CAPTURE_CONFLICT, VAT_RECTIFICATION_EFFECTS_REVIEW_REQUIRED y VAT_RECTIFICATION_PERIOD_LOCKED. En llamadas individuales viajan en errorCode y en error.code; el SDK JS conserva errorCode y Python error_code. En el lote viajan en failed[].code. Los fallos de acceso usan INSUFFICIENT_SCOPE, FORBIDDEN o NOT_FOUND, sin datos de otra organización.

Contabilidad

Gastos, proveedores, pagos e informes

Crear un gasto desde un documento digitalizado exige varios scopes a la vez. promote_to_expense requiere finance:payments:view, finance:expenses:create y finance:expenses:approve. La conversión solicita un gasto aprobado; si el documento está en otra divisa, el gasto queda en borrador hasta confirmar su importe en euros. No registra un pago al proveedor.

En resolve_duplicate, action: 'keep_both' conserva el documento como una factura distinta y crea el gasto con la misma regla. Exige los tres scopes anteriores y finance:payments:update. action: 'discard' exige finance:payments:view, finance:payments:update y finance:payments:delete. Ambas acciones requieren confirm: true. Estos scopes se suman a los permisos y al alcance del usuario y al acceso de su organización a Finanzas. Los conjuntos finance:read y finance:write no conceden el scope de aprobación.

Los vínculos del proveedor exigen el scope del otro lado. list_tasks devuelve tareas del CRM, list_payments documentos de Finanzas y get_counterpart la identidad de un cliente, así que un token de proveedores no basta: hace falta además el scope de aquello que se lee. La conjunción sale sola, porque los scopes que hacen VISIBLE la herramienta siguen siendo solo de Finanzas. list_tasks exige también el aplicativo CRM en el plan, no solo Finanzas. get_counterpart exige los CUATRO permisos de los dos lados (CLIENTS_VIEW, SUPPLIERS_VIEW y los dos de datos sensibles) y devuelve null sin decir por qué: el mismo null cubre «no tiene NIF», «ninguno casa» y «queda fuera de tu alcance», porque distinguirlos convertiría la operación en un comprobador de NIF ajeno. En list_payments y en finance_payments con supplierId, el NIF leído del documento (supplierNif) solo viaja con SUPPLIERS_VIEW_SENSITIVE: sin ese permiso la clave no existe en la fila.

Cobro con tarjeta, comisiones y ajustes

refund_manual registra una devolución hecha fuera de la pasarela de UTILIA OS. Su source dice por dónde: MANUAL_BANK (transferencia), MANUAL_CASH (efectivo) o EXTERNAL_GATEWAY («Pasarela de pago externa»: la devolución ya se hizo en una pasarela ajena a UTILIA OS, por ejemplo la cuenta de Stripe propia de la empresa). Con EXTERNAL_GATEWAY:

• UTILIA OS no mueve dinero: solo registra la devolución.
• referenceNumber es obligatorio: el identificador de la devolución en esa pasarela (por ejemplo, re_...), hasta 120 caracteres sin espacios, que no puede repetirse en la organización.
• Solo se puede devolver lo que se cobró fuera de la pasarela de UTILIA OS. Lo cobrado con ella se devuelve con refund_create.
• method dice cómo devolvió el dinero la pasarela externa (CARD, por defecto, TRANSFER o CASH) y decide la cuenta de tesorería del asiento.

Con createRectifyingInvoice: true, tanto refund_create como refund_manual emiten además la rectificativa por diferencias. El código lo decide el servidor: R1 para la ordinaria y la simplificada con destinatario identificado, R5 para la simplificada sin destinatario. Si no se puede calcular exacta al céntimo, el reembolso se rechaza sin registrar nada.

El régimen especial del pequeño empresario o profesional (REPEP) del IGIC se gestiona con tres operaciones de finance_settings:

Solo pueden declararlo los autónomos con un régimen fiscal canario. Los periodos no se pueden solapar ni contradecir ventas IGIC ya emitidas (eso se corrige con rectificativas), y las escrituras devuelven avisos no bloqueantes. UTILIA OS nunca abre, cierra ni mueve un periodo por su cuenta: avisa, y lo decide la persona.

finance_settings: get_stripe es de solo lectura. Devuelve si la pasarela está disponible, si la organización puede cobrar y por qué no, el estado de la cuenta conectada, su país y su divisa, y los requisitos que Stripe tiene pendientes, ya traducidos al castellano. Con eso el copiloto puede responder «tu cuenta está conectada pero le falta este documento», que antes no podía responder en absoluto.

Lo que no hay, y no es un olvido: ni alta ni desconexión por MCP. El alta exige que una persona teclee en un formulario alojado por Stripe con verificación de identidad, así que ofrecerla sería prometer lo que no hay. Y la desconexión es en la práctica irreversible: rehacerla obliga a repetir el alta entera, y eso no debe estar a un mensaje de distancia. Es el mismo criterio de payment_methods: setup_intent.

Divergencia de permiso dentro de la herramienta: get_stripe acepta configurar los pagos con tarjeta o verlos, en lugar del permiso de ajustes de Finanzas que gobierna al resto de sus operaciones.

La facturación electrónica (Facturae, UBL y envíos a FACe) está retirada desde el 6 de julio de 2026: la herramienta invoices_einvoicing no se publica en tools/list y, si se invoca por su nombre, responde que no está disponible.

Operaciones bajo supervisión humana

Estas operaciones están anotadas con supervisedByHuman en el catálogo: el cliente MCP debe pedir confirmación expresa al usuario antes de ejecutarlas. Los scopes del token limitan el dominio finance operación a operación: el servidor comprueba en cada llamada que el token porta el scope granular de la operación y la deniega con un error explícito si no lo lleva. La autorización final exige además que el usuario dueño del token tenga el permiso correspondiente en UTILIA OS: scope y permiso son condiciones independientes y ambas deben cumplirse. Las operaciones de esta tabla exigen scopes que quedan fuera de los conjuntos finance:read y finance:write (las acciones post, close, approve, delete, manage, reprocess, submit y liquidate hay que concederlas explícitamente o usar finance:full).

Las filas marcadas con Próximamente son de funciones en «Próximamente»: ver el aviso del principio de esta sección.

Dos operaciones mueven dinero real: crm_invoices_workflow: charge, que cobra con la tarjeta guardada del cliente, y refund_create, que devuelve por la pasarela. Las dos exigen confirm: true, el aplicativo de pagos con tarjeta y su permiso (INVOICES_CHARGE para cobrar, STRIPE_PAYMENTS_REFUND para devolver). Fuera de ellas, ninguna herramienta de este servidor mueve dinero ni desconecta bancos. Los presupuestos (crm_budgets*) son un documento comercial previo a la venta y viven solo en el servidor utilia-crm.

RRHH: festivos y calendario laboral

La herramienta attendance del servidor utilia-rrhh (POST https://os.utilia.ai/api/mcp/rrhh) decide qué festivos cuentan para tu empresa a partir de su ámbito territorial. Las mismas operaciones siguen publicadas por compatibilidad en workplace, del servidor utilia-crm, con el prefijo attendance_.

Un festivo cuenta para la empresa si su clave de ámbito (scopeKey) está en la lista de la empresa. Sin comunidad autónoma elegida, esa lista es ['ES', 'COMPANY']: solo cuentan los festivos nacionales y los propios de la empresa.

Las cuatro exigen además el permiso ATTENDANCE_MANAGE_HOLIDAYS y el aplicativo RRHH contratado. Cada festivo devuelve scopeKey, scopeLabel (su rótulo en castellano) y applicable.

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "attendance",
    "arguments": {
      "operation": "holidays_set_scope",
      "region": "ES-CN",
      "island": "GC",
      "locality": "Las Palmas de Gran Canaria"
    }
  }
}

Lo que conviene saber:

• Los festivos municipales no se cargan: los publica cada ayuntamiento y no hay una fuente que los cubra. holidays_import lo dice en el campo notice de su respuesta; se añaden a mano con holidays_create.
• El ámbito no se pasa al cargar: sale del que tiene declarado la empresa.
• Una isla fuera de Canarias se rechaza con un error 400.
• Elegir el ámbito y cargar el año son escrituras: cambian qué días descuentan jornada a toda la plantilla, así que un token de solo lectura no puede hacerlas.
• Quitar los festivos de otros ámbitos no se puede hacer por MCP. Es un borrado irreversible y solo está en Ajustes › RRHH › Festivos, necesitas entrar con tu cuenta, con vista previa y confirmación.

En los SDK, la superficie es sdk.mcp.attendance.holidays: getScope(), setScope(), import() y list() en JavaScript, y get_scope(), set_scope(), import_year() y list() en Python.

Cambios de contrato de septiembre de 2026

Los conjuntos de escritura ya no borran en el gestor de archivos

dev:write y crm:write dejan de poder eliminar archivos, versiones y carpetas: para borrar hace falta dev:files:full o crm:files:delete. Ninguno de los dos conjuntos de escritura prometía borrar, igual que ya excluían el resto de los borrados del producto. A cambio, dev:write incluye ahora dev:files:manage, para que los tokens existentes sigan pudiendo crear carpetas y renombrar archivos.

Los datos bancarios y fiscales tienen scope propio

La pantalla de autorización los muestra con su nombre y con aviso, porque con el IBAN de un proveedor se puede desviar un pago y las condiciones pactadas con un cliente son información comercial reservada.

Sin el scope, esas claves no existen en la respuesta: no llegan vacías ni nulas, porque un nulo en un campo fiscal se leería como «esta empresa no tiene NIF». Si tu integración compara candidatos lado a lado, tiene que tolerar la clave ausente. Los tokens emitidos antes del 2 de septiembre de 2026 conservan esos datos hasta el 2 de marzo de 2027; las autorizaciones nuevas no los conceden sin nombrarlos.

El recorte afecta a:

• suppliers: list, get, search_by_tax_id, check_duplicate, deduplicate_preview, merge, list_payments, create y update.
• finance_payments: list, get, check_duplicate y update.
• crm_clients: list, get, create, update, check_duplicate, deduplicate_preview y merge, y el historial de crm_clients_info. En la previa y en la fusión de clientes se retira además el NIF-IVA, que solo se publica ahí. Los recuentos de cada ficha viajan siempre.
• El volcado del reconocimiento de documentos (extractedData): el recorte cubre trece nombres de clave a cualquier profundidad (el NIF, el NIF-IVA, el IBAN, la cuenta, el SWIFT y el BIC del proveedor, con sus variantes). receiverNif, que es el NIF de tu propia organización, no se recorta.
• check_duplicate de finance_payments y de suppliers: sin SUPPLIERS_VIEW_SENSITIVE, el NIF desaparece de candidates y de expenseCandidates. La detección de duplicados funciona igual, porque se basa en el número, la fecha, el importe y la confianza.

create_many y update_many no aparecen porque cada elemento vuelve en versión corta, sin esos campos.

Archivos: permiso para vincular y scope por tipo de ficha

crm_files_management gobierna upload, link, unlink y bulk_link con FILE_MANAGER_LINK_CRM en lugar de CLIENTS_EDIT, porque admite fichas de varios módulos: las siete del CRM (client, contact, lead, project, opportunity, budget e interaction) y la del proveedor (supplier). El rol Asistente pierde esas cuatro operaciones por MCP, que tampoco podía hacer desde la aplicación.

Cada tipo de ficha exige además su propio scope, comprobado por parámetro:

get_linked_entities recorta también la lista que devuelve: un token del CRM no ve el nombre del proveedor al que cuelga un archivo. El gestor de archivos añade fm_virtual_folders: get_suppliers_tree, con el árbol de la carpeta virtual «Proveedores», y admite supplier en get_entity_files, link_files, unlink_file y unlink_files.

expenses: document_attach ya no copia el justificante: recibe el identificador de un archivo del gestor al que tengas acceso y lo cuelga del gasto. Sigue exigiendo confirm: true porque sustituye el justificante anterior. expenses: document_get añade source (file o legacy), fileId, fileName, mimeType y size; en los justificantes históricos, el tipo y el tamaño llegan nulos. El archivo queda compartido entre el gestor y el gasto, y un justificante no se puede retirar, solo sustituir.

Scopes nuevos

Las previas por reglas (deduplicate_preview de clientes y contactos) son lecturas y se piden con el scope de ver. La previa de merge, en cambio, la ejecuta la misma operación destructiva y exige el scope de fusionar.

Operaciones nuevas

Fusión de duplicados en el CRM:

• crm_clients: deduplicate_preview: grupos de clientes duplicados según las reglas (mismo NIF; sin NIF, mismo correo, mismo dominio o mismo nombre y ciudad), con el superviviente propuesto, los recuentos de cada ficha y lo que se movería. No escribe nada: basta CLIENTS_VIEW y crm:clients:view. Si alguna ficha de un grupo queda fuera de tu alcance de fusión, el grupo entero se omite.
• crm_clients: deduplicate: fusiona esos grupos. Exige confirm: true, CLIENTS_MERGE y crm:clients:merge. survivorIds elige quién sobrevive en cada grupo (hasta 500) y groupIds acota los grupos (hasta 100); los que ya no son duplicados vuelven en ignoredGroupIds sin error.
• crm_clients: merge: fusiona las fichas que eliges a mano, de 1 a 20 duplicadas; es la salida cuando el NIF está mal escrito en una y ninguna regla las junta. Sin confirm devuelve la previa con dryRun: true y no escribe nada, pero exige igualmente el permiso y el scope de fusionar. La ficha que sobrevive recibe contactos, oportunidades, proyectos, presupuestos, tareas, facturas, autorizaciones de cobro, accesos al portal, archivos, carpetas e interacciones, y rellena sus campos vacíos con los datos de las demás.
• Dos opciones de merge exigen alcance total sobre el permiso de fusionar: allowDifferentTaxId, que une dos NIF distintos (nunca si las dos fichas tienen facturas emitidas), y allowPortalAccessMerge, que deja que los interlocutores externos de una empresa vean los documentos de la otra.
• crm_contacts y crm_leads tienen el mismo juego de operaciones con sus propios scopes. En contactos, dos fichas con usuario del portal no se pueden unir, y si alguna no puede recibir correos, la que sobrevive tampoco podrá.
• crm_leads: find_duplicates lista los grupos de leads duplicados con su tipo de coincidencia, su puntuación y el valor que los une, con LEADS_VIEW y crm:leads:view. check_duplicate hace lo contrario: contrasta un candidato antes de darlo de alta, y excludeLeadId evita que una ficha se detecte a sí misma al editarla.
• crm_contacts: search_by_email localiza un contacto activo por su correo principal o secundario, sin distinguir mayúsculas. Devuelve como mucho uno, y found: false tanto si no hay ninguno como si el que hay queda fuera de tu alcance.

Proveedores:

• suppliers: accounting_accounts: subcuentas contables 400 del proveedor. Exige Finanzas con la capacidad de Contabilidad, los permisos de ver contabilidad y de ver proveedores, y el scope finance:accounting:view. Está en «Próximamente», como la Contabilidad.
• suppliers: create y update aceptan logoFileId, el identificador de una imagen del gestor. En la edición, omitirlo deja el logotipo como está y enviarlo a nulo lo retira.
• La actividad del proveedor (get_interaction_thread, list_interaction_activities, list_interaction_attachments, log_interactions_many, attach_to_interaction, remove_interaction_attachment, schedule_meeting, complete_meeting, cancel_meeting y los filtros nuevos de list_interactions) se explica en La actividad de un proveedor, sin salir del copiloto.

CRM y calendario:

• crm_clients: get_counterpart: el proveedor que comparte NIF con el cliente, o nada. Exige los dos aplicativos y los cuatro permisos de los dos lados, sensibles incluidos; si falta cualquiera, la respuesta es «no encontrado», igual que si el cliente no existiera.
• calendar_events_workflow: get_unified acepta sources para acotar el calendario unificado a algunas de sus catorce fuentes. supplier_meeting exige además el scope de la actividad del proveedor.
• Personas de fuera de la organización en un evento. calendar_events en create y update, y calendar_events_workflow en add_attendees, aceptan externalAttendees (lista de { email, name? }, hasta 50) y externalMessage. Cada persona recibe por correo la fecha, la hora y el lugar del evento con el archivo de calendario y, si el evento tiene videollamada (y Meet está en el plan), el enlace para entrar. Invitar nunca crea una videollamada. En update se añaden, nunca sustituyen. Exige el permiso CALENDAR_INVITE o CALENDAR_EDIT, ser quien creó el evento (o administrador) y el scope dev:calendar:invite o dev:calendar:update. Si el correo de alguien no puede salir, queda invitado «por enviar» y la respuesta lo dice. Todo se comprueba antes de guardar nada. Un correo que pertenece a la organización se invita como interno, y a quien ya estaba invitado no se le vuelve a escribir.
• calendar_events_workflow: remove_external_attendee y resend_external_invitation retiran a esas personas (reciben el aviso de cancelación) o les reenvían la invitación. Se identifican por email, por invitationId o con una lista externalAttendees, varias en una llamada; el reenvío respeta el margen de cinco minutos entre correos a la misma persona. Exigen CALENDAR_INVITE o CALENDAR_EDIT y el mismo scope (y Meet en el plan para las invitaciones de un evento con videollamada). calendar_events: get devuelve externalAttendees con su estado y hasVideoLink, y hasVideoCall del evento.

Dos herramientas transversales nuevas, search y notifications, tienen página propia.

Los SDK

Los SDK cubren estos cambios desde la versión 2.27.0. Dos avisos:

• El mensaje de los errores de una herramienta ya no se pierde. El SDK lee las tres formas de error que conviven y añade la pista al mensaje.
• El error del SDK trae errorCode y details. errorCode es el código exacto de la herramienta y details, su detalle: requiredScopes cuando falta un scope, field cuando falta un parámetro, resource y retryAfterSeconds. code, en cambio, sigue siendo VALIDATION_ERROR en los errores de herramienta, también en la versión actual: para distinguir un «no encontrado» de una regla de negocio, mira errorCode.

Cambios de contrato de octubre de 2026

Desde el 20 de octubre de 2026, todas las herramientas comparten la misma forma de responder, de paginar y de rechazar, y se añaden operaciones que hasta ahora solo existían en la aplicación.

Errores con motivo

Los rechazos por plan, permisos, scope o reglas de negocio llegan como resultado de la herramienta (isError: true), no como error del protocolo. Una llamada mal formada (una herramienta que no existe en el servidor o parámetros que no cumplen su esquema) sí puede responder con el error JSON-RPC -32602. En los resultados, además del mensaje, error.details.errorCode dice el motivo y error.hint, qué hacer:

Listados más ligeros y con cursor

Los listados de las herramientas principales (clientes, contactos, leads, oportunidades, proyectos, tareas e interacciones del CRM, calendar_events, tickets, issues, projects, ai_studio, chat_channels, chat_messages, las de Marketing, crm_invoices, crm_subscriptions y el gestor de archivos, entre otras) aceptan:

• response_format: concise (por defecto) da los campos con los que se identifica y decide cada fila; detailed, la fila completa de siempre. La vista resumida nunca enseña nada que la completa no enseñaría.
• limit con un máximo declarado en su esquema y cursor. offset y page se siguen aceptando donde existían.

La respuesta trae las filas en items y la paginación en pageInfo (nextCursor, hasMore, pageSize, responseFormat y detailHint). nextCursor es nulo en la última página.

{
  "name": "crm_clients",
  "arguments": { "operation": "list", "limit": 50, "response_format": "concise" }
}

Avisos, siguiente paso y reintentos

• _notices: avisos que no son error. ignoredFields lista los parámetros que la herramienta no conoce, con el nombre válido más parecido; deprecatedOperation avisa de que la operación es obsoleta y nombra la sustituta; reauthorization dice qué scope pedir al volver a autorizar cuando la llamada solo ha pasado por una compatibilidad que caduca.
• nextSteps: las creaciones y los cambios de estado de los flujos principales sugieren el paso siguiente como tool, operation, why y, si hace falta, args (presupuesto creado, generar el PDF y enviarlo; ticket de error, convertirlo en elemento de trabajo). Solo aparecen los pasos que tu plan, tus permisos y el token permiten.
• idempotencyKey y clientOperationId son intercambiables. Si la herramienta declara uno, el otro se acepta en su lugar, también dentro de los elementos de un lote. Si mandas los dos con valores distintos, la llamada se rechaza.

Operaciones obsoletas

No se anuncian en tools/list, pero siguen respondiendo hasta el 8 de enero de 2027 con un aviso en _notices.deprecatedOperation. Cambia a la sustituta:

Herramientas retiradas

Responden con errorCode: TOOL_RETIRED sin ejecutar nada, y el mensaje da la operación equivalente:

Verificación en dos pasos para lo más delicado

En la aplicación, quien no tiene la verificación en dos pasos confirma las acciones delicadas con su contraseña o con la sesión abierta. Desde un asistente de IA no hay ninguna de las dos, así que estas operaciones exigen tenerla activada y se confirman en el móvil:

• Crear y renovar credenciales y claves de API: api_credentials (create, rotate, org_keys_create y org_keys_rotate) y org_integrations_settings (api_keys_create, api_keys_regenerate). También ampliar una clave de la organización con org_keys_update (más permisos, más caducidad o cambiar de responsable).
• En team_management: dar el rol Super Administrador, conceder permisos críticos (sueltos, por lotes, al copiar los de otra persona o al aplicar una plantilla), cambiar el correo de acceso de otra persona y dar, ampliar o devolver el acceso de la asesoría (advisors_invite, advisors_update cuando amplía lo que ve o añade un responsable, y advisors_restore).
• Todas las escrituras de org_security_privacy (ver Seguridad y privacidad de la organización).

Sin la verificación en dos pasos, la llamada se rechaza con TWO_FACTOR_NOT_ENABLED antes de pedir nada al móvil. Con ella, sigue el ciclo de APPROVAL_REQUIRED y twoFactorApprovalId. La aplicación no cambia.

Scopes nuevos de octubre

Ninguno entra en un conjunto, salvo crm:settings:view: se piden por su nombre y la persona los ve nombrados al autorizar.

Operaciones nuevas de octubre

Gestión del equipo (team_management, servidor utilia-crm), igual que Ajustes › Usuarios y Ajustes › Permisos:

Nadie modifica sus propios permisos por esta vía, y los permisos protegidos solo los concede, retira o reemplaza un Super Administrador. users_deactivate y users_delete siguen dando de baja sin traspasar nada, y lo avisan.

Acceso de asesoría

La misma herramienta da acceso a la persona de la asesoría o gestoría de la empresa, igual que el bloque «Tu asesoría» de Ajustes › Usuarios. No ocupa usuario del plan: cuenta en los accesos de asesoría. Lo que ve se decide por áreas, cada una con su nivel y con su aplicativo en el plan:

Dentro de las áreas que se comparten, overrides afina permiso a permiso (permission y enabled) con los códigos de advisors_catalog. Solo se comparte lo que quien da acceso tiene con alcance «Todo».

users_create y users_update no dan ni quitan el rol ASESORIA: responden ADVISOR_ROLE_IMMUTABLE y remiten a advisors_invite. Los errores propios son los de Ajustes: QUOTA_EXCEEDED_ADVISOR_SEATS (cupo lleno), MODULE_NOT_ENABLED (área fuera del plan), PERMISSION_NOT_ALLOWED_FOR_ADVISOR, GRANT_AUTHORITY_EXCEEDED, ADVISOR_EMAIL_EXISTS y ADVISOR_FOLDER_IN_TRASH.

En advisors_update, la carpeta que ya tiene no hace falta reenviarla: sin folderId ni newFolderName se conserva. La misma carpeta con el mismo nivel se queda tal cual, también si está en «Eliminados recientemente»; cambiar el nivel de Documentos con la carpeta allí responde ADVISOR_FOLDER_IN_TRASH (409): restáurala o elige otra.

Ajustes de la organización (organization_settings, servidor utilia-crm). Cada bloque exige su aplicativo en el plan:

Las lecturas piden org:settings:view (el aviso de Meet acepta también crm:meet:view) y las escrituras, org:settings:update.

Otras herramientas:

• portal_access: list_portal_permissions dice qué permisos del portal del cliente se pueden conceder. Pide PORTAL_MANAGE_PERMISSIONS, PORTAL_INVITE_USER o PORTAL_MANAGE_CLIENT_ACCESS, y crm:portal:view.
• suppliers (servidor utilia-finance) gestiona los campos personalizados de los proveedores y de sus personas de contacto: list_custom_fields, create_custom_field, update_custom_field, reorder_custom_fields y delete_custom_field. Leer pide el permiso de ver proveedores o de ver los campos; escribir, CUSTOM_FIELDS_MANAGE y finance:custom-fields:manage.
• tickets_workflow: convert_to_issue convierte un ticket en elemento de trabajo; los detalles, en Herramientas MCP de tickets.
• ai_studio: use sustituye las variables de un prompt y suma un uso; ver Herramienta MCP de AI Studio.
• crm_settings y org_security_privacy son herramientas nuevas: ver Configuración del CRM y Seguridad y privacidad de la organización.

Gestor de archivos: Eliminados recientemente

Desde el 22 de octubre de 2026, lo que una persona elimina por MCP ya no se destruye en el acto: pasa 30 días en «Eliminados recientemente», igual que en la aplicación, y después se borra para siempre con su contenido, sus miniaturas y sus versiones. Las operaciones de borrado se llaman igual; cambia lo que responden:

• fm_files_manage: delete y batch_delete responden outcome: "TRASHED" con purgeAfter (fecha ISO del borrado definitivo); delete añade retentionDays. Si el archivo sigue en uso en un sitio que la persona no puede editar, outcome: "IN_USE", como hasta ahora, con los sitios en referencedBy (en batch_delete, en el error de ese archivo). physicallyDeleted se mantiene por compatibilidad y llega a false.
• remove_from_folder y batch_remove_from_folder responden outcome: "REMOVED" si el archivo sigue en otros sitios y "TRASHED", con purgeAfter, si esa carpeta era su última ubicación.
• fm_folders_manage: delete, con o sin cascade, manda la carpeta a «Eliminados recientemente» con lo que solo estaba en ella, y responde outcome: "TRASHED" y purgeAfter.
• fm_virtual_folders: unlink_file y unlink_files exigen confirm: true cuando quitar el vínculo deja el archivo sin ningún sitio y lo manda a «Eliminados recientemente».

Tres operaciones nuevas recorren «Eliminados recientemente» (en el servidor utilia-crm, por ejemplo):

restore y purge reciben un elemento (id, con kind: "folder" si es una carpeta; file por defecto) o un lote de hasta 50 en items: [{ kind, id }]. Una carpeta se restaura o se borra entera, con lo que se eliminó con ella. La respuesta trae results elemento a elemento, con outcome (RESTORED o FAILED al restaurar; PURGED, QUEUED o FAILED al borrar), errorCode y message, y failedItems si alguno falla. restore añade restoredTo (dónde ha quedado), renamedTo (si una carpeta cambió de nombre por estar el suyo ocupado) y uploadedBy. QUEUED cuenta como hecho: ya no se puede restaurar y termina de borrarse en cuanto responde el almacenamiento.

Qué ve y qué puede borrar cada persona lo decide el mismo servicio que la aplicación. Ve lo que eliminó y lo que subió; lo que eliminaron otras personas, solo con FILE_MANAGER_MANAGE_TRASH («Gestionar lo que eliminan otros») y dentro de su alcance. Borrar antes de tiempo es de quien lo subió (o creó la carpeta), del Super Administrador y de ese permiso; quien eliminó algo ajeno puede restaurarlo, pero no borrarlo. Lo que tiene bloqueado el acceso de la IA no aparece en list_trash y responde como inexistente. «Eliminar todo» no se publica por MCP: una destrucción masiva sin vuelta atrás se queda en la aplicación.

Al eliminar siguen las negativas de siempre, con su errorCode: FILE_IS_WORM_PROTECTED (la copia de lo que recibió el cliente), FILE_IS_ISSUED_INVOICE_ORIGINAL, FILE_IS_VAT_ACCREDITATION_EVIDENCE y, para carpetas, FOLDER_IS_SYSTEM. La guía de uso está en Eliminar y recuperar archivos.

Si quien conecta la IA es de la asesoría

Una persona de la asesoría trabaja solo en la carpeta que la empresa le comparte, y su IA tiene las mismas reglas que ella en la aplicación y en la unidad de red:

• Eliminar, mover, renombrar o sustituir (delete, batch_delete, remove_from_folder, batch_remove_from_folder, move, batch_move, rename, upload_version, restore_version, delete_version, edit_content, patch): solo con el nivel «También subir» y solo lo que subió o metió ella en su carpeta compartida. Lo de la empresa es de solo lectura para ella, y nada sale de su carpeta: mover fuera, o a Inicio, se niega.
• «Eliminados recientemente»: list_trash solo trae lo que ella eliminó de su carpeta compartida; restore lo devuelve solo a esa carpeta y, si la carpeta no está disponible (la empresa la ha eliminado o ya no la comparte), falla con TRASH_RESTORE_NO_DESTINATION. purge nunca: responde TRASH_PURGE_FORBIDDEN. Con «Ver y descargar», la lista llega vacía.

Solo se explica la negativa sobre lo que la asesoría ve (su carpeta o lo que subió ella); un archivo de la empresa que no ve responde como siempre, sin decir que existe.

Referencias

• Primeros pasos con MCP.
• Migración del MCP de integraciones de v1 a v2, si tu integración usaba la antigua herramienta integrations.
• Poner al día una cartera de clientes: lotes, logotipos, fusión con previa y espejo incremental.
• Scopes y recursos de OAuth.
• Buscador global y avisos por MCP.
• Herramienta MCP de tickets.