전체 글
AFFiNE
Toeverything·게시일 2026년 8월 20일 · 업데이트 2026년 8월 21일
터미널 화면에서 MCP 포트를 거쳐 AI 어시스턴트로 이어지는 그림

Claude Code에 MCP 서버 추가하는 법: 설정과 문제 해결

핵심 요약

  • Claude Code는 MCP를 기본 지원합니다. 원격 서버라면 claude mcp add 명령 한 줄, 몇 분이면 연결됩니다.
  • 설정 저장 위치는 local·project·user 세 가지 스코프 중에서 선택합니다. 팀 공유는 project, 자격 증명은 개인 스코프가 원칙입니다.
  • Claude Desktop은 「Connectors(원격)」와 「설정 파일(로컬)」 두 경로를 씁니다. Claude Code와는 설정이 분리되어 있습니다.
  • 서버가 보이지 않으면 세션 안에서 /mcp 명령으로 상태부터 확인하는 것이 가장 빠릅니다.

이 글은 claude mcp add 명령과 스코프 개념, Claude Desktop 쪽 설정, AFFiNE 워크스페이스를 예로 든 처음부터 끝까지의 연결 절차, 그리고 「안 붙을 때」 점검 목록까지 정리합니다. MCP 서버가 무엇인지부터 보고 오면 이해가 더 빠릅니다.

Claude Code에 MCP 서버 추가하기

먼저 원격(HTTP) 서버입니다. 호스팅형 서비스에 연결하는 가장 일반적인 형태입니다.

claude mcp add --transport http <이름> <서버 URL> \
  --header "Authorization: Bearer <토큰>"

토큰 헤더 대신 OAuth 로그인을 쓰는 서버(Notion, Sentry 등)라면 헤더 없이 URL만 등록한 뒤, 세션에서 /mcp를 열어 브라우저 로그인으로 인증합니다. 참고로 예전 자료에 자주 보이는 SSE 전송은 지원 중단(deprecated) 상태이므로, 신규 연결은 HTTP가 표준입니다.

다음은 로컬(stdio) 서버입니다. Claude Code가 내 컴퓨터에서 프로그램을 직접 실행하는 방식입니다.

claude mcp add <이름> -- <서버 실행 명령>

관리는 하위 명령 세 개면 충분합니다. claude mcp list로 목록, claude mcp get <이름>으로 상세, claude mcp remove <이름>으로 삭제합니다. 제품이 JSON 설정을 통째로 주는 경우에는 claude mcp add-json <이름> ''이 그대로 받아 줍니다. 세션 중에는 /mcp 명령이 연결 상태와 사용 가능한 도구를 보여 줍니다. 뭔가 이상할 때 가장 먼저 볼 곳입니다.

스코프: local·project·user

설정이 어디에 기록되느냐가 곧 누구에게 보이느냐를 결정합니다.

  • local(기본값): 이 프로젝트, 이 컴퓨터, 나 혼자. 실험과 개인 자격 증명용입니다.
  • project: 저장소 루트의 .mcp.json에 기록되어 버전 관리로 팀 전체에 공유됩니다. 지식 베이스처럼 팀 표준으로 삼을 서버용이고, 팀원에게는 처음 사용할 때 승인 프롬프트가 뜹니다.
  • user(--scope user): 이 컴퓨터의 모든 프로젝트에서 나에게만 적용됩니다. 어디서나 쓰는 개인 서버용입니다.

원칙은 단순합니다. 서버 정의만 project 스코프로 공유하고, 토큰은 각자 채웁니다. .mcp.json이 ${VAR} 형태의 환경 변수 확장을 지원하므로, 파일에는 자리만 남기고 실제 값은 각자의 셸 환경 변수에 두면 됩니다.

{
  "mcpServers": {
    "affine": {
      "type": "http",
      "url": "https://app.affine.pro/api/workspaces/<워크스페이스 ID>/mcp",
      "headers": { "Authorization": "Bearer ${AFFINE_MCP_TOKEN}" }
    }
  }
}

이 파일을 커밋해 두면, 저장소를 받은 팀원은 AFFINE_MCP_TOKEN 환경 변수만 설정하고 바로 연결할 수 있습니다.

Claude Desktop에 추가하기

  • 원격 서버: 「설정 → Connectors → 커스텀 커넥터 추가」에서 URL을 붙여 넣고 인증하면 끝입니다. 터미널이 필요 없는 경로로, AFFiNE이나 Notion 같은 호스팅형 서버는 이쪽이면 충분합니다.
  • 로컬 서버: claude_desktop_config.json(설정 → 개발자 → 설정 편집)의 mcpServers 항목에 추가하고 앱을 재시작합니다.

