Conectar SMOC con MCP a Claude o cualquier otro cliente basado en IA

Guía sencilla que muestra cómo conectar SMOC a clientes de IA y herramientas de desarrollo usando MCP (Model Context Protocol). Una vez conectado, herramientas como Claude Desktop, Claude Code, Cursor o VS Code pueden leer tus datos de SMOC directamente — contactos, empresas, activos de empresa, diagramas de flujo, analítica de flujos, hilos de la bandeja de entrada de LinkedIn y conversaciones de flujo de mensajes — todo limitado al ámbito de tu empresa. Las llamadas HTTP deben usar la referencia de la API REST v2.

Consigue tu clave API

La integración MCP de SMOC se autentica con una clave API privada. Genera una en la consola de SMOC:

1. Ve a Ajustes → Integraciones → MCP.
2. Opcionalmente ponle un nombre y una caducidad (7, 30 o 90 días). Deja la caducidad en Sin caducidad si no quieres que expire.
3. Genera la clave y cópiala inmediatamente — solo se muestra una vez, así que guárdala en un lugar seguro.

Tu clave está vinculada a tu empresa. Cada petición hecha con ella se limita automáticamente a tus datos — solo verás contactos, empresas, analíticas, hilos de la bandeja de entrada y conversaciones que te pertenecen. Generar una nueva clave no revoca las existentes. Las claves emitidas aparecen en la misma página — revoca las que no uses allí.

Las páginas de API y Zapier usan el mismo nombre, caducidad, aviso de copia única y lista de claves emitidas.

Qué puedes acceder

Tras conectar, las siguientes herramientas estarán disponibles (la disponibilidad exacta depende de los permisos de tu cuenta y las vinculaciones configuradas en el servidor). Las claves son solo lectura por defecto. Marca Permitir escrituras limitadas al crear una clave para habilitar las escrituras que se indican abajo.

Descubrimiento

• whoami — rol actual, ámbito de empresa y permisos
• mcp_capabilities — herramientas visibles, habilidades y todo lo actualmente no disponible
• skills_search — encontrar una receta a partir de una frase de tarea corta
• skills_get — entradas exactas y un ejemplo para una habilidad

Empresas y activos

• companies_get — perfil de empresa (título, clave, URL, idiomas, ajustes)
• company_assets_get — productos, posicionamiento, enlaces web y archivos
• company_asset_extraction_results_list — resúmenes de resultados de extracción
• company_asset_extraction_results_get — un resultado de extracción, opcionalmente con los datos extraídos
• company_asset_extraction_templates_list — plantillas, etiquetas y frescura

Las claves de superusuario también pueden llamar a companies_list para explorar todas las empresas antes de seleccionar una companyId.

Contactos

• contacts_search — búsqueda con filtros, orden y paginación
• contacts_get — un contacto anonimizado por id
• contacts_get_stats — recuentos y resumen de interacción
• contacts_get_filter_options — valores de filtro válidos (ubicación, flujo, dispositivo y similares)
• contact_tags_list — etiquetas de contacto
• prospect_lists_list / prospect_lists_get — listas de prospectos

Bandeja de entrada y conversaciones

• inbox_threads_list — hilos de la bandeja de entrada de LinkedIn (y otros), con filtros de no leídos / sin respuesta / remitente / flujo
• inbox_threads_get — un hilo; pon includeMessages: true para incluir mensajes recientes
• inbox_messages_list — historial de mensajes de un hilo, incluyendo hilos de compañeros fusionados
• conversations_list — ejecuciones de flujo de mensajes (inscripción, estado, nodo actual)
• conversations_get — una ejecución de conversación, incluyendo hitos

Las herramientas de bandeja de entrada requieren el permiso inbox:read. Pueden leer los cuerpos de los mensajes. Las claves con escritura habilitada también pueden archivar, marcar como no leído/gestionado y enviar una respuesta solo texto con inbox_threads_send (requiere threadId, body y idempotencyKey). No pueden adjuntar archivos, editar diagramas de flujo, publicar flujos ni iniciar campañas de prospección en LinkedIn. Las claves de superusuario pueden guardar borradores de flujo y tema Mongo (flowcharts_save, flowcharts_create, themes_save y llamadas relacionadas), incluyendo tipos web/mensaje y chat/flujo de tarjetas. Estas escrituras no publican.

Diagramas de flujo

