AI Coding Hub

레퍼런스

Claude Code에 MCP 서버 추가하기

원격 서버는 `claude mcp add --transport http <이름> <URL>`, 로컬 프로세스는 `claude mcp add <이름> -- <명령>`입니다. `--` 뒤의 내용은 그대로 서버에 전달됩니다. 실무에서 헷갈리는 건 명령 형식보다 범위입니다. `local`(기본, 본인만), `project`(저장소의 `.mcp.json`으로 공유), `user`(모든 프로젝트, 본인만) 셋이고, 팀 전원에게 같은 서버를 배포하려면 `--scope project` 외에 선택지가 없습니다.

한국어 · 최종 확인: 2026-09-05 · 영문 전체 버전: English

전송 방식별 형식

# HTTP(원격, 권장)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# HTTP + Bearer 토큰
claude mcp add --transport http <이름> <URL> \
  --header "Authorization: Bearer your-token"

# stdio(로컬 프로세스, -- 이후는 서버로 그대로 전달)
claude mcp add --env API_KEY=your-key --transport stdio myserver \
  -- python server.py --port 8080

# SSE(공식 문서에서 사용 중단 표시)
claude mcp add --transport sse asana https://mcp.asana.com/sse
공식 MCP 문서의 형식(2026-09-05 확인). 새로 추가한다면 HTTP를 고르세요.

범위: 이 서버는 누구에게 보이나

범위적용 대상공유 여부저장 위치
local(기본)현재 프로젝트만안 됨~/.claude.json
project현재 프로젝트만됨(.mcp.json 경유)프로젝트 루트의 .mcp.json
user본인의 모든 프로젝트안 됨~/.claude.json
 
# 팀 공유(저장소에 커밋됨)
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# 모든 프로젝트에서 나만 사용
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic
가장 흔한 착각

`local`과 `project`는 적용 범위가 똑같이 "현재 프로젝트만"입니다. 다른 것은 저장 위치입니다. `local`은 `~/.claude.json`(내 컴퓨터), `project`는 저장소 안의 `.mcp.json`입니다. "팀에 배포한 줄 알았는데 나만 쓰고 있었다"는 사고는 거의 이 지점에서 납니다.

.mcp.json의 모습

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}
project 범위로 추가하면 이 형태로 저장소에 들어갑니다. 리뷰 대상이 된다는 점이 이 범위의 가장 큰 가치입니다.

인증 네 가지

  • OAuth 2.0: 서버를 추가한 뒤 세션 안에서 `/mcp` 패널로 인증합니다. 명령줄에서는 `claude mcp login <이름>` / `claude mcp logout <이름>`.
  • 사전 설정한 OAuth 자격 증명: `--client-id`, `--client-secret`, `--callback-port`로 지정합니다. CI에서는 `MCP_CLIENT_SECRET` 환경 변수를 쓰는 형태가 제시되어 있습니다.
  • 정적 헤더: API 키나 토큰을 `--header "Authorization: Bearer ..."` 또는 `--header "X-API-Key: ..."`로 전달합니다.
  • 동적 헤더: `.mcp.json`의 `headersHelper`에 스크립트 경로를 적으면 그 스크립트가 반환한 값이 헤더가 됩니다. 사내 인증 기반에 붙일 때 쓰는 방식입니다.

관리 명령

claude mcp list          # 등록된 서버 목록
claude mcp get notion    # 개별 서버 상세
claude mcp remove notion # 삭제

# 세션 안에서
/mcp                     # 연결 상태 확인과 OAuth 인증

운영 조언 하나만 덧붙입니다. 처음부터 여러 서버를 붙이지 마세요. 에이전트가 쓸 수 있는 도구가 많아질수록 엉뚱한 도구를 고를 여지도 커집니다. 하나 붙이고 `/mcp`로 실제로 쓰이는지 확인한 뒤 다음으로 넘어가는 편이 결과적으로 더 빨리 안정됩니다.

자주 묻는 질문

claude mcp add의 범위는 무엇을 골라야 하나요?
팀 전원에게 같은 서버를 배포하려면 `--scope project`입니다. 이 범위만 저장소의 .mcp.json에 기록되어 버전 관리로 공유됩니다. 내 모든 프로젝트에서 쓰고 싶은 개인 서버는 `--scope user`, 이 프로젝트의 내 환경에서만 쓰려면 기본값 local입니다.
stdio에서 인자를 어떻게 전달하나요?
`claude mcp add <이름> -- <명령> [인자...]` 형태이며 `--` 뒤의 내용이 그대로 서버로 전달됩니다. 환경 변수는 `--env KEY=VALUE`를 `--` 앞에 둡니다. 예: claude mcp add --env API_KEY=your-key --transport stdio myserver -- python server.py --port 8080.
SSE는 아직 쓸 수 있나요?
쓸 수는 있지만 공식 문서가 SSE 전송을 사용 중단(deprecated)으로 명시하고 원격 서버에는 HTTP를 권장합니다. 기존 SSE 설정은 계속 동작하지만 새로 추가하는 서버는 --transport http를 쓰세요.
API 키는 어디에 두는 게 안전한가요?
정적 키는 `--header`로 헤더에 실어 보내는 것이 기본입니다. 다만 project 범위에서 .mcp.json에 평문으로 넣으면 저장소에 남습니다. 사내 인증 기반이 있다면 .mcp.json의 headersHelper에 스크립트를 지정해 실행 시점에 헤더를 생성하는 방식이 권장됩니다.

출처

이어서 읽기