같은 서버가 Claude Code에서도 Claude Desktop에서도 동작하지만, 두 앱의 설정은 따로 관리됩니다. 쓰는 앱마다 한 번씩 설정해 두세요. 다만 Claude Desktop에 이미 등록한 로컬 서버가 많다면, claude mcp add-from-claude-desktop 명령(macOS·WSL 지원)으로 골라서 한 번에 가져올 수 있습니다.

처음부터 끝까지: 내 지식 베이스 연결하기

AFFiNE의 내장 MCP 서버를 예로 든 전체 절차입니다. 워크스페이스의 문서와 화이트보드를 어떤 MCP 클라이언트에서든 검색할 수 있게 됩니다.

  1. 자격 증명 만들기: AFFiNE에서 「설정 → Integrations → MCP Server → Create credential」. 라벨은 「Claude Code」처럼 클라이언트 이름으로 적습니다(클라이언트당 하나면 폐기가 편합니다). 접근 권한은 기본값인 읽기 전용 그대로 두고 유효 기간을 설정합니다.
  2. 설정 복사: 토큰은 한 번만 표시되며, Copy JSON 버튼이 엔드포인트 URL과 인증 헤더를 포함한 완전한 설정을 만들어 줍니다. 엔드포인트는 https://app.affine.pro/api/workspaces/<워크스페이스 ID>/mcp 형태이고, 셀프호스팅이라면 내 서버 주소가 들어갑니다.
  3. 추가하기:
claude mcp add --transport http affine \
  "https://app.affine.pro/api/workspaces/<워크스페이스 ID>/mcp" \
  --header "Authorization: Bearer <토큰>"
  1. 사용하기: 세션을 열고 내 노트에만 답이 있는 질문을 던집니다. 「결제 재시도 설계 메모 찾아서 미해결 쟁점 정리해줘」. Claude Code가 검색 도구를 호출하고(키워드+의미 검색, 화이트보드 포함), 권한 범위 안에서 해당 문서 본문을 읽어 실제 내용에 근거해 답합니다.

추가 요금은 없습니다. AFFiNE Cloud에서도, AI 기능을 켠 셀프호스팅에서도 똑같이 동작합니다.

로컬 또는 원격 전송을 선택한 뒤 권한이 제한된 자격 증명으로 MCP 서버에 연결하는 흐름
전송 방식은 서버의 실행 위치를 정하고, 자격 증명에 부여된 권한은 클라이언트가 접근할 수 있는 도구와 데이터를 정합니다.

같은 설정을 Cursor와 ChatGPT에도

Cursor는 ~/.cursor/mcp.json(프로젝트 단위라면 .cursor/mcp.json)을 읽습니다. AFFiNE의 Copy JSON 출력은 Cursor 형식과 그대로 일치하므로, 붙여 넣고 재시작하면 끝입니다.

ChatGPT는 커넥터로 원격 MCP 서버에 연결하며, 커스텀 서버 추가에는 개발자 모드(설정 → 커넥터 → 고급)를 씁니다. 같은 엔드포인트와 헤더가 그대로 통합니다. 서버는 하나, 연결하는 어시스턴트는 몇 개든. 이것이 MCP의 장점입니다.

문제 해결: 서버가 안 보일 때

위에서부터 순서대로 확인하면 대부분 이 목록 안에서 해결됩니다.

  • 먼저 /mcp: 연결됐는지, 인증에서 떨어졌는지, 아예 시작을 못 했는지가 여기서 드러납니다. 감으로 찍기 전에 표시된 오류를 읽는 편이 결국 가장 빠릅니다.
  • 전송 방식 착오: 호스팅형 서버에는 --transport http가 필수입니다. 빠뜨리면 URL을 로컬 명령으로 취급하려 듭니다. 삭제하고 다시 추가하세요.
  • 헤더 표기: Authorization: Bearer <토큰> 형식입니다. Bearer 누락이나 공백 하나로도 아무 말 없이 401만 돌아옵니다. 손으로 치지 말고 Copy JSON에서 붙여 넣는 것이 확실합니다.
  • 자격 증명 만료·폐기: 유효 기간이 있는 토큰은 언젠가 만료됩니다. 새 자격 증명을 발급해 다시 등록하세요.
  • 스코프 착오: local 스코프로 추가한 서버는 다른 프로젝트에는 존재하지 않습니다. 기대하는 프로젝트 폴더에서 claude mcp list를 실행해 보면 바로 드러납니다.
  • 로컬 서버 의존성 부족: stdio 서버는 명령을 실행합니다. 런타임이 없으면 그 자리에서 죽습니다. 먼저 그 명령만 터미널에서 실행해 원래 오류를 확인하세요. npx 기반 서버라면 Node.js 설치 여부와 버전부터 봅니다.
  • 연결은 되는데 안 쓰일 때: 처음 몇 번은 「AFFiNE 워크스페이스에서 ~ 찾아줘」처럼 출처를 명시하세요. 패턴이 자리 잡으면 이후에는 말하지 않아도 알맞은 도구를 고릅니다.

