Servidor MCP

Integración del Protocolo de Contexto de Modelo

El servidor MCP de mindzieAPI permite que los asistentes de codificación de IA interactúen programáticamente con mindzieStudio. MCP (Model Context Protocol) proporciona una forma estandarizada para que las herramientas de IA accedan a capacidades externas.

Herramientas Disponibles

El servidor MCP expone las siguientes herramientas para asistentes de IA:

mindzie_list_block_types

Recupera información sobre los tipos de bloques disponibles (filtros, calculadores, enriquecimientos).

Parámetros

Parámetro	Tipo	Requerido	Descripción
`category`	String	No	Filtrar por categoría: "filters", "calculators", "unified", o omitir para solo filtros

Opciones de Categoría

Valor	Retorna
`"filters"`	Solo tipos de bloque filtro (por defecto)
`"calculators"`	Solo tipos de bloque calculador
`"unified"`	Todos los tipos de bloque incluyendo enriquecimientos, agrupados por categoría

Ejemplo: Obtener Todos los Tipos de Bloque (Recomendado)

mindzie_list_block_types category="unified"

Retorna metadatos completos para todos los tipos de bloque:

{
  "BlockTypes": [
    {
      "OperatorName": "CaseAttributeFilter",
      "DisplayName": "Filtro de Atributo de Caso",
      "Description": "Filtrar casos basados en valores de atributos",
      "Category": "Filtros de Atributos",
      "BlockType": "Filter",
      "DocumentationUrl": "/mindzie_studio/filters/case-attribute-filter",
      "UsageFrequency": "High",
      "CommonUseCases": ["Filtrar por segmento de cliente", "Enfocarse en regiones específicas"]
    },
    {
      "OperatorName": "CaseDurationCalculator",
      "DisplayName": "Calculador de Duración de Caso",
      "Description": "Calcular la duración total de los casos",
      "Category": "Calculadores de Tiempo",
      "BlockType": "Calculator",
      "DocumentationUrl": "/mindzie_studio/calculators/case-duration-calculator",
      "UsageFrequency": "High",
      "CommonUseCases": ["Analizar tiempos de ciclo", "Identificar casos lentos"]
    },
    {
      "OperatorName": "CaseStageCalculator",
      "DisplayName": "Calculador de Etapas de Caso",
      "Description": "Asignar etiquetas de etapa a casos basadas en patrones de actividad",
      "Category": "Análisis de Etapas",
      "BlockType": "Enrichment",
      "DocumentationUrl": "/mindzie_studio/enrichments/case-stage-calculator",
      "UsageFrequency": "Medium",
      "CommonUseCases": ["Rastrear progreso del caso", "Monitorear transiciones de etapa"]
    }
  ],
  "Categories": ["Filtros de Atributos", "Filtros de Tiempo", "Calculadores de Tiempo", "Análisis de Etapas"],
  "TotalCount": 45,
  "ByBlockCategory": {
    "Filter": [...],
    "Calculator": [...],
    "Enrichment": [...]
  }
}

Ejemplo: Obtener Solo Filtros

mindzie_list_block_types category="filters"

Ejemplo: Obtener Solo Calculadoras

mindzie_list_block_types category="calculators"

mindzie_list_projects

Lista los proyectos disponibles en el tenant actual.

Parámetros

Parámetro	Tipo	Requerido	Descripción
`tenant_id`	String	Sí	Identificador del tenant

mindzie_get_project

Obtiene detalles sobre un proyecto específico.

Parámetros

Parámetro	Tipo	Requerido	Descripción
`tenant_id`	String	Sí	Identificador del tenant
`project_id`	String	Sí	Identificador del proyecto

mindzie_execute_block

Ejecuta un bloque y devuelve los resultados.

Parámetros

Parámetro	Tipo	Requerido	Descripción
`tenant_id`	String	Sí	Identificador del tenant
`project_id`	String	Sí	Identificador del proyecto
`block_id`	String	Sí	Bloque a ejecutar

