Solución de problemas de conexión de Cocos MCP: Cursor no muestra cocos-creator

Primero: ¿qué capa falló?

Si dices “Cursor se rompió / no conecta”, empieza por síntomas en Cursor: Cursor roto tras Cocos Creator MCP.

Si aún no tienes claro qué puede hacer MCP y en qué se diferencia de “Cocos Creator AI”, lee primero Qué es Cocos Creator MCP.

El camino MCP tiene cuatro capas. La falla en cualquier capa se ve como “no se puede conectar”:

1. Extensión instalada y habilitada
        ↓
2. Panel activado (cuenta / código de licencia)
        ↓
3. Servidor MCP muestra Ejecutándose (localhost)
        ↓
4. Configuración del IDE de IA escrita y la lista MCP muestra conectado

Lo que ves	Revisa primero
Sin menú Extensión → Cocos MCP Server / MCP Server	Capa 1: versión del paquete, ruta de importación, reiniciar
El panel se abre pero no puede iniciar / permanece sin activar	Capa 2: cuenta y licencia
Hiciste clic en Iniciar pero nunca Ejecutándose	Capa 3: puerto, firewall, activación
Creator muestra Ejecutándose, Cursor no tiene cocos-creator	Capa 4: configuración rápida, recarga de MCP, archivo de configuración
Cursor muestra conectado pero no puede listar nodos de escena	Prompt de verificación, alternar herramientas, proyecto correcto abierto

Síntoma A: Sin extensión MCP en el menú

Causas probables

1. Paquetes 2.x / 3.x mezclados
2. 3.x: no importado en el Administrador de Extensiones, o aún deshabilitado
3. 2.x: no está en packages/<nombre-del-plugin>/, o hay un nivel extra de anidamiento al descomprimir
4. 2.x: archivos colocados pero Creator no se reinició completamente

Soluciones

Creator 3.x:

1. Descarga desde Cocos MCP 3.x—no el paquete 2.x
2. Abre el proyecto → Extensión → Administrador de Extensiones → Importar → selecciona el zip 3.x
3. Confirma que cocos-mcp-server está habilitado; habilítalo si está deshabilitado
4. Si el menú aún falta: sal de Creator y vuelve a abrir el mismo proyecto

Creator 2.x:

1. Descarga desde Cocos MCP 2.x
2. Después de descomprimir, el árbol debería verse así:

raíz-del-proyecto/
  packages/
    <nombre-del-plugin>/          ← archivos del plugin directamente aquí
      package.json                ← debería existir en esta ruta (nombre según el paquete)

3. Anidamiento incorrecto ejemplo:

packages/
  xxx-mcp-descomprimido/
    <nombre-del-plugin>/
      package.json

4. Corrige la ruta, luego sal y reinicia Creator (no solo actualices la escena). Revisa Extensión → MCP Server.

Síntoma B: El panel se abre, pero la activación falla o el servicio no se inicia

Causas probables

• La cuenta carece del derecho Pro correspondiente
• El código de licencia expiró o el correo no coincide
• Hiciste clic en Iniciar antes de la activación

Soluciones

1. Abre el panel MCP (3.x: Extensión → Cocos MCP Server → Abrir Panel MCP; 2.x: Extensión → MCP Server)
2. Activa con cualquiera de:
   • Cuenta VberAI + contraseña
   • Correo + código de licencia
3. Confirma el plan / código en el centro de cuentas oficial, luego reintenta en el panel
4. Solo después de la activación abre la configuración del Servidor MCP y haz clic en Iniciar

Sin activación, el servidor generalmente nunca llega a Ejecutándose. Arregla el lado del editor antes de culpar a Cursor.

Síntoma C: Hiciste clic en Iniciar, pero nunca Ejecutándose

Causas probables

1. Aún no activado (ver síntoma B)
2. Puerto en uso (3.x a menudo usa el predeterminado 3000; 2.x sigue el panel)
3. Firewall / software de seguridad bloquea la escucha en localhost

Soluciones

1. Anota el puerto en la página de configuración del Servidor MCP (los ejemplos a continuación usan 3000—reemplázalo con el valor de tu panel)
2. Verifica si algo ya está escuchando:

macOS / Linux:

lsof -iTCP:3000 -sTCP:LISTEN

Windows (PowerShell):

netstat -ano | findstr :3000

3. Si otro proceso tiene el puerto:
   • detén ese proceso, o
   • elige un puerto libre en el panel MCP, luego Iniciar de nuevo
