MCP: el CRM desde tu IA

Qué es MCP

El Model Context Protocol es el estándar abierto con el que los asistentes de IA se conectan a herramientas externas. En vez de copiar y pegar datos en un chat, el asistente llama directamente a FusionCRM: busca un contacto, resume las conversaciones de la semana, crea una cotización o mueve un negocio de etapa, y te muestra el resultado.

Qué puedes pedirle

Conectar tu cliente

Hay dos formas de autenticarse; ambas terminan en un token con la organización ya dentro, así que no hay nada más que configurar:

• • Conector MCP (OAuth): en Configuración → Desarrollador → Conectores MCP creas un conector y obtienes un Client ID y un Secreto. El cliente hace el flujo OAuth solo.
• • Token de API: el mismo token de la API REST, enviado como Authorization: Bearer. Para clientes que aceptan headers fijos.

Qué credencial usar

Los tokens de API funcionan en /api/* (la API REST) y en /api/mcp. No sirven en /api/v1/*, que es la API interna de la app web: ahí responden 401 con el código API_TOKEN_NOT_ACCEPTED.

Claude (web y escritorio)

1. 1. En FusionCRM: Configuración → Desarrollador → Conectores MCP → Crear conector MCP. Guarda el Client ID y el Secreto (el secreto se muestra una sola vez).
2. 2. En Claude: Configuración → Conectores → Agregar conector personalizado.
3. 3. Pega la URL del servidor y, en Configuración avanzada, el Client ID y el Secreto.
4. 4. Autoriza el acceso cuando Claude lo pida. Listo: en un chat nuevo ya verás las herramientas de FusionCRM.

Claude Code

claude mcp add --transport http fusioncrm https://api.fusioncol.com/api/mcp \
  --header "Authorization: Bearer <token de API>"

Cursor y otros clientes

Cualquier cliente que soporte servidores MCP remotos (Streamable HTTP) funciona. En Cursor, el archivo mcp.json queda así:

{
  "mcpServers": {
    "fusioncrm": {
      "url": "https://api.fusioncol.com/api/mcp",
      "headers": { "Authorization": "Bearer <token de API>" }
    }
  }
}

Cursor también acepta el flujo OAuth con un conector (redirige a cursor://anysphere.cursor-mcp/oauth/callback); los metadatos del servidor están en /.well-known/oauth-authorization-server.

Verifica a qué cuenta apunta

Es el primer paso recomendado después de conectar, y es obligatorio si tienes varias organizaciones conectadas: equivocarse de conexión es enviar un WhatsApp desde el número de otra empresa. Pregúntale a la IA «¿a qué organización estoy conectado?»; usará la herramienta get_current_organization. Con un token de API puedes comprobarlo tú mismo:

curl https://api.fusioncol.com/api/me \
  -H "Authorization: Bearer <token de API>"

{
  "success": true,
  "data": {
    "organization": { "id": "665f…", "name": "Mi Empresa SAS" },
    "user": { "email": "ana@example.com", "role": "admin" },
    "token": {
      "name": "claude-code",
      "permissions": ["contacts:read", "whatsapp:send"],
      "expiresAt": null
    },
    "plan": { "name": "pro", "modules": { "api": true } }
  }
}

Permisos y seguridad

• • Un conector OAuth actúa con los permisos del usuario que lo autorizó, dentro de su organización.
• • Con un token de API, la IA solo ve las herramientas cuyos permisos tenga el token (por ejemplo, sin whatsapp:send no puede enviar mensajes).
• • Todo queda acotado a tu organización: no hay forma de leer datos de otra.
• • Los conectores y tokens se revocan desde la misma pantalla donde se crearon; el cliente pierde acceso al instante.
• • MCP hace parte del módulo API del plan, igual que la API REST.
• • El header X-Organization-Id (o el query organizationId) es opcional: sin él se usa la organización del token. Si lo envías y no coincide, la respuesta es 403 ORGANIZATION_ID_MISMATCH (en MCP llega como error JSON-RPC con ese código en data.code).

Problemas frecuentes

Cada rechazo trae un code que dice exactamente qué pasó:

Herramientas disponibles

219 herramientas, generadas desde el servidor en producción. El catálogo completo con los parámetros de cada una está en mcp-tools.json.