
이 글은 claude mcp add 명령과 스코프 개념, Claude Desktop 쪽 설정, AFFiNE 워크스페이스를 예로 든 처음부터 끝까지의 연결 절차, 그리고 「안 붙을 때」 점검 목록까지 정리합니다. 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 <이름> '
설정이 어디에 기록되느냐가 곧 누구에게 보이느냐를 결정합니다.
원칙은 단순합니다. 서버 정의만 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 Code에서도 Claude Desktop에서도 동작하지만, 두 앱의 설정은 따로 관리됩니다. 쓰는 앱마다 한 번씩 설정해 두세요. 다만 Claude Desktop에 이미 등록한 로컬 서버가 많다면, claude mcp add-from-claude-desktop 명령(macOS·WSL 지원)으로 골라서 한 번에 가져올 수 있습니다.
AFFiNE의 내장 MCP 서버를 예로 든 전체 절차입니다. 워크스페이스의 문서와 화이트보드를 어떤 MCP 클라이언트에서든 검색할 수 있게 됩니다.
claude mcp add --transport http affine \
"https://app.affine.pro/api/workspaces/<워크스페이스 ID>/mcp" \
--header "Authorization: Bearer <토큰>"
추가 요금은 없습니다. AFFiNE Cloud에서도, AI 기능을 켠 셀프호스팅에서도 똑같이 동작합니다.
Cursor는 ~/.cursor/mcp.json(프로젝트 단위라면 .cursor/mcp.json)을 읽습니다. AFFiNE의 Copy JSON 출력은 Cursor 형식과 그대로 일치하므로, 붙여 넣고 재시작하면 끝입니다.
ChatGPT는 커넥터로 원격 MCP 서버에 연결하며, 커스텀 서버 추가에는 개발자 모드(설정 → 커넥터 → 고급)를 씁니다. 같은 엔드포인트와 헤더가 그대로 통합니다. 서버는 하나, 연결하는 어시스턴트는 몇 개든. 이것이 MCP의 장점입니다.
위에서부터 순서대로 확인하면 대부분 이 목록 안에서 해결됩니다.
claude mcp add입니다. 호스팅형이면 --transport http에 서버 URL과 인증 헤더를 더하고, 로컬형이면 실행 명령을 넘깁니다. 등록 확인은 claude mcp list, 세션 중 상태는 /mcp 명령으로 봅니다.
지원합니다. 원격 서버는 설정의 Connectors에서 커스텀 커넥터로 추가하고, 로컬 서버는 claude_desktop_config.json의 mcpServers에 적고 재시작합니다. Claude Code와 설정이 따로 관리된다는 점만 주의하세요.
가져올 수 있습니다. claude mcp add-from-claude-desktop 명령을 실행하면 Claude Desktop 설정 파일을 읽어 가져올 서버를 고르는 화면이 나옵니다. macOS와 WSL에서 동작하며, 가져온 뒤의 설정 변경은 두 앱에서 각각 관리됩니다.
local은 한 프로젝트에서 나 혼자, project는 저장소의 .mcp.json으로 팀 공유, user는 이 컴퓨터의 모든 프로젝트에서 나에게만 적용됩니다. 자격 증명은 개인 쪽에 두고, 서버 정의 공유만 project 스코프로 하는 것이 원칙입니다.
--scope project로 추가하면 저장소 루트의 .mcp.json에 기록되고, 이 파일을 커밋하면 팀 전체에 공유됩니다. 토큰은 파일에 넣지 말고 ${VAR} 환경 변수 확장으로 각자 채우게 하세요. 팀원 쪽에서는 처음 사용할 때 승인 프롬프트가 한 번 뜹니다.
됩니다. Streamable HTTP 원격 서버는 --transport http와 인증 헤더로 정식 지원되고, OAuth 로그인을 쓰는 서버는 URL만 등록한 뒤 /mcp에서 인증하면 됩니다. AFFiNE 워크스페이스 엔드포인트 같은 호스팅형은 로컬에 프로세스를 두지 않고 연결됩니다.
/mcp로 상태를 확인한 뒤 단골 원인을 순서대로 보세요. 원격인데 --transport http가 없거나, Authorization 헤더 형식이 틀렸거나, 자격 증명이 만료됐거나, 스코프가 다른 경우(local로 추가하면 다른 프로젝트에는 안 보입니다). 이 네 가지로 대부분 설명됩니다.
MCP 지원 자체는 Claude Code와 Claude Desktop에 추가 요금 없이 포함되어 있고, 프로토콜 자체도 오픈소스 표준입니다. 개별 서버의 이용 조건은 제각각이지만, 예를 들어 AFFiNE 내장 서버는 Cloud에서도 AI 기능을 켠 셀프호스팅에서도 무료로 쓸 수 있습니다.
하나 연결해 보면 두 번째부터는 손이 기억합니다. 기본 절차가 어느 서버든 똑같기 때문입니다. 첫 연결 대상은 평소 답을 찾아 헤매던 곳, 즉 내 워크스페이스가 가장 남는 장사입니다.