Guía Completa: Conectar Agentes de IA a VIBEWORKFLOW con Model Context Protocol (MCP)

El Model Context Protocol (MCP) es el estándar abierto que permite a los modelos de inteligencia artificial conectarse de forma segura a datos y herramientas externas. En VIBEWORKFLOW, hemos implementado un servidor MCP nativo de alto rendimiento para que agentes como Claude Desktop, Cursor, Windsurf, Claude Code, Antigravity y asistentes personalizados interactúen directamente con el ADN operativo de tu empresa en tiempo real.

En esta guía exhaustiva de Soporte y Aprendizaje, encontrarás todos los insumos, credenciales, configuraciones, catálogo de herramientas y directrices de ingeniería para conectar agentes de IA a tu espacio de trabajo de forma óptima y sin errores.

---

1. ¿Por qué conectar tus agentes de IA a VIBEWORKFLOW vía MCP?

Hasta hoy, alimentar a un agente con el contexto de tu empresa implicaba copiar y pegar largos manuales en PDF, notas de reuniones o capturas de pantalla. Este enfoque es estático, pierde la jerarquía del proceso y genera alucinaciones.

Con el servidor MCP oficial de VIBEWORKFLOW, tu agente de IA puede:

• Inspeccionar en tiempo real los flujos, áreas y procesos mapeados en tu organización.
• Crear y conectar tarjetas en el canvas (acciones, soluciones, KPIs, responsables, tareas) respetando las reglas de diseño y la ontología empresarial.
• Auditar cuellos de botella y brechas en tus flujos existentes y proponer mejoras ejecutables.
• Consultar analítica SQL de solo lectura sobre indicadores de procesos y volumen de operaciones.
• Interconectar macroflujos que articulan diferentes áreas de la organización.

---

2. Insumos y Requisitos Previos

Antes de configurar tu agente, asegúrate de contar con los siguientes elementos:

1. Cuenta activa en VIBEWORKFLOW con plan PRO o Enterprise (las conexiones MCP requieren permisos de nivel PRO).
2. Acceso a al menos un Entorno (Environment) creado en tu cuenta.
3. Node.js (versión 18 o superior) instalado en tu equipo si vas a usar herramientas de escritorio como Claude Desktop o editores basados en Electron.
4. Cliente compatible con MCP:
   • Claude Desktop (macOS, Windows).
   • Cursor IDE / Windsurf.
   • Claude Code / Gemini CLI / Antigravity.
   • Aplicaciones personalizadas con el SDK oficial @modelcontextprotocol/sdk.

---

3. Procedimiento: Cómo Generar tu API Key de MCP

Para autenticar a cualquier agente externo, necesitas una clave personal con prefijo vibe_mcp_.

1. Inicia sesión en tu cuenta de VIBEWORKFLOW y dirígete al menú lateral izquierdo: haz clic en Integraciones (/app/integrations).
2. Localiza y despliega la tarjeta titulada Model Context Protocol (MCP).
3. En la sección Tus API Keys de MCP, escribe una etiqueta descriptiva en el campo de texto (por ejemplo: "Claude Desktop - Mi Laptop" o "Cursor Dev").
4. Haz clic en el botón morado + Generar.
5. Aparecerá una ventana modal con tu nueva clave de acceso (inicia con vibe_mcp_...).
6. Copia la clave inmediatamente y guárdala en tu gestor de contraseñas. Por estrictas políticas de seguridad criptográfica, la clave solo se muestra una vez y luego se almacena hasheada (SHA-256) en nuestra base de datos.

Nota de Seguridad: Si sospechas que tu API Key fue expuesta, puedes revocarla con un solo clic desde la misma tabla en el panel de Integraciones haciendo clic en el icono del cubo de basura.

---

4. Guía de Conexión Paso a Paso por Cliente

4.1 Claude Desktop (macOS y Windows)

Claude Desktop se comunica con servidores MCP remotos a través del puente de línea de comandos mcp-remote.

Ubicación del archivo de configuración:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Abre este archivo en tu editor favorito y agrega la entrada correspondiente a vibeworkflow:

{
  "mcpServers": {
    "vibeworkflow": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://vibeworkflow.co/api/mcp",
        "--header",
        "Authorization: Bearer vibe_mcp_TU_API_KEY_AQUI"
      ]
    }
  }
}

Reinicia Claude Desktop. Verás un icono de herramientas (martillo o enchufe) en la esquina inferior del chat confirmando que las herramientas de VIBEWORKFLOW están activas.

---

4.2 Cursor IDE

Cursor permite conectar servidores MCP para que el modelo tenga contexto de tus procesos mientras programas:

1. Abre Cursor y ve a Cursor Settings > Features > MCP Servers.
2. Haz clic en Add New MCP Server.
3. Ingresa los siguientes datos:
   • Name: vibeworkflow
   • Type: command
   • Command: npx -y mcp-remote https://vibeworkflow.co/api/mcp --header "Authorization: Bearer vibe_mcp_TU_API_KEY_AQUI"

