Solução de Problemas de Conexão do Cocos MCP: Cursor Não Mostra cocos-creator

Se a frase é “Cursor quebrou / não conecta”, comece pelos sintomas no Cursor: Cursor quebrado após Cocos Creator MCP.

Se ainda não está claro o que o MCP faz e como difere de “Cocos Creator AI”, leia primeiro O que é Cocos Creator MCP.

Ao conectar o Cocos MCP ao Cursor (ou outro cliente MCP), o bloqueio usual não são “prompts ruins”—é que a ponte nunca conecta: o servidor do editor está desligado, ou o IDE de IA nunca lista cocos-creator.

Este guia segue sintoma → causa → correção para o Creator 2.x e 3.x. Fluxos completos de instalação:

• Instalação do Cocos Creator 3.x MCP
• Instalação do Cocos Creator 2.x MCP

Exemplos usam Cursor; Claude Code, Codex e clientes semelhantes seguem as mesmas verificações de recarregamento / configuração.

Primeiro: qual camada falhou?

O caminho do MCP tem quatro camadas. A falha em qualquer camada parece “não é possível conectar”:

1. Extensão instalada e habilitada
        ↓
2. Painel ativado (conta / código de licença)
        ↓
3. Servidor MCP mostra Executando (localhost)
        ↓
4. Configuração do IDE de IA escrita e lista MCP mostra conectado

O que você vê	Verifique primeiro
Sem menu Extensão → Cocos MCP Server / MCP Server	Camada 1: versão do pacote, caminho de importação, reiniciar
Painel abre, mas não inicia / permanece não ativado	Camada 2: conta e licença
Clicou em Iniciar, mas nunca Executando	Camada 3: porta, firewall, ativação
Creator mostra Executando, Cursor não tem cocos-creator	Camada 4: configuração rápida, recarregar MCP, arquivo de configuração
Cursor mostra conectado, mas não é possível listar nós da cena	Prompt de verificação, alternâncias de ferramentas, projeto correto aberto

Sintoma A: Sem extensão MCP no menu

Causas prováveis

1. Pacotes 2.x / 3.x misturados
2. 3.x: não importado no Gerenciador de Extensões, ou ainda desabilitado
3. 2.x: não está em packages/<nome-do-plugin>/, ou um nível extra de aninhamento de descompactação
4. 2.x: arquivos colocados, mas o Creator não foi totalmente reiniciado

Correções

Creator 3.x:

1. Baixe de Cocos MCP 3.x—não o pacote 2.x
2. Abra o projeto → Extensão → Gerenciador de Extensões → Importar → selecione o zip 3.x
3. Confirme que cocos-mcp-server está habilitado; habilite se estiver desabilitado
4. Se o menu ainda estiver ausente: saia do Creator e reabra o mesmo projeto

Creator 2.x:

1. Baixe de Cocos MCP 2.x
2. Após descompactar, a árvore deve ficar assim:

raiz-do-seu-projeto/
  packages/
    <nome-do-plugin>/          ← arquivos do plugin diretamente aqui
      package.json              ← deve existir neste caminho (nome conforme o pacote)

3. Aninhamento errado exemplo:

packages/
  xxx-mcp-unzip/
    <nome-do-plugin>/
      package.json

4. Corrija o caminho, depois saia e reinicie o Creator (não apenas atualize a cena). Verifique Extensão → MCP Server.

Sintoma B: O painel abre, mas a ativação falha ou o serviço não inicia

Causas prováveis

• A conta não tem direito Pro correspondente
• Código de licença expirado ou e-mail incompatível
• Clicou em Iniciar antes da ativação

Correções

1. Abra o painel MCP (3.x: Extensão → Cocos MCP Server → Abrir Painel MCP; 2.x: Extensão → MCP Server)
2. Ative com qualquer um:
   • Conta VberAI + senha
   • E-mail + código de licença
3. Confirme o plano / código no centro de contas oficial e tente novamente no painel
4. Somente após a ativação abra as configurações do Servidor MCP e clique em Iniciar

Sem ativação, o servidor geralmente nunca atinge Executando. Corrija o lado do editor antes de culpar o Cursor.

Sintoma C: Clicou em Iniciar, mas nunca Executando

Causas prováveis

1. Ainda não ativado (veja sintoma B)
2. Porta em uso (3.x geralmente usa 3000 por padrão; 2.x segue o painel)
3. Firewall / software de segurança bloqueia a escuta em localhost

Correções

1. Anote a porta na página de configurações do Servidor MCP (exemplos abaixo usam 3000—substitua pelo valor do seu painel)
2. Verifique se algo já está escutando:

macOS / Linux:

lsof -iTCP:3000 -sTCP:LISTEN

Windows (PowerShell):

netstat -ano | findstr :3000

3. Se outro processo estiver usando a porta:
   • pare esse processo, ou
   • escolha uma porta livre no painel MCP e Inicie novamente
4. Garanta que o firewall permita 127.0.0.1 (não exponha o MCP à internet pública)
5. Quando o painel mostrar Executando, configure o IDE de IA

Sintoma D: Creator está Executando, Cursor não tem cocos-creator

A maioria dos relatos de “falha de conexão” está aqui: editor OK, cliente nunca ingeriu a configuração.

Correções (em ordem)

1. No Creator, confirme que o painel MCP ainda está Executando (mudanças de porta ou reinicializações do editor podem pará-lo)
2. Abra o Gerenciador de Ferramentas e habilite as ferramentas necessárias
3. Abra Configuração Rápida → escolha Cursor → Configuração Automática até a interface mostrar Configurado
4. No Cursor → lista MCP / ferramentas:
   • Você deve ver cocos-creator (ou o nome mostrado no painel)
   • Se ausente: Recarregar MCP (ou reinicie o Cursor) e verifique novamente
5. Ainda ausente: verifique se a configuração MCP do Cursor contém a ponte local (127.0.0.1 + a porta do painel)

A saída da Configuração Automática varia conforme a versão do Cursor. Ao inspecionar manualmente:

• O nome do serviço corresponde ao Cocos MCP (ex.: cocos-creator)
• O host é 127.0.0.1 ou localhost, a porta corresponde ao Creator
• Não é um IP de LAN ou público por engano

Após qualquer edição de configuração, recarregue o MCP novamente ou a interface mantém o estado antigo.

Outros IDEs de IA

Na Configuração Rápida, escolha Claude Code, Codex, Windsurf, Cline, etc., depois Configuração Automática → recarregue o MCP nesse cliente. Configurar o Cursor não conecta todos os IDEs.

Sintoma E: Mostra conectado, mas não é possível listar cena / editar nós

Causas prováveis

1. O projeto / cena aberto no Creator não corresponde ao que você perguntou
2. Ferramentas necessárias desmarcadas no Gerenciador de Ferramentas
3. Você apenas verificou “arquivos no disco”, não o contexto do editor

Verificação

Envie um prompt somente leitura no Cursor:

Liste os nomes dos nós raiz da cena atualmente aberta no Cocos Creator.

Resultado	Significado
Corresponde à Hierarquia	Ponte OK; tente uma pequena escrita em seguida
Erro claro / sem ferramentas	Volte aos sintomas C/D
Nomes de nós inventados	MCP provavelmente não usado; verifique conexão e alternâncias de ferramentas

Depois tente uma pequena escrita (crie um nó temporário e exclua-o). Faça commit antes de grandes edições.

Tabela rápida 2.x vs 3.x

Item	Creator 3.x	Creator 2.x
Página do produto	cocos (3.x)	cocos2x
Instalação	Gerenciador de Extensões → Importar	Descompacte no projeto packages/
Após instalação	Habilite na lista	Deve reiniciar o Creator
Pacote	Somente 3.x	Somente 2.x
Passos completos	Instalação 3.x	Instalação 2.x

Pacotes misturados geralmente aparecem como “sem menu” ou “falha na importação”—use esta tabela primeiro.

Ordem recomendada (lista de verificação de 5 minutos)

Marque em ordem; a maioria das falhas está nos primeiros quatro:

1. A versão principal do Creator corresponde ao zip do MCP (2.x ↔ 2.x, 3.x ↔ 3.x)
2. Extensão habilitada / caminho packages correto; 2.x reiniciado
3. Painel ativado com sucesso
4. Painel mostra Executando; porta livre
5. Configuração Rápida → Configuração Automática para o IDE atual
6. MCP recarregado no IDE de IA; cocos-creator listado
7. Prompt somente leitura lista raízes da cena atualmente aberta

Se ainda falhar, capture isto

Ao pedir suporte ou a um colega, inclua:

• Versão exata do Creator (ex.: 3.8.x / 2.4.x)
• Tipo de pacote MCP (2.x ou 3.x Pro)
• Se o painel está Executando, e a porta
• Nome/versão do IDE de IA e captura de tela da lista MCP
• Prompt exato somente leitura e resposta

Mantenha a ponte apenas em localhost; não publique a porta MCP.

Documentos relacionados

• Instalação do Cocos Creator 3.x MCP
• Instalação do Cocos Creator 2.x MCP
• Vídeo de configuração do Cocos Creator MCP
• Guia de escolha de engine: Godot MCP vs Unity MCP vs Cocos MCP