🌐 ITENFRESDE

Cómo Integrar Hermes Agent con tu CRM: Guía Práctica de las API MCP

· Hermes Agent Experts

La integración de Hermes Agent con tu CRM mediante Model Context Protocol (MCP) está transformando la forma en que empresas de Madrid, Barcelona y Valencia gestionan sus relaciones comerciales. Este artículo es una guía práctica y técnica para conectar tu CRM — ya sea Salesforce, HubSpot o cualquier plataforma con API abierta — con Hermes Agent, el agente de IA de código abierto más versátil del ecosistema.

¿Qué es MCP y por qué cambia las reglas del juego?

Model Context Protocol (MCP) es un estándar abierto que permite a los modelos de lenguaje (LLM) interactuar directamente con APIs y sistemas externos de forma estructurada. Piensa en MCP como el “USB-C de la IA”: un protocolo único que unifica la comunicación entre el agente y cualquier servicio, incluyendo tu CRM.

Para Hermes Agent, MCP no es un añadido opcional: es su mecanismo nativo de extensión. Cada “skill” que despliegas en Hermes Agent puede exponer herramientas MCP que el agente invoca cuando necesita leer, escribir o transformar datos de tu CRM.

Ventajas clave de MCP frente a integraciones tradicionales

AspectoAPIs tradicionalesMCP + Hermes Agent
Curva de aprendizajeAlta: requires autenticación, SDK, endpointsBaja: descripción declarativa de herramientas
MantenimientoConstante: cambios de API rompen integracionesMínimo: MCP abstrae la capa de transporte
ContextoEl desarrollador gestiona el estado manualmenteEl agente mantiene el contexto conversacional
EscalabilidadVertical: más código, más endpointsHorizontal: más skills, más herramientas MCP

Escenario 1: Sincronización de leads con HubSpot

Uno de los casos de uso más demandados por equipos comerciales en España es la captura y sincronización automática de leads. Con Hermes Agent y MCP, puedes crear un skill que monitorice formularios web, redes sociales o campañas de email, y los volcae directamente en HubSpot.

Paso 1: Crear el skill MCP para HubSpot

hermes skill create hubspot-lead-sync

Esto genera la estructura base del skill. A continuación, edita el archivo SKILL.md para definir las herramientas MCP:

---
name: hubspot-lead-sync
description: Sincronización automatizada de leads con HubSpot vía MCP
tools:
  - name: crear_contacto_hubspot
    description: Crea un nuevo contacto en HubSpot
    input_schema:
      type: object
      properties:
        email:
          type: string
          description: Email del contacto
        nombre:
          type: string
          description: Nombre completo
        empresa:
          type: string
          description: Empresa del contacto
        telefono:
          type: string
          description: Teléfono de contacto
        origen:
          type: string
          description: Origen del lead (web, email, referral)
  - name: buscar_contacto_hubspot
    description: Busca un contacto existente en HubSpot por email
    input_schema:
      type: object
      properties:
        email:
          type: string
          description: Email a buscar

Paso 2: Implementar el handler en Python

El skill se apoya en un script Python que Hermes Agent ejecuta cuando invoca la herramienta MCP:

# scripts/hubspot_handler.py
import os
import requests
from typing import Dict, Any

HUBSPOT_API_KEY = os.getenv("HUBSPOT_API_KEY")
HUBSPOT_API_URL = "https://api.hubapi.com/crm/v3/objects/contacts"

def crear_contacto(params: Dict[str, Any]) -> Dict[str, Any]:
    """Crea un contacto en HubSpot desde una herramienta MCP."""
    headers = {
        "Authorization": f"Bearer {HUBSPOT_API_KEY}",
        "Content-Type": "application/json"
    }
    payload = {
        "properties": {
            "email": params["email"],
            "firstname": params.get("nombre", "").split()[0],
            "lastname": " ".join(params.get("nombre", "").split()[1:]),
            "company": params.get("empresa", ""),
            "phone": params.get("telefono", ""),
            "hs_lead_source": params.get("origen", "web")
        }
    }
    response = requests.post(HUBSPOT_API_URL, json=payload, headers=headers)
    response.raise_for_status()
    return {"status": "ok", "contact_id": response.json()["id"]}