4. Asegúrate de que el firewall permita 127.0.0.1 (no expongas MCP a internet público)
5. Cuando el panel muestre Ejecutándose, configura el IDE de IA

Síntoma D: Creator está Ejecutándose, Cursor no tiene cocos-creator

La mayoría de los informes de “fallo de conexión” llegan aquí: editor OK, cliente nunca ingirió la configuración.

Soluciones (en orden)

1. En Creator, confirma que el panel MCP sigue Ejecutándose (los cambios de puerto o reinicios del editor pueden detenerlo)
2. Abre el Administrador de Herramientas y habilita las herramientas que necesitas
3. Abre Configuración Rápida → elige Cursor → Auto Config hasta que la UI muestre Configurado
4. En Cursor → lista MCP / herramientas:
   • Deberías ver cocos-creator (o el nombre que se muestra en el panel)
   • Si falta: Recargar MCP (o reiniciar Cursor) y verifica de nuevo
5. Si aún falta: verifica que la configuración MCP de Cursor contenga el puente local (127.0.0.1 + el puerto del panel)

La salida de Auto Config varía según la versión de Cursor. Al inspeccionar manualmente:

• El nombre del servicio coincide con Cocos MCP (ej. cocos-creator)
• El host es 127.0.0.1 o localhost, el puerto coincide con Creator
• No es una IP LAN o pública por error

Después de cualquier edición de configuración, recarga MCP de nuevo o la UI mantiene el estado anterior.

Otros IDEs de IA

En Configuración Rápida, elige Claude Code, Codex, Windsurf, Cline, etc., luego Auto Config → recargar MCP en ese cliente. Configurar Cursor no conecta todos los IDEs.

Síntoma E: Muestra conectado, pero no puede listar la escena / editar nodos

Causas probables

1. El proyecto / escena abierta en Creator no coincide con lo que preguntaste
2. Las herramientas necesarias no están marcadas en Administrador de Herramientas
3. Solo verificaste “archivos en disco”, no contexto del editor

Verificación

Envía un prompt de solo lectura en Cursor:

Lista los nombres de los nodos raíz de la escena actualmente abierta en Cocos Creator.

Resultado	Significado
Coincide con la Jerarquía	Puente OK; intenta una pequeña escritura a continuación
Error claro / sin herramientas	Regresa a los síntomas C/D
Nombres de nodos inventados	MCP probablemente no se usa; verifica la conexión y las alternancias de herramientas

Luego intenta una pequeña escritura (crea un nodo temporal y elimínalo). Confirma antes de ediciones grandes.

Tabla rápida 2.x vs 3.x

Elemento	Creator 3.x	Creator 2.x
Página del producto	cocos (3.x)	cocos2x
Instalación	Administrador de Extensiones → Importar	Descomprimir en packages/ del proyecto
Después de instalar	Habilitar en la lista	Debes reiniciar Creator
Paquete	Solo 3.x	Solo 2.x
Pasos completos	Instalación 3.x	Instalación 2.x

Los paquetes mezclados a menudo se muestran como “sin menú” o “fallo de importación”—usa esta tabla primero.

Orden recomendado (lista de verificación de 5 minutos)

Marca en orden; la mayoría de las fallas están en los primeros cuatro:

1. La versión principal de Creator coincide con el zip MCP (2.x ↔ 2.x, 3.x ↔ 3.x)
2. Extensión habilitada / ruta packages correcta; 2.x reiniciado
3. Panel activado correctamente
4. Panel muestra Ejecutándose; puerto libre
5. Configuración Rápida → Auto Config para el IDE actual
6. MCP recargado en el IDE de IA; cocos-creator listado
7. Prompt de solo lectura lista las raíces de la escena actualmente abierta

Si aún falla, captura esto

Al pedir soporte o a un compañero, incluye:

• Versión exacta de Creator (ej. 3.8.x / 2.4.x)
• Tipo de paquete MCP (2.x o 3.x Pro)
• Si el panel está Ejecutándose, y el puerto
• Nombre/versión del IDE de IA y captura de pantalla de la lista MCP
• Prompt de solo lectura exacto y respuesta

Mantén el puente solo en localhost; no publiques el puerto MCP.

Documentos relacionados

• Instalación de Cocos Creator 3.x MCP
• Instalación de Cocos Creator 2.x MCP
• Guía de video de configuración de Cocos Creator MCP
• Guía de selección de motor: Godot MCP vs Unity MCP vs Cocos MCP