MCP 인증 실패, needsAuth일 때 뭐 하나
MCP 인증 실패는 mcp.json이 안 읽히거나 프로세스가 안 뜨는 연결 실패와 축이 다릅니다. 서버 카드는 Customize에 보이는데 상태가 needsAuth(또는 authentication required)이고, 채팅의 Available Tools가 비거나 도구 호출이 바로 거절될 때입니다. 가격·플랜·토큰 숫자·API 키 값은 다루지 않습니다.
이 글은 증상, 재연결 순서, 도구 목록이 비면만 정리합니다. 근거는 Cursor MCP 문서의 OAuth·디버깅·토글 FAQ입니다. 서버가 목록 자체에 안 뜨면 별도 글(mcp-connection-fail)을 봅니다.
증상은?
한 줄 답: 서버는 보이는데 needsAuth이고, 로그에 OAuth·401·invalid_token 쪽 메시지가 남으면 인증 축입니다. 명령어 not found·경로 오타는 연결 축입니다.
연결 실패와 인증 실패를 가르는 신호:
| 신호 | 연결 실패(connection) | 인증 실패(needsAuth) |
|---|---|---|
| Customize 목록 | 서버가 안 보이거나 시작 직후 사라짐 | 서버는 보이지만 상태가 needsAuth / Authenticate |
| MCP Logs | command not found, spawn 실패, JSON 파싱 | OAuth, callback, 401, invalid_token, needsAuth |
| 채팅 도구 | 해당 서버 자체가 Available Tools에 없음 | 서버는 있으나 도구 0개·호출 거절 |
| 손볼 곳 | mcp.json 경로·command·PATH·env | OAuth 재인증·토글·Logout 후 Authenticate |
실무에서 자주 보이는 패턴:
- 마켓/플러그인으로 추가한 원격 서버(Linear, Atlassian, Figma 등)가 한동안 잘 쓰이다가 갑자기 needsAuth.
- 브라우저 OAuth 창은 열리지만 콜백 후 Cursor가 여전히 needsAuth.
- 한 워크스페이스에서는 연결되고, 다른 Cursor 창·프로필에서는 needsAuth만 반복.
- stdio 로컬 서버는 뜨는데,
url원격 서버만 OAuth에 걸림.
공식 문서 기준으로 원격(SSE / Streamable HTTP)은 OAuth를 쓸 수 있고, stdio는 주로 env로 키를 넘깁니다. needsAuth UI는 OAuth 세션이 없거나 만료·무효일 때 뜨는 쪽에 가깝습니다. mcp.json 오타로 서버가 목록에 안 뜨는 문제는 이 글의 대상이 아닙니다.
재연결 순서는?
한 줄 답: MCP Logs로 인증 메시지를 확인한 뒤, Authenticate → (실패 시) 토글 오프/온 → Logout 후 재인증 → Cursor 재시작 순으로 갑니다. mcp.json을 먼저 지우지 않습니다.
권장 순서(MCP FAQ의 로그·토글 안내와 맞춤):
- Output → MCP Logs를 엽니다. Mac은
Cmd+Shift+U, Windows/Linux는Ctrl+Shift+U. 드롭다운에서 MCP Logs를 고릅니다. - 로그에
needsAuth, OAuth callback,401,invalid_token이 있는지 확인합니다. 없으면 연결/경로 쪽을 먼저 의심합니다. - Customize → MCPs(또는 해당 플러그인 카드)에서 Authenticate / 로그인 버튼을 눌러 브라우저 OAuth를 끝까지 마칩니다.
- 콜백 후에도 needsAuth면 해당 서버 토글을 껐다가 다시 켭니다. 문서·포럼 모두 “stuck auth는 토글로 재트리거”를 안내합니다.
- 여전히면 카드의 Logout / Disconnect 후 다시 Authenticate합니다. 만료 세션·워크스페이스 스코프 꼬임을 끊는 단계입니다.
- 셸·프로필을 건드린 뒤에만 Cursor를 완전 종료 후 재실행합니다. 인증만 실패인데
mcp.json을 삭제하면 연결 축 문제를 새로 만듭니다.
원격 서버에 제공자가 고정 Client ID를 요구하면, 문서의 Static OAuth(auth.CLIENT_ID 등)와 리다이렉트 URL 등록이 필요할 수 있습니다.
- Desktop:
http://localhost:8787/callback - Web / Agents:
https://www.cursor.com/agents/mcp/oauth/callback
값을 본문에 붙이지 말고, 제공자 콘솔에 허용 리다이렉트로만 등록합니다. API 키·토큰 문자열은 글·채팅·스크린샷에 넣지 않습니다.
연결 실패 글과의 경계: 경로·PATH·env·제거 후 재추가는 connection 축입니다. needsAuth에서는 그 전에 Authenticate / 토글 / Logout을 끝냅니다.
도구 목록이 비면?
한 줄 답: 서버가 켜져 있어도 인증이 끝나기 전이면 Available Tools가 비거나 스키마를 못 받습니다. needsAuth를 먼저 풀고, 그다음 도구 allowlist·서버 자체 장애를 봅니다.
빈 도구 목록을 나누는 기준:
| 상태 | 의미 | 다음 행동 |
|---|---|---|
| 서버 = needsAuth, 도구 0 | 세션 없음·만료 | 위 재연결 순서 |
| 서버 = connected, 도구 0 | 핸드셰이크/스키마 실패 또는 정책 | MCP Logs + 엔터프라이즈 allowlist |
| 서버 = connected, 도구 있음, 호출만 실패 | 권한·원격 API 오류 | 로그의 인자·원격 응답 |
체크리스트:
- Customize에서 해당 서버가 enabled이고 needsAuth가 해제됐는지 확인합니다.
- 채팅의 Available Tools에 서버 접두 도구가 다시 붙는지 봅니다. 문서상 Cursor는 관련 있으면 이 목록의 MCP 도구를 자동으로 씁니다.
- 로그에 초기화는 성공인데 tools/list가 비면, 서버 프로세스·원격 엔드포인트 장애일 수 있습니다. 이때는 인증이 아니라 서버·네트워크 축입니다.
- 팀/엔터프라이즈면 Dashboard의 MCP Allowlist가 도구를 막을 수 있습니다. 허용 목록은 “설정이 보인다”와 “도구가 돈다”를 갈라 놓습니다.
- 다른 MCP는 정상인데 하나만 비면, 전역 Cursor 고장이 아니라 그 서버의 OAuth·플러그인만 의심합니다.
인증을 풀었는데도 도구가 계속 0이면, connection-fail 절차(토글 → 제거 → 재추가)로 넘어가도 됩니다. 다만 needsAuth가 남아 있는 동안 제거만 반복하면 OAuth를 다시 안 밟아 같은 증상이 납니다.
자주 묻는 질문
연결 실패 글이랑 뭐가 다르나요?
목록에 서버가 안 보이거나 spawn이 깨지면 connection입니다. 서버는 보이는데 needsAuth·빈 도구면 이 글(auth)입니다.
Authenticate를 눌렀는데 브라우저만 열고 끝나요?
콜백 URL·팝업 차단·다른 Cursor 프로필을 확인합니다. MCP Logs에 callback/code 수신이 있는지 봅니다. 토글 오프/온으로 흐름을 다시 겁니다.
토큰·요금을 어디에 넣나요?
넣지 않습니다. OAuth는 UI로 재연결하고, 키가 필요하면 env / headers에 이름만 두고 값은 로컬 비밀로 둡니다. 본문에 시크릿·가격을 적지 않습니다.
stdio 서버도 needsAuth가 뜨나요?
보통은 env 키 누락·잘못된 헤더로 원격 API가 거절되는 쪽에 가깝습니다. needsAuth UI는 OAuth 원격/플러그인에서 더 흔합니다.
무엇을 기억하면 되나?
needsAuth = 인증 축, 목록 부재·spawn 실패 = 연결 축입니다. 순서는 로그 → Authenticate → 토글 → Logout → (필요 시) 재시작입니다. 도구가 비면 먼저 needsAuth를 풀고, 그다음 allowlist·서버 로그를 봅니다.
공식 문서는 어디인가?
- Model Context Protocol (MCP) — OAuth, Static OAuth, 로그, 토글 FAQ
- 같은 문서의 How do I debug MCP server issues? — Output → MCP Logs
- 같은 문서의 Can I temporarily disable an MCP server? — Customize 토글