def buscar_contacto(params: Dict[str, Any]) -> Dict[str, Any]:
    """Busca un contacto en HubSpot por email."""
    headers = {"Authorization": f"Bearer {HUBSPOT_API_KEY}"}
    url = f"{HUBSPOT_API_URL}?email={params['email']}"
    response = requests.get(url, headers=headers)
    if response.status_code == 404:
        return {"status": "not_found"}
    response.raise_for_status()
    return {"status": "found", "contact": response.json()}

Paso 3: Registrar el skill en Hermes Agent

hermes skill load hubspot-lead-sync
hermes skill enable hubspot-lead-sync

Una vez cargado, Hermes Agent detecta automáticamente las herramientas MCP disponibles. Cuando un lead entra por cualquier canal, el agente decide de forma autónoma si debe crear un nuevo contacto o actualizar uno existente.

Escenario 2: Automatización de tareas en Salesforce

Salesforce sigue siendo el CRM preferido de grandes cuentas y corporaciones en Madrid y Barcelona. Con Hermes Agent puedes automatizar tareas repetitivas que antes consumían horas del equipo comercial.

Ejemplo: Actualización masiva de oportunidades

Imagina que necesitas actualizar el estado de todas las oportunidades en fase “Negociación” que lleven más de 30 días sin actividad. Con una skill MCP personalizada:

# SKILL.md (fragmento)
tools:
  - name: consultar_oportunidades_salesforce
    description: Consulta oportunidades por estado y antigüedad
    input_schema:
      type: object
      properties:
        fase:
          type: string
          description: Fase de la oportunidad
        dias_inactivo:
          type: integer
          description: Días mínimos sin actividad
  - name: actualizar_oportunidad_salesforce
    description: Actualiza el estado de una oportunidad
    input_schema:
      type: object
      properties:
        opportunity_id:
          type: string
        nuevo_estado:
          type: string
        motivo:
          type: string

Hermes Agent ejecuta esta skill de forma programada mediante su sistema de cronjobs:

hermes cron create \
  --name "salesforce-oportunidades-estancadas" \
  --schedule "0 8 * * 1" \
  --skill salesforce-cleanup \
  --prompt "Revisa oportunidades en fase Negociación con más de 30 días sin actividad. Envía un aviso al responsable y si no hay respuesta en 7 días, mueve la oportunidad a 'Perdida' con motivo 'Sin actividad prolongada'."

Este cronjob se ejecuta cada lunes a las 8:00 AM, liberando a tu equipo de una tarea administrativa que nadie quiere hacer.

Escenario 3: Enriquecimiento automático de contactos

Una de las funcionalidades más potentes de Hermes Agent con MCP es la capacidad de enriquecer registros de tu CRM con datos de fuentes externas. Por ejemplo, cuando un nuevo contacto se añade a tu base de datos, el agente puede:

  1. Buscar información pública de la empresa (LinkedIn, web corporativa)
  2. Identificar el sector, tamaño y ubicación
  3. Clasificar el lead por score de prioridad
  4. Añadir notas contextuales al registro del CRM

Ejemplo de pipeline automático

# scripts/enrichment_pipeline.py
def enrichment_pipeline(contacto: dict) -> dict:
    """Pipeline completo de enriquecimiento para un contacto CRM."""
    # Paso 1: Verificar si el contacto ya está enriquecido
    estado = buscar_contacto_crm(contacto["email"])
    if estado.get("enriquecido"):
        return {"status": "already_enriched", "contact_id": estado["id"]}

    # Paso 2: Obtener datos públicos de la empresa
    datos_empresa = web_search(contacto.get("dominio", ""))
    
    # Paso 3: Calcular score de lead
    score = calcular_lead_score(contacto, datos_empresa)
    
    # Paso 4: Actualizar CRM con datos enriquecidos
    resultado = actualizar_contacto_crm(
        contacto["email"],
        enriched_data={
            "sector": datos_empresa.get("sector"),
            "tamaño_empresa": datos_empresa.get("tamaño"),
            "lead_score": score,
            "notas": f"Contacto enriquecido automáticamente por Hermes Agent. "
                     f"Sector detectado: {datos_empresa.get('sector')}. "
                     f"Ubicación: {datos_empresa.get('ubicacion', 'No disponible')}"
        }
    )
    return {"status": "enriched", "contact_id": resultado["id"], "score": score}