• flowcharts_list — diagramas de flujo estáticos de la empresa
• flowcharts_get — resumen o gráfico completo de un diagrama de flujo
• flowchart_recommendations_list — documentos de recomendación para un diagrama de flujo
• flowcharts_versions_list, themes_get, studio_generation_categories_list, carteras de segmentación y lecturas de trabajos de generación/traducción
• Escrituras de borrador de superusuario: flowcharts_save, flowcharts_restore_version, flowcharts_create (flowType web o mensaje, webFormat chat o flujo de tarjetas), flowcharts_duplicate, themes_save. Estas escriben borradores Mongo y no publican.
• Lecturas CPCS: cpcs_overview, URLs, rastreos, extracciones, plantillas, programación

Analítica de flujos

• analytics_flow_list_flows — flujos ordenados por tráfico
• analytics_flow_kpis — totales, conversión, variaciones respecto al periodo anterior
• analytics_flow_timeseries — tendencias diarias o mensuales
• analytics_flow_dimension_metrics — desglose por dispositivo, país, idioma, UTM o día de la semana
• analytics_flow_filter_values — valores de filtro de analítica válidos

Las claves de cliente siempre están limitadas a tu propia empresa. Las claves de superusuario pueden pasar companyId en herramientas limitadas.

---

Conectar en Claude (web y escritorio)

Añade SMOC como conector personalizado. Esto funciona en claude.ai y en la app de escritorio de Claude. Puedes iniciar sesión con tu cuenta de SMOC o conectar con una clave API.

Inicio rápido

Endpoint MCP: https://api.smoc.ai/mcp

Iniciar sesión

1. En Claude, abre Personalizar y luego + Añadir.
2. Nombra el conector SMOC y pega el endpoint MCP. Deja activado el inicio de sesión. No elijas Sin inicio de sesión y no añadas un encabezado de petición.
3. Cuando Claude te pida conectar, inicia sesión con una cuenta de administrador de empresa.
4. En un chat, abre +, elige Conectores y activa SMOC. Pide a Claude que ejecute whoami.

El inicio de sesión es solo para administradores de empresa. Puede leer los datos de esa empresa. Los miembros y otros roles no tienen acceso. No habilita las escrituras limitadas que seleccionas al crear una clave API. Si administras más de una empresa, usa una clave API para la empresa que quieras.

En Team y Enterprise, un Propietario añade el conector en Ajustes de organización → Conectores → + Añadir → Personalizado. Los miembros lo activan desde Personalizar.

O añade una clave API

1. Genera una clave API en Ajustes → Integraciones → MCP y cópiala.
2. En Claude, abre Personalizar y luego + Añadir.
3. Nombra el conector SMOC y pega el endpoint MCP.
4. Elige Sin inicio de sesión. En Encabezados de petición, selecciona authorization y pon el valor Bearer YOUR_SMOC_API_KEY — incluye la palabra Bearer y el espacio. Marca el encabezado como Obligatorio y luego añade el conector.

Usa una clave cuando quieras una sola empresa, una caducidad o escrituras limitadas. Los encabezados de petición se están desplegando. Si + Añadir no tiene sección de encabezados, usa Claude Code o el archivo de configuración de escritorio de abajo.

Conectar en ChatGPT

ChatGPT añade SMOC como una app. La pantalla de creación usa inicio de sesión y no tiene campo para clave API. Inicia sesión con una cuenta de administrador de empresa.

Inicio rápido

Endpoint MCP: https://api.smoc.ai/mcp

1. Abre Ajustes → Apps → Ajustes avanzados y activa Modo desarrollador. En Business, Enterprise o Edu, un administrador del espacio de trabajo debe activarlo antes en Ajustes de espacio de trabajo → Permisos y roles.
2. Abre Apps → Crear. Nombra la app SMOC y pega el endpoint MCP.
3. Elige OAuth y luego Escanear herramientas. Inicia sesión con una cuenta de administrador de empresa cuando ChatGPT lo pida y haz clic en Crear.
4. En un chat, abre el menú de herramientas y activa SMOC. Pide a ChatGPT que ejecute whoami.

El inicio de sesión es solo para administradores de empresa. Puede leer los datos de esa empresa. Los miembros no tienen acceso. Las claves API son para Claude, Cursor y VS Code. ChatGPT necesita un plan Plus, Pro, Business, Enterprise o Edu para apps personalizadas.

Conectar a Claude Desktop con un archivo de configuración

Usa esto cuando el diálogo de conector no acepte clave API. SMOC se conecta entonces a través de un pequeño puente local (mcp-remote).

1. Abre Claude Desktop → Ajustes → Desarrollador → Editar configuración. Esto abre claude_desktop_config.json.
2. Añade SMOC bajo mcpServers:

{
  "mcpServers": {
    "smoc": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.smoc.ai/mcp",
        "--header",
        "Authorization: Bearer YOUR_SMOC_API_KEY"
      ]
    }
  }
}

3. Sustituye YOUR_SMOC_API_KEY por la clave que generaste.
4. Guarda el archivo y reinicia Claude Desktop.

SMOC aparecerá ahora en tu lista de herramientas. Requiere Node.js instalado (para npx).

---

Conectar a Claude Code

Claude Code puede comunicarse directamente con el endpoint de SMOC usando un encabezado de autenticación — no necesita puente.

claude mcp add --transport http smoc https://api.smoc.ai/mcp \
  --header "Authorization: Bearer YOUR_SMOC_API_KEY"

En Claude Code 2.1.1 y superior también puedes añadirlo como JSON:

claude mcp add-json smoc \
  '{"type":"http","url":"https://api.smoc.ai/mcp","headers":{"Authorization":"Bearer YOUR_SMOC_API_KEY"}}'

Verifica la conexión ejecutando /mcp dentro de una sesión de Claude Code — SMOC debería aparecer como conectado con sus herramientas listadas.

---

Conectar a otros clientes (Cursor, VS Code, Windsurf, etc.)

La mayoría de los editores compatibles con MCP usan un archivo de configuración JSON (a menudo mcp.json). Añade una entrada de servidor HTTP apuntando al endpoint de SMOC con tu clave en el encabezado Authorization:

{
  "mcpServers": {
    "smoc": {
      "type": "http",
      "url": "https://api.smoc.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SMOC_API_KEY"
      }
    }
  }
}

Consulta la documentación MCP de tu editor para la ubicación exacta del archivo. Tras guardar, reinicia o recarga el editor.

---

Verificar la conexión

• Comprobación de estado: el endpoint expone GET https://api.smoc.ai/mcp/health.
• Comprobación de identidad: pide a la IA que ejecute la herramienta whoami — devuelve quién eres y el ámbito de tu empresa. Es la forma más rápida de confirmar que la clave funciona.

Descubrir herramientas

La IA no necesita saber los nombres de las herramientas de SMOC por adelantado. El flujo previsto es:

1. mcp_capabilities — lista las herramientas disponibles, tu rol y tu ámbito.
2. skills_search — describe la tarea en una frase corta para encontrar la herramienta adecuada.
3. skills_get — devuelve las entradas exactas y un ejemplo para la herramienta elegida.
4. Llama a la herramienta.

En la práctica, puedes simplemente preguntar en lenguaje natural (por ejemplo, "buscar mis contactos de SMOC en Oslo" o "mostrar hilos sin respuesta en la bandeja de entrada de LinkedIn") y el cliente elegirá la herramienta correcta.

Notas de seguridad

• Tu clave API se muestra una sola vez al crearla — guárdala en un gestor de contraseñas o variable de entorno.
• Nunca subas la clave a un repositorio Git ni la pegues en una configuración compartida/pública.
• Generar una nueva clave no revoca las existentes. Revoca las que no uses desde la lista de claves emitidas en Ajustes → Integraciones → MCP.
• Las claves de cliente son solo lectura por defecto y están confinadas a los datos de tu empresa. Las claves con escritura pueden actualizar contactos, etiquetas, listas, perfil de empresa, añadir URLs CPCS, gestionar la bandeja de entrada y enviar respuestas de texto. No pueden borrar datos, publicar flujos, activar/desactivar ni iniciar campañas de prospección en LinkedIn.
• Las herramientas de bandeja de entrada y conversación necesitan inbox:read en la clave. Las claves nuevas de Ajustes → Integraciones → MCP lo incluyen; las antiguas requieren rotación.

Resolución de problemas

• Faltan herramientas en la lista: la IA puede ejecutar mcp_capabilities y comprobar unavailableTools — indica el permiso exacto que le falta a tu clave.
• Fallo de autenticación: confirma que la clave es correcta, no ha sido revocada y que el encabezado es exactamente Authorization: Bearer <key>.
• El diálogo + Añadir de Claude no tiene encabezados de petición: usa el comando de Claude Code o la configuración mcp-remote de arriba. Asegúrate de que Node.js está instalado, el JSON es válido y has reiniciado completamente Claude Desktop tras editar la configuración.

Ver también

• Referencia de la API REST v2 — cada llamada POST /api/v2/{toolName}
• Conectar SMOC con la API REST
• API pública de contactos
• MCP para Claude, Cursor y VS Code