Primeros pasos con MCP

UTILIA OS publica sus datos para asistentes de IA y agentes mediante el protocolo MCP (Model Context Protocol): servidores remotos que hablan JSON-RPC sobre HTTP y se autorizan con OAuth 2.1. Este artículo te lleva de cero a tu primera llamada: qué servidor elegir, cómo autorizar el acceso, cómo es el intercambio inicial y cómo invocar las herramientas desde tu propio código. La credencial es un token OAuth o una clave de conexión personal, emitidos para un servidor concreto.

Si solo quieres conectar Claude, ChatGPT o Cursor sin programar nada, la guía de uso Conecta tu IA cuenta el proceso paso a paso.

Qué necesitas

• Una cuenta de UTILIA OS con permiso sobre lo que quieras consultar. El servidor hereda tus permisos y su alcance: nunca ve más que tú.
• Que tu organización tenga contratado el aplicativo de cada área que conectes. Si no lo tiene, el servidor lo rechaza aunque tengas el permiso.
• Un cliente MCP que admita el transporte HTTP (Claude, ChatGPT, Cursor, Claude Code u otro), o tu propio código.

Los servidores

Cada servidor cubre un área del producto y solo anuncia las herramientas de esa área. Son las mismas direcciones que ofrece la pantalla Conecta tu IA, necesitas entrar con tu cuenta, donde ves las de tu plan y, con un candado, las que tu organización podría contratar:

Hay herramientas que se repiten en varios servidores con el mismo contrato: notifications y org_plan están en todos, y search, en CRM, Gestión de proyectos y Finanzas. Lo que cambia entre copias es lo que alcanza el token. El detalle está en Buscador global y avisos por MCP.

Autorizar el acceso

Todas las llamadas llevan la cabecera Authorization: Bearer <token>. Hay dos formas de conseguir ese token:

• Autorización por navegador (OAuth 2.1 con PKCE). Es la forma recomendada y la que usan los asistentes cuando pegas la dirección del servidor. El cliente lo descubre todo a partir de la primera respuesta, como se ve en la figura. El detalle está en Descubrimiento de OAuth y en Scopes y recursos.
• Clave de conexión personal. Para clientes que no admiten la autorización por navegador. Se genera en Ajustes › Integraciones › Conecta tu IA, dentro del área, en «Conexión avanzada con clave (para desarrolladores)». Va atada a un solo servidor, caduca a los 90 días y admite como mucho cinco activas por servidor.

En los dos casos el token queda atado al servidor para el que se emitió: un token del recurso /api/mcp/crm no sirve en /api/mcp/finance, y al revés tampoco.

La doble puerta

Cada llamada tiene que pasar por la puerta del token y por la de tu usuario, además del plan de tu organización. Las comprobaciones van en este orden:

El scope, el permiso y la confirmación de cada operación están en la referencia de herramientas MCP y en la página de cada servidor.

Tu primera llamada

Con un token válido, el intercambio es el estándar de MCP. Primero, initialize:

curl -s -i -X POST 'https://os.utilia.ai/api/mcp/crm' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "clientInfo": { "name": "mi-cliente", "version": "1.0.0" },
      "capabilities": {}
    }
  }'

La respuesta identifica el servidor (en este caso, UTILIA CRM MCP), incluye en instructions una guía de sus herramientas canónicas y devuelve en la cabecera Mcp-Session-Id el identificador de la sesión, que conviene reenviar en las peticiones siguientes. El servidor admite las versiones del protocolo 2025-11-25 y 2025-06-18.

Después, tools/list devuelve las herramientas que tu token puede usar, y tools/call ejecuta una. Por ejemplo, buscar una ficha por texto:

curl -s -X POST 'https://os.utilia.ai/api/mcp/crm' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'Mcp-Session-Id: <SESION>' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": { "operation": "global", "q": "Acme" }
    }
  }'

Cada servidor admite hasta 60 peticiones por minuto; por encima responde con HTTP 429.

Llamar a las herramientas desde tu código

Los SDK oficiales envuelven algunas herramientas MCP con métodos tipados en sdk.mcp. Necesitas la versión actual (4.1.0) del SDK de JavaScript, con Node.js 18 o superior, o del SDK de Python, con Python 3.9 o superior.

npm install @utilia-os/sdk-js

sdk.mcp necesita una sesión OAuth: la clave de API que usan los servicios REST (X-Api-Key) no abre los servidores MCP. Configura el SDK con tu aplicación OAuth y pide la autorización indicando como resource el servidor al que vas a llamar:

import { UtiliaSDK } from '@utilia-os/sdk-js';
 
const sdk = new UtiliaSDK({
  baseURL: 'https://os.utilia.ai/api',
  oauth: {
    clientId: process.env.UTILIA_CLIENT_ID!,
    redirectUri: 'https://tu-app.com/callback',
    scopes: ['integrations:overview:view'],
  },
});
 
// 1. Envía a la persona a esta dirección para que autorice.
const authUrl = await sdk.oauth.getAuthorizationUrl({
  resource: 'https://os.utilia.ai/api/mcp/work',
});
 
// 2. En tu ruta de vuelta, cambia el código por el token.
await sdk.oauth.handleCallback(code);
 
// 3. Ya puedes llamar a las herramientas.
const status = await sdk.mcp.integrationsOverview.status();
console.log(`Aplicaciones externas: ${status.apps.total}`);

sdk.mcp.integrationsOverview llama a la herramienta integrations_overview del servidor de Gestión de proyectos. Con el mismo patrón, sdk.mcp.integrations gestiona aplicaciones externas y sus webhooks, y sdk.mcp.crm, sdk.mcp.marketing y sdk.mcp.attendance llaman a sus servidores respectivos. Para todo lo que no tiene método tipado, invoca la herramienta por JSON-RPC como en el apartado anterior.

Problemas frecuentes

Siguiente paso

• Referencia de herramientas MCP: herramientas, operaciones, scopes y permisos.
• Poner al día una cartera de clientes: un caso completo con el servidor del CRM.
• Avisos a tu servidor (webhooks): si además quieres que UTILIA OS te avise de lo que pasa, configura los webhooks de tu aplicación externa y verifica su firma HMAC.