Configuración del archivo MCP en Hermes Agent

Para que Hermes Agent reconozca tus herramientas MCP personalizadas, debes configurar el archivo mcp_servers.yaml en el directorio de configuración:

# ~/.hermes/config/mcp_servers.yaml
mcp_servers:
  hubspot:
    type: stdio
    command: python
    args:
      - /home/hermes/skills/hubspot-lead-sync/scripts/hubspot_handler.py
    env:
      HUBSPOT_API_KEY: "${HUBSPOT_API_KEY}"
      
  salesforce:
    type: stdio
    command: python
    args:
      - /home/hermes/skills/salesforce-cleanup/scripts/salesforce_handler.py
    env:
      SF_CLIENT_ID: "${SF_CLIENT_ID}"
      SF_CLIENT_SECRET: "${SF_CLIENT_SECRET}"
      SF_USERNAME: "${SF_USERNAME}"
      SF_PASSWORD: "${SF_PASSWORD}"

Las variables de entorno se gestionan desde el archivo .env de Hermes Agent o directamente en la configuración del perfil activo:

hermes config set HUBSPOT_API_KEY "pat-eu1-xxxx-xxxx"
hermes config set SF_CLIENT_ID "3MVG9xxxxxxxxx"

Buenas prácticas para integraciones CRM-MCP

1. Diseña tools atómicas

Cada herramienta MCP debe hacer una sola cosa y hacerla bien. En lugar de una herramienta “sincronizar_todo”, crea varias: crear_contacto, actualizar_contacto, buscar_contacto, eliminar_contacto. Esto permite a Hermes Agent componer flujos complejos combinando tools simples.

2. Implementa validación de entrada

Siempre valida los parámetros que recibe cada herramienta MCP. Hermes Agent es fiable, pero los datos que llegan desde formularios web o APIs externas pueden contener sorpresas:

def validar_email(email: str) -> bool:
    import re
    patron = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
    return re.match(patron, email) is not None

3. Gestiona la tasa de llamadas API

Los CRM suelen tener límites de tasa (rate limits). Implementa un mecanismo de backoff exponencial en tus handlers:

import time
import random

def llamada_con_reintento(func, params, max_intentos=3):
    for intento in range(max_intentos):
        try:
            return func(params)
        except requests.exceptions.HTTPError as e:
            if e.response.status_code == 429:  # Too Many Requests
                espera = (2 ** intento) + random.random()
                time.sleep(espera)
            else:
                raise
    raise Exception("Máximo de reintentos alcanzado")

4. Logging y auditoría

Cada operación que Hermes Agent realice sobre tu CRM debe quedar registrada. Implementa un sistema de logging estructurado:

import logging
import json

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger("crm-mcp")

def log_operacion(accion: str, contacto: str, resultado: dict):
    logger.info(json.dumps({
        "accion": accion,
        "contacto": contacto,
        "resultado": resultado,
        "timestamp": time.time()
    }))

Seguridad en integraciones CRM-MCP

La seguridad es crítica cuando conectas un agente de IA a tu CRM. Sigue estas recomendaciones:

Autenticación segura

Nunca hardcodees credenciales. Usa el sistema de variables de entorno de Hermes Agent o un gestor de secretos como HashiCorp Vault:

hermes config set --secret HUBSPOT_API_KEY "pat-eu1-xxxx-xxxx"

Principio de mínimo privilegio

Crea tokens de API con los permisos mínimos necesarios. Para HubSpot, usa tokens de acceso privado restringidos solo a los objetos que necesitas (contacts, deals) con permisos de solo lectura cuando sea posible.

Validación de salida

Antes de escribir cualquier dato en tu CRM, Hermes Agent puede validar que el contenido sea apropiado y no contenga inyecciones:

def sanitizar_entrada(texto: str) -> str:
    """Elimina caracteres peligrosos antes de escribir en CRM."""
    import html
    return html.escape(texto.strip()[:500])  # Limitar longitud

Casos de uso avanzados

CRM predictivo con Hermes Agent

