📌 답변 먼저 보기
Cursor MCP 연결 실패 시 가장 먼저 Output 패널의 MCP Logs(Mac: Cmd+Shift+U, Windows/Linux: Ctrl+Shift+U)를 확인합니다. 그다음 mcp.json 경로와 환경변수를 점검하고, 여전히 안 되면 Customize > MCPs에서 서버를 제거 후 다시 추가합니다.
이 글은 mcp.json을 이미 작성한 상태에서 서버가 목록에 뜨지 않거나 연결에 실패할 때의 진단·복구 절차만 다룹니다. 처음부터 서버를 추가하는 기본 설정 튜토리얼은 다루지 않습니다.
서버 목록에 안 뜨면 어디를 보나?
한 줄 답: mcp.json 파일 위치를 다시 확인하고, Output 패널의 MCP Logs에서 에러 메시지를 읽습니다.
Cursor는 프로젝트 단위(.cursor/mcp.json)와 글로벌 단위(~/.cursor/mcp.json) 두 곳에서 설정 파일을 읽습니다. 파일명이나 경로에 오타가 있으면 서버 자체가 목록에 나타나지 않습니다. 경로가 맞는데도 보이지 않는다면 백그라운드에서 발생한 에러를 로그로 확인해야 합니다.
확인 방법은 다음과 같습니다.
- Mac은
Cmd+Shift+U, Windows/Linux는Ctrl+Shift+U를 눌러 Output 패널을 엽니다. - 패널 우측 상단 드롭다운에서 MCP Logs를 선택합니다.
- 서버가 시작될 때 출력된 에러 메시지(명령어를 찾을 수 없음, 인증 실패 등)를 확인합니다.
이 로그에 원인이 대부분 남아 있으므로, 목록에 서버가 안 보이는 문제는 항상 이 단계에서 시작합니다.
권한·경로·환경변수는 어떻게 점검하나?
한 줄 답: 실행 명령어가 시스템 PATH에 있는지, 셸 환경변수가 Cursor에 전달됐는지, 원격 서버라면 인증 헤더가 맞는지 확인합니다.
로그에서 원인을 찾았다면 아래 세 가지 항목을 순서대로 점검합니다.
- 명령어 경로: 로컬 서버라면
mcp.json의command값(예:npx,python)이 실제로 시스템PATH에 등록되어 있는지 터미널에서 직접 실행해 확인합니다. - 환경변수: 서버가
.zshrc,.bashrc같은 셸 프로필의 환경변수에 의존한다면, 셸 프로필을 수정한 뒤 반드시 셸을 재시작(터미널을 새로 열거나 로그아웃 후 재로그인)한 다음 Cursor도 재시작해야 변수가 반영됩니다. - 인증 헤더: 원격(URL) 방식 서버는
mcp.json의headers항목에 넣은 API 키(Authorization: Bearer ...등)가 누락되거나 만료되지 않았는지 확인합니다.
재시작·캐시 초기화 순서는?
한 줄 답: 단순 재시작만으로 해결되지 않으면 Customize > MCPs에서 토글을 껐다 켜고, 안 되면 서버를 제거 후 다시 추가합니다.
설정을 고쳐도 기존 백그라운드 프로세스나 캐시 때문에 바로 반영되지 않는 경우가 있습니다. 다음 순서대로 진행합니다.
권장 순서
- 사이드바에서 Customize를 열고 MCPs 섹션으로 이동합니다.
- 문제가 있는 서버의 토글 스위치를 껐다가 다시 켭니다(enable/disable).
- 토글만으로 해결되지 않으면 해당 서버를 목록에서 제거(Remove)합니다.
- 셸 프로필이나 환경변수를 수정했다면, Cursor를 완전히 종료한 뒤 다시 실행합니다.
- 다시 Customize > MCPs에서 Add to Cursor로 서버를 재추가합니다.
이 순서(토글 → 제거 → Cursor 재시작 → 재추가)를 지키면 캐시나 잔여 프로세스로 인한 연결 실패를 대부분 해소할 수 있습니다.
마무리
정리하면 순서는 ① MCP Logs 확인 → ② 경로·환경변수·인증 점검 → ③ 토글/제거/재시작입니다. 서버 추가 자체가 처음이라면 기본 설정 방법은 별도의 mcp.json 작성 가이드를 참고하시고, 이 글은 연결이 이미 실패한 상태를 되돌리는 데에만 활용하시기 바랍니다.
📌 Short answer first
When a Cursor MCP connection fails, first check MCP Logs in the Output panel (Cmd+Shift+U on Mac, Ctrl+Shift+U on Windows/Linux). Then verify the mcp.json path and environment variables, and if it's still broken, remove and re-add the server under Customize > MCPs.
This guide assumes you already wrote an mcp.json file and covers only what to do when a server does not appear in the list or fails to connect. It does not repeat the basic setup tutorial for adding a server from scratch.
Where do you look when a server does not appear in the list?
One-line answer: Re-check the mcp.json file location, then read the error in the Output panel's MCP Logs.
Cursor reads configuration from two possible locations: project-level (.cursor/mcp.json) and global (~/.cursor/mcp.json). A typo in the filename or path will simply keep the server out of the list. If the path is correct but the server still doesn't show up, a background error is almost always the cause, and the logs are where you find it.
- Open the Output panel with
Cmd+Shift+U(Mac) orCtrl+Shift+U(Windows/Linux). - Select MCP Logs from the dropdown in the top-right corner.
- Read the error message emitted when the server tried to start (command not found, authentication failure, etc.).
Most root causes show up here, so start troubleshooting from this step every time.
How do you check permissions, paths, and environment variables?
One-line answer: Confirm the command is on your system PATH, that shell environment variables are actually loaded into Cursor, and that auth headers are correct for remote servers.
- Command path: for local servers, verify the
commandvalue inmcp.json(e.g.npx,python) actually runs from a terminal, meaning it exists on your systemPATH. - Environment variables: if the server relies on variables defined in a shell profile (
.zshrc,.bashrc), you must restart the shell (open a new terminal or log out and back in) after editing the profile, then restart Cursor as well before the variable is picked up. - Auth headers: for remote (URL-based) servers, check that the API key in the
headersfield (e.g.Authorization: Bearer ...) is present and not expired.
What is the correct restart / cache-reset sequence?
One-line answer: If a plain restart doesn't fix it, toggle the server off and on under Customize > MCPs, and if that fails, remove and re-add it.
Cached state or a leftover background process can prevent a config change from taking effect immediately. Follow this order:
- Open Customize from the sidebar and go to the MCPs section.
- Toggle the problematic server off and back on (enable/disable).
- If toggling doesn't help, remove the server from the list.
- If you changed a shell profile or environment variables, fully quit and relaunch Cursor.
- Go back to Customize > MCPs and click Add to Cursor to re-add the server.
Following this sequence — toggle, remove, restart Cursor, re-add — resolves most connection failures caused by stale cache or lingering processes.
Wrap-up
In short: ① check MCP Logs → ② verify path/env vars/auth → ③ toggle/remove/restart. If you're setting up a server for the first time, refer to a dedicated mcp.json setup guide; use this article specifically to recover from an already-failed connection.
'AI 에이전트 관련' 카테고리의 다른 글
| Claude Opus 5.5란 무엇인가 — 에이전트 코딩에서 Opus 5와 뭐가 다른가 (0) | 2026.09.26 |
|---|---|
| ChatGPT 검색만 하던 사람, 에이전트 지시로 바꾸려면 (0) | 2026.09.24 |
| Orca CLI로 worktree·에이전트 병렬 돌리기 (0) | 2026.09.23 |
| 에이전트를 실무에 어떻게 쓸까, 개요 (0) | 2026.09.23 |
| Orca CLI란? 설치하고 첫 명령까지 (0) | 2026.09.22 |