Migración del MCP de integraciones de v1 a v2
Qué cambió cuando la herramienta integrations pasó a llamarse org_integrations_settings, cómo migrar tu código y qué herramientas nuevas llegaron con el cambio.
Actualizado el . 3 min de lectura
Esta guía es para integraciones escritas antes de la versión 2.8.0 de los SDK, que usaban la antigua herramienta MCP integrations. Explica qué cambió, cómo saber si te afecta y cómo migrar sin perder nada.
Qué cambió
La herramienta integrations, antes y ahora
SDK 2.7 y anteriores
Una sola herramienta
integrations mezclaba las claves de API v1 de la organización y los formularios de captación con ajustes de otros ámbitos.
SDK 2.8.0 y posteriores
Cuatro herramientas
org_integrations_settings, enutilia-crm: lo que hacía la antigua.integrations, enutilia-work: aplicaciones externas, OAuth saliente, webhooks, métricas y facturación por aplicación.api_credentials, enutilia-work: credenciales v2 personales, de cuenta de servicio y de aplicación externa.integrations_overview, enutilia-work: el estado del dominio de integraciones, de solo lectura.
El nombre integrations se quedó para las aplicaciones externas; lo que antes gestionaba se llama ahora org_integrations_settings, porque son ajustes de integración de la organización.
El contrato completo de las cuatro está en la referencia de herramientas MCP.
Por JSON-RPC, el nombre antiguo ya no admite las operaciones antiguas
Si invocas la herramienta integrations con una operación del dominio antiguo (api_keys_list, lead_forms_list...), la llamada falla con un error de operación no reconocida. No hay periodo de gracia ni traducción automática en el servidor: cambia el campo name a org_integrations_settings y llama al servidor utilia-crm.
¿Te afecta?
Te afecta si tu código invoca la herramienta integrations con alguna operación api_keys_* o lead_forms_*, o si usa el alias del SDK integrationsLegacy (JavaScript) o integrations_legacy (Python). Para localizarlo:
# Llamadas JSON-RPC a la herramienta por su nombre
grep -rEn '"name"\s*:\s*"integrations"' --include='*.{ts,tsx,js,py,json}' .
# Alias obsoleto del SDK de JavaScript
grep -rEn '\bsdk\.mcp\.integrationsLegacy\b' --include='*.{ts,tsx,js}' .
# Alias obsoleto del SDK de Python
grep -rEn '\bsdk\.mcp\.integrations_legacy\b' --include='*.py' .Si tu código solo usa las operaciones de aplicaciones externas (apps_*, apps_oauth_*, apps_webhooks_*, apps_metrics_* y apps_billing_*), no te afecta: esas son justo las de la nueva integrations.
Cómo migrar
Cambia el nombre de la herramienta
En las llamadas JSON-RPC, cambia
"name": "integrations"por"name": "org_integrations_settings"y envíalas ahttps://os.utilia.ai/api/mcp/crm.Cambia el nombre de dos operaciones
Las operaciones conservan su nombre, sus argumentos y su respuesta, salvo las dos de avisos de las claves de API:
api_keys_notifications_getpasa aapi_keys_get_notifications, yapi_keys_notifications_update, aapi_keys_update_notifications.Pide los scopes de cada operación
Cada operación exige su propio scope:
integrations:credentials:viewo:managepara las claves de API ycrm:lead-forms:viewo:managepara los formularios. Revisa los scopes que pide tu aplicación al autorizar.Sustituye el alias del SDK
Cambia
sdk.mcp.integrationsLegacyporsdk.mcp.orgIntegrationsSettingsen JavaScript, ysdk.mcp.integrations_legacyporsdk.mcp.org_integrations_settingsen Python. El alias sigue en la versión actual del SDK, marcado como obsoleto, y desaparecerá en una versión mayor.
Para tu organización, org_integrations_settings ofrece dieciocho operaciones: siete de claves de API y once de formularios de captación.
Los métodos del SDK para esta herramienta llaman hoy al servidor equivocado
sdk.mcp.orgIntegrationsSettings y su alias envían las llamadas al servidor de Gestión de proyectos (/api/mcp/dev), donde org_integrations_settings no está publicada, así que responden con un error que dice que la herramienta no está disponible en ese servidor. Hasta que el SDK lo corrija, invoca la herramienta por JSON-RPC contra /api/mcp/crm.
Antes y después
Listar las claves de API de la organización:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "org_integrations_settings",
"arguments": { "operation": "api_keys_list" }
}
}Antes, la misma llamada llevaba "name": "integrations".
Las capacidades nuevas no tenían equivalente antes. Por ejemplo, listar las aplicaciones externas o las entregas fallidas de un webhook con la nueva integrations:
const { data: apps } = await sdk.mcp.integrations.appsList({
page: 1,
limit: 20,
includeInactive: false,
});
const { data: failed } =
await sdk.mcp.integrations.appsWebhooksListDeliveries(appId, {
status: 'FAILED_PERMANENTLY',
limit: 50,
});Los SDK necesitan una sesión OAuth autorizada para el servidor utilia-work, como se explica en Primeros pasos con MCP.
Fechas
Del cambio de nombre a la retirada del alias
12 may 2026
Versión 2.8.0 de los SDK
Llegan las cuatro herramientas y el alias. Por JSON-RPC, el nombreintegrationspasa a la nueva sin periodo de gracia.1 sep 2026
Fin del soporte del alias
El alias sigue en el SDK, marcado como obsoleto.Versión mayor
El alias desaparece
Llegará con la próxima versión mayor de los SDK.
Siguiente paso
- Referencia de herramientas MCP: permisos, scopes y confirmaciones de las cuatro herramientas.
- Primeros pasos con MCP.
- Los cambios de cada versión están en el
CHANGELOG.mdde cada SDK, en la entrada 2.8.0.