Combina MCP con capacidades de análisis para crear un CRM predictivo. Hermes Agent puede analizar patrones históricos de cierre y asignar probabilidades a oportunidades abiertas:

tools:
  - name: predecir_cierre_oportunidad
    description: Calcula la probabilidad de cierre de una oportunidad basada en datos históricos
    input_schema:
      type: object
      properties:
        opportunity_id:
          type: string
        incluir_recomendaciones:
          type: boolean

Slack + CRM + Hermes Agent

Uno de los despliegues más populares entre equipos de Valencia y Barcelona es el asistente CRM dentro de Slack. El equipo escribe “Hermes, crea un contacto para Marta García de Acme Corp, email [email protected]” y Hermes Agent:

  1. Busca si el contacto ya existe en el CRM
  2. Si no existe, lo crea con los datos proporcionados
  3. Busca información adicional de la empresa
  4. Responde en Slack con un resumen de lo creado

Preguntas frecuentes (FAQ)

¿Qué CRMs son compatibles con Hermes Agent vía MCP?

Cualquier CRM que exponga una API REST puede integrarse con Hermes Agent mediante MCP. Los más comunes son Salesforce, HubSpot, Zoho CRM, Monday.com, Pipedrive y Dynamics 365. Si tu CRM tiene API, Hermes Agent puede conectarse.

¿Necesito conocimientos avanzados de programación?

No es necesario ser un desarrollador experto. Con conocimientos básicos de Python y seguir los ejemplos de esta guía, puedes tener tu primera integración funcionando en menos de una hora. Para casos complejos, nuestro equipo en Hermes Agent Experts ofrece soporte técnico personalizado.

¿Qué pasa si la API del CRM cambia?

MCP abstrae la capa de transporte, por lo que los cambios en la API del CRM solo requieren actualizar el handler específico, no toda la integración. Hermes Agent sigue funcionando con el resto de herramientas sin interrupción.

¿Cómo gestiono los rate limits del CRM?

Implementa el patrón de backoff exponencial que mostramos en la sección de buenas prácticas. Además, puedes configurar Hermes Agent para espaciar las llamadas usando el sistema de colas interno.

¿Es seguro dar acceso al CRM a un agente de IA?

Sí, siempre que sigas las prácticas de seguridad recomendadas: tokens de mínimo privilegio, variables de entorno secretas, logging de auditoría y validación de entrada/salida. Hermes Agent es software de código abierto, auditado por la comunidad.

¿Puedo integrar múltiples CRMs a la vez?

Sí. Hermes Agent puede cargar múltiples skills MCP simultáneamente. Puedes tener un skill para HubSpot, otro para Salesforce y otro para un CRM propio, todos activos al mismo tiempo. El agente decide qué herramienta usar según el contexto de la conversación.

¿Hermes Agent funciona con CRM on-premise?

Sí. MCP soporta conexiones tanto a APIs cloud como a endpoints on-premise, siempre que el CRM sea accesible desde la red donde se ejecuta Hermes Agent. Para entornos con restricciones de red, puedes usar el modo stdio para ejecutar el handler localmente.

Próximos pasos

La integración de Hermes Agent con tu CRM mediante MCP no es solo una mejora técnica: es un cambio de paradigma en cómo tu equipo interactúa con los datos comerciales. Desde oficinas en Madrid hasta startups tecnológicas en Barcelona y empresas consolidadas en Valencia, la automatización inteligente del CRM está impulsando equipos comerciales más eficientes y con mejores tasas de conversión.

Si quieres llevar tu integración al siguiente nivel, nuestro equipo de Hermes Agent Experts está disponible para ayudarte con:

  • Consultoría personalizada: Análisis de tu stack tecnológico y diseño de la integración óptima
  • Desarrollo de skills a medida: Creamos skills MCP específicos para tu CRM y tus flujos de trabajo
  • Formación para equipos: Talleres prácticos para que tu equipo saque el máximo partido a Hermes Agent
  • Soporte continuo: Mantenimiento y actualización de tus integraciones CRM-MCP

Contáctanos en [email protected] y descubre cómo Hermes Agent puede transformar tu CRM en un sistema inteligente y autónomo.

Richiedi una consulenza gratuita →

← Torna al blog