지켜야 할 보안 기본값

  • 필요해질 때까지 읽기 전용: 지식 베이스 연결에 쓰기가 필요한 경우는 드뭅니다. AFFiNE 자격 증명은 기본이 읽기 전용이고, 쓰기는 단계적 제공 중입니다.
  • 클라이언트당 자격 증명 하나: 노트북 것만 폐기해도 데스크톱이 무사하도록. 유효 기간까지 걸어 두면 교체는 정기 작업이 됩니다.
  • 도구 승인은 건너뛰지 않기: Claude는 새 도구를 처음 쓰기 전에 확인을 요청하고, project 스코프의 공유 서버도 첫 사용 때 승인제입니다. 데이터를 바꿀 수 있는 도구에서 이 확인을 끄지 마세요. 전체 점검 목록은 MCP 보안 가이드(영문)에 있습니다.

자주 묻는 질문

Claude Code에 MCP 서버를 추가하는 명령은 무엇인가요?

claude mcp add입니다. 호스팅형이면 --transport http에 서버 URL과 인증 헤더를 더하고, 로컬형이면 실행 명령을 넘깁니다. 등록 확인은 claude mcp list, 세션 중 상태는 /mcp 명령으로 봅니다.

Claude Desktop도 MCP를 지원하나요?

지원합니다. 원격 서버는 설정의 Connectors에서 커스텀 커넥터로 추가하고, 로컬 서버는 claude_desktop_config.json의 mcpServers에 적고 재시작합니다. Claude Code와 설정이 따로 관리된다는 점만 주의하세요.

Claude Desktop에서 쓰던 MCP 서버를 Claude Code로 가져올 수 있나요?

가져올 수 있습니다. claude mcp add-from-claude-desktop 명령을 실행하면 Claude Desktop 설정 파일을 읽어 가져올 서버를 고르는 화면이 나옵니다. macOS와 WSL에서 동작하며, 가져온 뒤의 설정 변경은 두 앱에서 각각 관리됩니다.

local·project·user 스코프는 무엇이 다른가요?

local은 한 프로젝트에서 나 혼자, project는 저장소의 .mcp.json으로 팀 공유, user는 이 컴퓨터의 모든 프로젝트에서 나에게만 적용됩니다. 자격 증명은 개인 쪽에 두고, 서버 정의 공유만 project 스코프로 하는 것이 원칙입니다.

팀원과 같은 MCP 서버 설정을 공유하려면 어떻게 하나요?

--scope project로 추가하면 저장소 루트의 .mcp.json에 기록되고, 이 파일을 커밋하면 팀 전체에 공유됩니다. 토큰은 파일에 넣지 말고 ${VAR} 환경 변수 확장으로 각자 채우게 하세요. 팀원 쪽에서는 처음 사용할 때 승인 프롬프트가 한 번 뜹니다.

Claude Code는 원격 MCP 서버에 연결되나요?

됩니다. Streamable HTTP 원격 서버는 --transport http와 인증 헤더로 정식 지원되고, OAuth 로그인을 쓰는 서버는 URL만 등록한 뒤 /mcp에서 인증하면 됩니다. AFFiNE 워크스페이스 엔드포인트 같은 호스팅형은 로컬에 프로세스를 두지 않고 연결됩니다.

서버가 목록에 안 나오는 이유는 무엇인가요?

/mcp로 상태를 확인한 뒤 단골 원인을 순서대로 보세요. 원격인데 --transport http가 없거나, Authorization 헤더 형식이 틀렸거나, 자격 증명이 만료됐거나, 스코프가 다른 경우(local로 추가하면 다른 프로젝트에는 안 보입니다). 이 네 가지로 대부분 설명됩니다.

Claude에서 MCP를 쓰는 데 비용이 드나요?

MCP 지원 자체는 Claude Code와 Claude Desktop에 추가 요금 없이 포함되어 있고, 프로토콜 자체도 오픈소스 표준입니다. 개별 서버의 이용 조건은 제각각이지만, 예를 들어 AFFiNE 내장 서버는 Cloud에서도 AI 기능을 켠 셀프호스팅에서도 무료로 쓸 수 있습니다.

마무리

하나 연결해 보면 두 번째부터는 손이 기억합니다. 기본 절차가 어느 서버든 똑같기 때문입니다. 첫 연결 대상은 평소 답을 찾아 헤매던 곳, 즉 내 워크스페이스가 가장 남는 장사입니다.