Claude Code MCP 서버 연결하기노션 등록부터 /mcp 확인까지

막히기 쉬운 네 군데

따라 하다 멈췄다면 어디서 멈췄을까요? 공식 문서가 흔한 연결 오류로 꼽는 곳을 추렸습니다.

/mcp에 No MCP servers configured가 뜹니다

증상. 분명 등록했는데 /mcp를 열면 No MCP servers configured만 나옵니다.

원인. 기본 범위(local)로 등록한 서버는 등록한 프로젝트에만 묶입니다. git 저장소(파일 변경 이력을 기록하는 폴더)라면 그 맨 위 폴더, 아니라면 명령을 친 바로 그 폴더입니다. 다른 폴더에서 열면 서버가 보이지 않습니다.

해결. 등록했던 폴더로 돌아가 Claude Code를 다시 엽니다. 어느 폴더에서나 쓰고 싶다면 범위를 user로 바꿔 등록하세요.

claude mcp add --scope user --transport http notion https://mcp.notion.com/mcp

브라우저가 안 열리거나 승인 뒤 연결 오류가 납니다

증상. Authenticate를 골랐는데 브라우저가 뜨지 않습니다. 또는 노션에서 승인까지 했는데 브라우저에 연결 오류 화면이 나옵니다.

원인. 승인을 마친 브라우저는 내 컴퓨터의 Claude Code(localhost 주소)로 결과를 돌려보냅니다. 이 돌아오는 길이 끊기면 오류가 납니다. 브라우저가 자동으로 안 열리는 원인은 문서에 나와 있지 않습니다.

해결. 브라우저가 안 열리면 터미널에 뜬 주소를 복사해 직접 엽니다. 승인 뒤 오류가 났다면 브라우저 주소창의 주소 전체를 복사해 Claude Code에 뜬 입력 칸에 붙여 넣으세요. 그래도 안 되면 /mcp에서 Authenticate를 다시 고릅니다.

already exists라며 등록이 거절됩니다

증상. 등록 명령을 다시 쳤더니 MCP server notion already exists in local config가 뜹니다.

원인. 같은 이름의 서버가 같은 범위에 이미 있습니다. 앞에서 한 번 등록했다면 다시 칠 필요가 없습니다.

해결. 주소를 잘못 넣어 고치려는 경우라면 claude mcp remove notion으로 먼저 지운 뒤 새로 등록합니다. 이름을 바꿔 하나 더 만드는 방법도 있습니다.

Failed to connect가 뜹니다

증상. claude mcp list에서 notion 옆에 ✘ Failed to connect나 ✘ Connection error가 보입니다. Windows 10 기본 콘솔처럼 오래된 창에서는 ✘ 대신 ×로 나옵니다.

원인. 서버가 응답하지 않았거나 주소가 맞지 않는다는 뜻입니다. 주소 경로가 틀려 404가 나면 /mcp에서 서버를 골랐을 때 MCP endpoint not found at으로 시작하는 문구가 보입니다.

해결. claude mcp get notion으로 저장된 주소와 오류 내용을 봅니다. 주소가 틀렸다면 지운 뒤 맞는 주소로 다시 등록합니다. 주소가 맞는데도 응답이 없으면 네트워크를 점검해 보세요.

여기서 한 걸음 더

같은 순서로 다른 서비스도 붙여 보세요. 팀이 함께 쓰려면 --scope project로 등록해 프로젝트 맨 위에 .mcp.json 파일을 만듭니다. 이 파일을 저장소에 올리면 동료가 처음 열 때 승인 창이 뜨고, 승인하면 같은 서버가 붙습니다.

서버마다 도구 이름이 매 대화의 컨텍스트 창을 조금씩 차지합니다. 안 쓰는 서버는 claude mcp remove notion으로 정리하세요. 노션 쪽에 남은 승인까지 끊으려면 지우기 전에 claude mcp logout notion을 먼저 실행합니다.

이상으로 글 마치겠습니다.

출처

• Claude Code 공식 문서: MCP 참고 문서
• Claude Code 공식 문서: Connect to MCP servers