Cocos Creator MCP 연결 후 Cursor가 고장난 것처럼 보일 때: 증상별 연결 수정

Cursor가 고장난 것처럼 보일 때: 증상별 연결 수정

Cocos MCP를 설치하고 Cursor에서 한 번 구성한 후, 많은 사람들이 Cursor가 고장났다고 느낍니다: 채팅이 씬에 접근할 수 없거나, MCP 패널이 모두 빨간색이거나, 어제는 작동했는데 오늘은 사라진 경우입니다. 대부분의 경우 Cursor 자체는 정상입니다—MCP 브리지가 다운된 것입니다. Creator 쪽 서버가 실행되지 않거나, Cursor의 구성/새로고침이 적용되지 않은 것입니다.

이 가이드는 Cursor에서 볼 수 있는 증상에서 시작하여, 다음에 어떤 계층을 확인해야 하는지 알려줍니다. 긴 Creator 단계(확장 프로그램 가져오기, 활성화 코드, 포트 충돌)는 일반 가이드에 있습니다: Cocos MCP 연결 문제 해결. 제품 경계가 필요하다면 Cocos Creator MCP란 무엇인가를 참조하세요.

먼저: Cursor가 고장난 것인지, 브리지가 고장난 것인지

느껴지는 증상	더 가능성 높은 원인
Cursor는 여전히 일반 코드를 작성하지만 Cocos 씬/노드에 도달하지 못함	MCP가 연결되지 않았거나 도구가 활성화되지 않음
MCP 목록에 cocos-creator(또는 Quick configure에서 생성된 이름)가 없음	구성이 작성되지 않았거나 새로고침 필요
서비스 이름은 있지만 오류/연결 끊김 표시	Creator가 실행 중이지 않음, 잘못된 URL/포트, 또는 새로고침 필요
연결됨으로 표시되지만 열린 씬의 노드를 나열할 수 없음	잘못된 프로젝트, 도구가 선택 해제됨, 또는 잘못된 읽기 전용 검사

Claude Code, Codex 및 유사한 MCP 클라이언트도 동일한 아이디어를 따릅니다: 클라이언트에 정상적인 서비스 항목이 있는지 확인한 다음 Creator를 확인하세요.

1단계: Cursor 내부의 MCP만 확인

Cursor의 MCP/도구 설정(메뉴 레이블은 버전에 따라 다를 수 있음)을 열고 다음을 확인하세요:

1. **cocos-creator**가 나타나는지 (또는 Creator의 Quick configure에서 작성된 이름)
2. 상태가 연결/사용 가능인지—오류, 연결 끊김, 또는 공백 상태가 아닌지
3. 방금 구성을 변경했거나 Creator에서 Auto configure를 실행한 경우: Reload Window(또는 이에 상응하는 MCP 새로고침)를 수행한 후 목록을 다시 확인하세요

일반적인 경우: Creator가 이미 Running으로 표시되지만 Cursor는 여전히 오래된 구성을 보유하고 있습니다—새로고침 없이는 “갑자기 고장난” 것처럼 느껴집니다.

2단계: URL이 로컬 Creator를 가리키는지 확인

Cursor MCP 항목은 로컬 브리지 URL을 대상으로 해야 합니다. 일반적으로:

• http://127.0.0.1:3000/mcp
• 또는 http://localhost:3000/mcp

Creator의 MCP 패널에 표시된 포트를 사용하세요(기본값은 보통 3000; 변경했다면 패널과 일치시켜야 합니다).

또한 Cocos Creator를 열고 MCP 패널이 동일한 프로젝트에 대해 Running인지 확인하세요. 패널이 실행 중이 아니면 Cursor에서 Reload를 해도 도구가 나타나지 않습니다.

제품 페이지(주요 버전에 맞는 패키지를 선택하세요; 혼용하지 마세요):

• Cocos MCP 3.x
• Cocos MCP 2.x

3단계: 그래도 실패하면 계층별로 점프

MCP 경로에는 네 개의 계층이 있습니다. 어느 계층에서든 실패하면 “Cursor가 고장났다 / 연결되지 않는다”처럼 보일 수 있습니다:

1. 프로젝트에 플러그인이 있고 활성화됨
        ↓
2. 패널 활성화 (계정 / 라이선스 코드)
        ↓
3. MCP 서버가 Running으로 표시됨 (localhost)
        ↓
4. Cursor에 구성이 작성되고 MCP 목록에 연결됨으로 표시됨

Cursor에서 보이는 것	먼저 확인할 곳
서비스 항목이 전혀 없음	계층 4: Creator로 돌아가 → Quick configure → Auto configure 후 Reload; 자세한 내용은 일반 가이드
항목은 있지만 오류/연결 불가	계층 3: Creator가 Running인지, 포트가 일치하는지, localhost가 차단되지 않았는지
Creator 내부에 MCP 메뉴가 없음	계층 1: 2.x/3.x 패키지 혼용, 가져오기 경로, 재시작 (일반 가이드 증상 A)
패널이 시작되지 않거나 활성화되지 않음	계층 2: 계정 및 활성화 (일반 가이드)
연결되었지만 노드를 나열할 수 없음	올바른 프로젝트가 열려 있는지 확인; 아래 읽기 전용 스모크 테스트 실행; 그런 다음 도구 토글 확인

전체 설치:

• Cocos Creator 3.x MCP 설치
• Cocos Creator 2.x MCP 설치

4단계: 스모크 테스트 (수정 확인)

Cursor에서 읽기 전용 확인으로 시작하세요. 예를 들어:

Cocos Creator에서 현재 열려 있는 씬의 루트 노드를 나열해 주세요.

응답이 편집기 계층 구조와 일치하면 브리지가 작동하는 것입니다. 선택적으로 되돌릴 수 있는 쓰기 작업(임시 노드 생성 후 삭제)을 수행하세요. 큰 편집 전에 커밋하고; 브리지를 localhost에서만 유지하세요—MCP 포트를 공개 인터넷에 노출하지 마세요.

자주 묻는 질문

Cocos Creator MCP 이후 “Cursor가 고장났다”는 것은 보통 무엇을 의미하나요?
일반적인 증상: MCP 서비스 항목이 없거나, 빨간색/오류 상태이거나, 연결은 되었지만 도구/노드가 없는 경우입니다. 대부분의 경우 Cursor 충돌이 아니라 4계층 브리지에서 한 계층이 누락된 것입니다.

Cursor를 먼저 확인해야 하나요, Creator를 먼저 확인해야 하나요?
Cursor의 MCP 목록부터 확인하세요(누락 vs 빨간색). 그런 다음 Creator를 확인하세요: 플러그인 가져오기/활성화, 패널 활성화, 서버 실행 중, 포트가 구성과 일치하는지. 이 문서의 증상 표를 사용하세요.

연결되었지만 노드가 없으면 어떻게 하나요?
올바른 프로젝트/씬이 열려 있는지 확인하고, 읽기 전용 스모크 테스트(루트 노드 나열)를 실행하세요. 그래도 실패하면 도구 토글 및 권한을 확인하세요. 전체 경로: 연결 문제 해결.

Cursor를 다시 설치해야 하나요?
보통은 아닙니다. Creator의 “빠른 구성 → 자동 구성”을 선호하고, MCP를 다시 로드한 후 localhost 포트를 확인하세요. 카테고리 경계: Cocos Creator MCP란 무엇인가.