MCP

서버 추가하기

원격 서버는 HTTP 방식을 권장합니다. SSE 방식은 더 이상 권장되지 않으며 HTTP를 쓸 수 있으면 HTTP를 쓰라고 문서가 안내합니다. 내 컴퓨터에서 도는 서버는 stdio 방식이고, 서버 명령은 -- 뒤에 적습니다.

# 원격 HTTP 서버
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 로컬 stdio 서버: --transport, --env, --scope 같은 옵션은 -- 앞에
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

관리 명령

세션 안에서는 /mcp로 상태 확인, 인증, 재연결, 서버 끄기를 할 수 있습니다. 끄는 것은 설정을 지우지 않습니다.

claude mcp list           # 서버 목록과 상태
claude mcp get notion     # 한 서버의 상세
claude mcp remove notion  # 제거
claude mcp login sentry   # 셸에서 OAuth 로그인
claude mcp logout sentry  # 저장된 인증 삭제

범위와 .mcp.json

• local(기본): 현재 프로젝트에서만, 나만. ~/.claude.json에 저장됩니다.
• project: 프로젝트 루트의 .mcp.json에 저장되어 버전 관리로 팀과 공유됩니다.
• user: 내 모든 프로젝트에서. ~/.claude.json에 저장됩니다.
• 같은 이름이 여러 곳에 있으면 local, project, user 순으로 이기고 항목 전체가 쓰입니다(필드는 합쳐지지 않음).

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

인증과 보안

• 원격 서버가 401이나 403을 주면 인증이 필요한 서버로 표시됩니다. /mcp에서 서버를 고르고 브라우저 절차를 완료합니다.
• .mcp.json의 프로젝트 서버는 대화형 세션에서 승인을 묻습니다. 복제한 저장소가 스스로 승인할 수는 없습니다.
• 외부 콘텐츠를 가져오는 서버는 프롬프트 인젝션에 노출될 수 있습니다. 공식 문서도 연결 전에 서버를 확인하라고 경고합니다.
• 서버를 remove해도 토큰은 인증 서버에서 취소되지 않습니다. 먼저 claude mcp logout을 실행하세요.
• 비대화형 실행(-p)에서는 OAuth 절차를 보여줄 수 없으니 대화형 세션에서 먼저 로그인하세요.

플러그인, 스킬, 훅과의 차이

MCP는 Claude에게 새 도구와 데이터 접근을 줍니다. 스킬은 도구 사용법을 담은 지시문이고, 훅은 이벤트마다 자동으로 실행되는 명령입니다. 플러그인은 이들을 묶어 설치하는 단위라서 MCP 서버가 플러그인 안에 들어 있을 수도 있습니다.

실제 예시

claude mcp add --transport http --scope user notion https://mcp.notion.com/mcp
(세션에서) /mcp

claude mcp add --transport http --scope project shared-server https://example.com/mcp

흔한 실수와 쓰지 말아야 할 때

• stdio 서버를 추가할 때 -- 를 빼면 서버의 옵션(--port 등)을 Claude Code가 자기 옵션으로 읽습니다.
• url만 있고 type이 없는 JSON 항목은 stdio로 취급되어 오류와 함께 건너뜁니다. type을 "http"로 적으세요.
• 검증하지 않은 서버를 연결하지 마세요. 서버가 가져온 외부 글이 Claude에게 지시처럼 읽힐 수 있습니다.
• 붙여 넣은 토큰 끝에 줄바꿈이 섞이면 경고가 뜨지만 자동으로 잘라주지 않습니다. 설정을 직접 고쳐야 합니다.
• 서버가 많으면 도구 정의가 컨텍스트를 차지합니다. 쓰지 않는 서버는 /mcp에서 끄세요.

자주 묻는 질문