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

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**

### Una sola herramienta (SDK 2.7 y anteriores)

`integrations` mezclaba las claves de API v1 de la organización y los formularios de captación con ajustes de otros ámbitos.

### Cuatro herramientas (SDK 2.8.0 y posteriores)

- `org_integrations_settings`, en `utilia-crm`: lo que hacía la antigua.
- `integrations`, en `utilia-work`: aplicaciones externas, OAuth saliente, webhooks, métricas y facturación por aplicación.
- `api_credentials`, en `utilia-work`: claves de API de la organización (`org_keys_*`) y credenciales v2 personales y de aplicación externa.
- `integrations_overview`, en `utilia-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](https://os.utilia.ai/docs/developers/mcp/reference#aplicaciones-externas-y-credenciales).

> **Importante: 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:

```bash
# 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

1. **Cambia el nombre de la herramienta**

   En las llamadas JSON-RPC, cambia `"name": "integrations"` por `"name": "org_integrations_settings"` y envíalas a `https://os.utilia.ai/api/mcp/crm`.
2. **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_get` pasa a `api_keys_get_notifications`, y `api_keys_notifications_update`, a `api_keys_update_notifications`.
3. **Pide los scopes de cada operación**

   Cada operación exige su propio scope: `integrations:credentials:view` o `:manage` para las claves de API y `crm:lead-forms:view` o `:manage` para los formularios. Revisa los scopes que pide tu aplicación al autorizar.
4. **Sustituye el alias del SDK**

   Cambia `sdk.mcp.integrationsLegacy` por `sdk.mcp.orgIntegrationsSettings` en JavaScript, y `sdk.mcp.integrations_legacy` por `sdk.mcp.org_integrations_settings` en 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.

> **Atenció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:

```json
{
  "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`:

### JavaScript / TypeScript

```typescript
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,
  });
```

### Python

```python
from utilia_sdk.mcp.types import AppsListFilters, WebhookDeliveriesFilters

apps, pagination = await sdk.mcp.integrations.apps_list(
    AppsListFilters(page=1, limit=20, include_inactive=False)
)

failed, _ = await sdk.mcp.integrations.apps_webhooks_list_deliveries(
    app_id,
    WebhookDeliveriesFilters(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](https://os.utilia.ai/docs/developers/mcp/quickstart#llamar-a-las-herramientas-desde-tu-código).

## Fechas

**Del cambio de nombre a la retirada del alias**

1. **12 may 2026**: Versión 2.8.0 de los SDK. Llegan las cuatro herramientas y el alias. Por JSON-RPC, el nombre `integrations` pasa a la nueva sin periodo de gracia.
2. **1 sep 2026**: Fin del soporte del alias. El alias sigue en el SDK, marcado como obsoleto.
3. **Versión mayor**: El alias desaparece. Llegará con la próxima versión mayor de los SDK.

## Siguiente paso

- [Referencia de herramientas MCP](https://os.utilia.ai/docs/developers/mcp/reference): permisos, scopes y confirmaciones de las cuatro herramientas.
- [Primeros pasos con MCP](https://os.utilia.ai/docs/developers/mcp/quickstart).
- Los cambios de cada versión están en el `CHANGELOG.md` de cada SDK, en la entrada 2.8.0.