O agrégalo directamente a tu archivo .cursor/mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "vibeworkflow": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://vibeworkflow.co/api/mcp",
        "--header",
        "Authorization: Bearer vibe_mcp_TU_API_KEY_AQUI"
      ]
    }
  }
}

---

4.3 Clientes Personalizados y SDK de TypeScript/Node

Si estás desarrollando tu propio agente de automatización o worker en segundo plano, conéctate mediante el transporte HTTP Streamable nativo:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const apiKey = "vibe_mcp_TU_API_KEY";
const client = new Client({ name: "mi-agente-empresa", version: "1.0.0" });

const transport = new StreamableHTTPClientTransport(
  new URL("https://vibeworkflow.co/api/mcp"),
  {
    requestInit: {
      headers: { Authorization: `Bearer ${apiKey}` },
    },
  }
);

await client.connect(transport);

// Listar entornos accesibles
const environments = await client.callTool({
  name: "list_environments",
  arguments: {},
});

console.log("Entornos disponibles:", environments);

---

5. Catálogo de Capacidades y Herramientas (Taxonomía MCP)

El servidor MCP de VIBEWORKFLOW expone más de 38 herramientas de alta precisión organizadas por dominios operativos:

---

6. Aclaraciones Críticas y Reglas de Oro de Arquitectura

Para que tus agentes operen con máxima estabilidad y no generen diagramas rotos o errores 401/400, deben respetar tres reglas fundamentales:

Regla 1: Autenticación obligatoria por cabecera HTTP Authorization

• El protocolo MCP ejecuta dos fases: un apretón inicial (handshake SSE GET) y llamadas a herramientas (POST JSON-RPC).
• Siempre debes enviar la API Key en el encabezado HTTP: Authorization: Bearer vibe_mcp_...
• Advertencia: Pasar la clave únicamente como parámetro query (?key=vibe_mcp_...) permite iniciar la conexión GET, pero fallará con error 401 en las solicitudes POST posteriores de ejecución de herramientas.

Regla 2: Reglas de Renderizado y Tarjetas Apiladas (Stacked Cards)

• En VIBEWORKFLOW, las tarjetas se dividen en dos categorías:
  1. Tarjetas Base: accion y solucion. Conforman la línea horizontal del proceso.
  2. Tarjetas Acopladas (Stacked): responsable, indicador (KPI), tarea, deseo, funcionalidad, punto_contacto.
• Las tarjetas acopladas NUNCA se conectan con líneas físicas (edges). Se posicionan dentro de su tarjeta padre utilizando parentId y coordenadas relativas. El lienzo de VIBEWORKFLOW las agrupa automáticamente en una columna vertical elegante y compacta.
• Las líneas físicas (edges) solo deben conectar:
  • Acción -> Acción (secuencia cronológica).
  • Solución -> Acción (sistema que habilita una acción).

Regla 3: Formato Nativo JSONB para el campo data

• En nuestra base de datos, el atributo data de cada tarjeta es de tipo jsonb.
• Si construyes peticiones personalizadas con clientes de base de datos o APIs, envía el objeto JSON directamente. Nunca apliques JSON.stringify(), ya que esto generaría una doble serialización que impediría el renderizado correcto de la tarjeta en el navegador.

---

7. Ejemplo de Prompt para tu Agente una vez Conectado

Una vez que tu agente tenga el MCP activo en Claude Desktop o Cursor, prueba indicarle prompts directos como:

"Explora mis entornos de VIBEWORKFLOW, lista los flujos del entorno principal y dime qué responsables y KPIs están vinculados al flujo de Ventas."

O para crear un proceso nuevo:

"Crea un nuevo flujo llamado 'Atención a Garantías de Calidad'. Agrega 4 acciones principales conectadas secuencialmente, coloca un responsable 'Líder de Soporte' en la primera acción y un KPI 'Tiempo de Respuesta < 24h'. Asegúrate de usar la herramienta create_flow_graph."

---

8. Preguntas Frecuentes (FAQ)

¿Puedo conectar varios agentes con la misma API Key? Sí, puedes usar una misma API Key en diferentes herramientas. Sin embargo, recomendamos crear una API Key por cada aplicación o dispositivo (por ejemplo, una para Claude Desktop y otra para Cursor) para monitorear su último uso y poder revocar accesos individuales sin afectar a los demás.

¿Qué modelos de IA son compatibles con el MCP de VIBEWORKFLOW? Cualquier modelo que soporte llamada a herramientas (Tool Calling) a través del protocolo MCP: Claude 3.5/3.7 Sonnet, Claude 3.5 Haiku, modelos Gemini 2.0/2.5 vía proxies compatibles, y OpenAI GPT-4o a través de clientes MCP como Cursor o Windsurf.

¿Dónde puedo solicitar nuevas herramientas o reportar dudas técnicas? Visita nuestro centro de soporte en VIBEWORKFLOW Blog o contáctanos directamente a través del canal de soporte en tu panel de usuario.