mindzie_generate_url

Genera URLs hacia páginas y entidades de mindzieStudio para navegación o compartir.

Parámetros

Parámetro	Tipo	Requerido	Descripción
`type`	String	Sí	Tipo de URL (ver Tipos de URL abajo)
`entity_id`	String	Condicional	ID de entidad para páginas específicas de entidad
`parent_id`	String	Condicional	ID padre (projectId o notebookId)

Tipos de URL

Páginas de Lista (no se requiere entity_id):

Tipo	parent_id	Descripción
`projects`	-	Lista de proyectos
`apps`	-	Lista de apps
`investigations`	projectId	Investigaciones para un proyecto
`dashboards-list`	projectId	Lista de dashboards para un proyecto
`datasets`	projectId	Conjuntos de datos para un proyecto
`actions`	projectId	Acciones para un proyecto
`bpmn`	projectId	Editor BPMN para un proyecto

Páginas de Entidad (se requiere entity_id):

Tipo	entity_id	parent_id	Descripción
`dashboard`	dashboardId	-	Dashboard individual
`analysis`	notebookId	-	Página de notebook/análisis
`block`	blockId	notebookId	Bloque específico
`enrichment`	enrichmentId	projectId (opcional)	Notebook de enriquecimiento

Ejemplo: Obtener URL de Dashboard

mindzie_generate_url type="dashboard" entity_id="{dashboardId}"

Retorna:

{
  "url": "https://host/navigate?type=dashboard&id=...",
  "entityType": "dashboard",
  "entityId": "...",
  "tenantId": "..."
}

Ejemplo: Obtener URL de Bloque

mindzie_generate_url type="block" entity_id="{blockId}" parent_id="{notebookId}"

Ejemplo: Obtener URL de Lista de Investigaciones

mindzie_generate_url type="investigations" parent_id="{projectId}"

Requisitos Previos

Antes de configurar el servidor MCP, asegúrate de tener:

Node.js 18 o superior - Descarga desde nodejs.org
Un token de API de mindzie - Generado desde la configuración de tu cuenta mindzieStudio
La URL de tu instancia mindzieStudio - Puede ser https://www.mindziestudio.com (nube) o tu URL on-premise

Instalación

El servidor MCP de mindzie se instala automáticamente vía npx - no requiere instalación manual:

npx -y @mindzie/mcp-server

Variables de Entorno

Variable	Requerida	Descripción
`MINDZIE_API_URL`	Sí	URL de tu instancia mindzieStudio
`MINDZIE_API_TOKEN`	Sí	Tu token de autenticación API

Configuración por Aplicación

Claude Desktop

Claude Desktop es la aplicación de escritorio de Anthropic para Claude AI.

Configuración en Windows

Edita el archivo de configuración en:

%APPDATA%\Claude\claude_desktop_config.json

Agrega el servidor MCP de mindzie:

{
  "mcpServers": {
    "mindzie": {
      "command": "npx",
      "args": ["-y", "@mindzie/mcp-server"],
      "env": {
        "MINDZIE_API_URL": "https://www.mindziestudio.com",
        "MINDZIE_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Configuración en macOS

Edita el archivo de configuración en:

~/Library/Application Support/Claude/claude_desktop_config.json

Agrega la misma configuración que en Windows arriba.

Después de Configurar

Guarda el archivo de configuración
Reinicia completamente Claude Desktop (cerrar y abrir)
Busca el ícono de martillo en la interfaz de chat - esto indica que las herramientas MCP están disponibles

Claude Code (CLI)

Claude Code es la interfaz de línea de comandos de Anthropic para Claude AI.

Agregar el Servidor MCP

Ejecuta este comando para registrar el servidor MCP de mindzie:

claude mcp add mindzie -- npx -y @mindzie/mcp-server

Configurar Variables de Entorno

Windows (PowerShell):

$env:MINDZIE_API_URL = "https://www.mindziestudio.com"
$env:MINDZIE_API_TOKEN = "your-api-token-here"

Windows (Command Prompt):

set MINDZIE_API_URL=https://www.mindziestudio.com
set MINDZIE_API_TOKEN=your-api-token-here

macOS/Linux:

export MINDZIE_API_URL="https://www.mindziestudio.com"
export MINDZIE_API_TOKEN="your-api-token-here"

Configuración Persistente

Agrega las variables de entorno a tu perfil de shell (.bashrc, .zshrc, o perfil de PowerShell) para que sean persistentes.

Cursor IDE

Cursor es un editor de código potenciado por IA construido sobre VS Code.

Ubicación del Archivo de Configuración

Crea o edita .cursor/mcp.json en tu directorio home o raíz del proyecto:

{
  "mcpServers": {
    "mindzie": {
      "command": "npx",
      "args": ["-y", "@mindzie/mcp-server"],
      "env": {
        "MINDZIE_API_URL": "https://www.mindziestudio.com",
        "MINDZIE_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Alternativa: Interfaz de Configuración

Abre Cursor
Ve a Settings (Ctrl/Cmd + ,)
Busca "MCP"
Haz clic en Edit in settings.json
Agrega la configuración del servidor mindzie

Verificar Configuración

Tras la configuración, reinicia Cursor y verifica que las herramientas de mindzie aparezcan en las herramientas disponibles del asistente IA.

Windsurf (Codeium)

Windsurf es el IDE potenciado por IA de Codeium.

Ubicación del Archivo de Configuración

Crea o edita el archivo MCP:

Windows:

%USERPROFILE%\.codeium\windsurf\mcp_config.json

macOS/Linux:

~/.codeium/windsurf/mcp_config.json

Configuración

{
  "mcpServers": {
    "mindzie": {
      "command": "npx",
      "args": ["-y", "@mindzie/mcp-server"],
      "env": {
        "MINDZIE_API_URL": "https://www.mindziestudio.com",
        "MINDZIE_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Verificar Configuración

Reinicia Windsurf
Abre el panel Cascade
Las herramientas mindzie deberían estar disponibles para consultas de minería de procesos

VS Code con la Extensión Continue

Continue es un asistente de codificación IA open-source para VS Code.

Instalar Continue

Abre VS Code
Ve a Extensiones (Ctrl/Cmd + Shift + X)
Busca "Continue" e instálala

Configurar Servidor MCP

Edita el archivo de configuración de Continue:

Windows:

%USERPROFILE%\.continue\config.json

macOS/Linux:

~/.continue/config.json

Agrega el servidor MCP en la sección mcpServers:

{
  "mcpServers": [
    {
      "name": "mindzie",
      "command": "npx",
      "args": ["-y", "@mindzie/mcp-server"],
      "env": {
        "MINDZIE_API_URL": "https://www.mindziestudio.com",
        "MINDZIE_API_TOKEN": "your-api-token-here"
      }
    }
  ]
}

Verificar Configuración

Reinicia VS Code
Abre el panel de Continue
Escribe /tools para ver las herramientas MCP disponibles incluyendo mindzie

Solución de Problemas

Servidor MCP No Se Conecta

Verifica la instalación de Node.js: Ejecuta node --version (debe ser 18+)
Prueba el servidor manualmente: Ejecuta npx -y @mindzie/mcp-server en la terminal
Revisa las variables de entorno: Asegúrate que MINDZIE_API_URL y MINDZIE_API_TOKEN estén definidas
Reinicia la aplicación: Cierra completamente y abre de nuevo

Errores de Autenticación

Verifica tu token de API: Los tokens pueden expirar o ser revocados
Revisa permisos del token: Asegúrate que el token tenga acceso a los recursos necesarios
Verifica la URL: Confirma que MINDZIE_API_URL apunte a tu instancia correcta

Herramientas No Aparecen

Revisa la sintaxis de configuración: Asegúrate que el JSON sea válido (sin comas al final)
Verifica la ubicación del archivo: El archivo de configuración debe estar en la ruta correcta
Consulta los registros de la aplicación: Busca mensajes de error relacionados con MCP
Reinicia completamente: Algunas aplicaciones almacenan en caché configuraciones MCP

Errores Comunes en la Configuración

Error	Solución
Falta el flag `-y` en args de npx	Agrega `-y` para omitir confirmación: `["-y", "@mindzie/mcp-server"]`
Coma final en JSON	Elimina las comas finales de objetos JSON
Ubicación incorrecta del archivo de configuración	Verifica dos veces la ruta según tu sistema operativo
Token contiene caracteres especiales	Asegura que el token esté correctamente entrecomillado en JSON

Buenas Prácticas de Seguridad

Nunca comitees tokens en control de versiones - Usa variables de entorno o gestores de secretos
Usa tokens específicos por proyecto - Crea tokens separados para diferentes proyectos
Rota los tokens regularmente - Especialmente en entornos de producción
Restringe permisos de tokens - Otorga solo acceso a los recursos necesarios
Monitorea el uso de tokens - Revisa periódicamente los logs de acceso API

Descubrimiento Unificado para Asistentes IA

El parámetro de categoría unified está diseñado específicamente para asistentes IA. Cuando una IA necesita entender qué capacidades de análisis están disponibles, puede hacer una única llamada MCP:

mindzie_list_block_types category="unified"

Esto devuelve todo lo que la IA necesita para:

Entender capacidades disponibles: Todos filtros, calculadoras y enriquecimientos
Seleccionar tipos de bloque apropiados: Basado en UsageFrequency y CommonUseCases
Enlazar a la documentación: Cada tipo de bloque incluye DocumentationUrl
Identificar relaciones: El campo RelatedBlocks sugiere tipos de bloque complementarios

Ejemplo de Flujo de Trabajo IA

Un asistente IA que ayuda a un usuario a analizar la duración de un proceso podría:

Llamar a mindzie_list_block_types category="unified" para descubrir capacidades
Encontrar tipos de bloque donde CommonUseCases contenga "duration"
Sugerir CaseDurationCalculator y WaitTimeCalculator
Crear los bloques apropiados usando la API
Ejecutar e interpretar resultados

Referencia de Campos en la Respuesta

Cuando se usa category="unified", cada tipo de bloque incluye:

Campo	Descripción	Uso IA
`OperatorName`	Identificador técnico	Usar al crear bloques vía API
`DisplayName`	Nombre legible	Mostrar a usuarios
`Description`	Descripción breve	Ayudar a entender el propósito
`Category`	Agrupación funcional	Organizar sugerencias
`BlockType`	Filter/Calculator/Enrichment	Determinar contexto de uso
`DocumentationUrl`	Enlace a documentación	Obtener información detallada
`UsageFrequency`	Alto/Medio/Bajo	Priorizar bloques comunes
`CommonUseCases`	Escenarios comunes	Emparejar con metas del usuario
`RelatedBlocks`	Tipos relacionados	Sugerir bloques complementarios
`UsageNotes`	Guía adicional	Proporcionar contexto a usuarios

Buenas Prácticas

Para Asistentes IA

Comenzar con descubrimiento unificado: Siempre llamar primero con category="unified"
Cachear resultados: Los metadatos de tipos de bloque cambian poco frecuentemente
Emparejar casos de uso: Usar el campo CommonUseCases para encontrar bloques relevantes
Sugerir bloques relacionados: Usar RelatedBlocks para ofrecer análisis complementarios

Para Desarrolladores

Asegura tus tokens: Nunca expongas tokens API en código cliente
Usa scopes apropiados: Solicita solo permisos necesarios
Maneja límites de tasa: Implementa retroceso exponencial para reintentos
Valida respuestas: Verifica errores antes de procesar resultados

Próximos Pasos

API de Tipos de Bloque Unificados - Documentación API directa
API de Generación de URL - Generar URLs de navegación
Resumen de Herramientas de Codificación IA - Integración general de herramientas IA
Autenticación - Detalles de autenticación API