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 › Integraciones › Aplicaciones externas, 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.

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 el ciclo de vida de las credenciales v2 de tu organización. Hay tres tipos:

• PERSONAL: va atada a un usuario y hereda sus permisos.
• SERVICE_ACCOUNT: de máquina a máquina, para integraciones internas que no representan a una persona.
• EXTERNAL_APP: credencial recortada de una aplicación externa, con scopes propios.

Al rotar, el secreto nuevo se muestra una sola vez y el anterior sigue valiendo 24 horas, para que puedas cambiarlo sin cortar el servicio.

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 (7). Además del permiso, la clave tiene que haberla creado tu usuario y pertenecer a tu organización.

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 › Integraciones › 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.

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('El dominio de integraciones tiene problemas.');
  console.warn('Aplicación con más errores:', health.worstApp?.name);
}

Permisos por rol

De los seis roles de UTILIA OS, solo dos traen permisos de integraciones por defecto: Super Administrador, todos, y Gerente, solo los de consulta. 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 BUDGETS_EDIT o INVOICES_CREATE (con receptor alternativo, además INVOICES_CREATE y acceso a la matriz) y el scope crm:budgets:update o crm:invoices:create.

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 o archivar campos no se hace por MCP, sino en la aplicación, con CUSTOM_FIELDS_MANAGE. Filtrar listados por el valor de un campo personalizado tampoco está disponible por MCP.

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 siguen funcionando como alias de loss_reasons y by_owner, con el mismo contrato.

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 26 herramientas: 12 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 12 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

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. Valores: EXEMPT_IGIC_RETAILER, EXEMPT_IGIC_INTERNAL, EXEMPT_EXPORT y EXEMPT_OTHER. La causa decide la mención legal que se imprime en la factura.
• 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. 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

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).

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, y la parte de VeriFactu es de solo lectura: por MCP no se remite nada a la AEAT. 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.
• 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.

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.

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.