MCP 커넥터 — AI 한 입

Claude Code 실무 가이드에서 MCP의 개념과 claude mcp add의 기본 두 형태를 봤다면, 이 문서는 그다음입니다 — 실제 외부·사내 MCP 서버를 붙이고, 인증하고, 팀과 공유하고, 연결이 깨졌을 때 진단하는 단계를 다룹니다. MCP가 무엇인지, 상태 표시(✓·!·✗·⏸)가 무엇인지는 Claude Code 실무에서 다루므로 여기서는 다시 정의하지 않습니다.

서버 추가 — transport와 서브커맨드

실무 가이드에서 본 claude mcp add는 시작점입니다. claude mcp 아래에는 서버를 다루는 서브커맨드가 모여 있습니다.

서브커맨드	하는 일
`claude mcp add`	서버 추가
`claude mcp list`	등록된 서버 전체와 연결 상태
`claude mcp get <name>`	한 서버의 상세 — 스코프·URL/command·상태
`claude mcp remove <name>`	서버 제거(여러 스코프에 있으면 `--scope`로 지정)
`claude mcp add-json <name> '<json>'`	JSON 설정을 직접 추가
`claude mcp reset-project-choices`	프로젝트 서버 승인 상태 초기화(재승인 프롬프트)

서버를 어떻게 붙이느냐는 전송 방식(transport)이 가릅니다. 네 가지가 있고, 권장은 HTTP입니다.

MCP Transport 선택 흐름도 — HTTP(권장, 클라우드·OAuth)·stdio(로컬 프로세스)·SSE(폐기)·WebSocket(.mcp.json ws) 중 연결 대상에 맞는 전송 방식 고르기.

transport	추가 방법	비고
HTTP (권장)	`claude mcp add --transport http <name> <url>`	클라우드 표준, OAuth 지원
stdio (기본)	`claude mcp add <name> -- <command> <args>`	로컬 프로세스, 기본 스코프 local
SSE	`--transport sse`	폐기 — HTTP를 쓸 수 있으면 HTTP를 쓰세요
WebSocket	`.mcp.json`의 `"type": "ws"`	CLI `--transport` 미지원

HTTP는 클라우드·SaaS 서버를 붙일 때, stdio는 로컬에서 도는 프로세스(브라우저 자동화, 로컬 DB, 파일시스템 접근 등)를 붙일 때 씁니다. stdio 형태에서 -- 뒤는 모두 서버를 띄우는 실행 명령으로 넘어갑니다 — --를 빼면 CLI가 서버 쪽 플래그를 자기 옵션으로 해석하므로 반드시 넣어야 합니다.

claude mcp add playwright -- npx -y @playwright/mcp@latest

이렇게 stdio로 추가하면 기본 스코프가 local이라 현재 프로젝트에서 본인만 쓰게 됩니다. 인증이 없는 공개 서버로 연결 자체를 먼저 확인한 뒤, 인증이 필요한 사내 서버로 넘어가면 진단 범위가 좁아집니다.

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

claude mcp list
claude mcp get claude-code-docs

인증 — OAuth와 토큰

붙인 서버가 인증을 요구하면 claude mcp list에 ! Needs authentication으로 뜹니다. 인증은 크게 두 갈래입니다 — 브라우저로 로그인하는 OAuth, 그리고 헤더에 토큰을 싣는 방식입니다.

OAuth(브라우저 로그인)

OAuth 서버는 추가한 뒤 세션 안에서 인증합니다. 예로 Sentry의 원격 MCP 서버를 붙여 보겠습니다.

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

claude mcp list 출력 — 등록된 MCP 서버의 연결 상태를 보여줌. 인증이 끝난 서버는 '✔ Connected', 아직 로그인하지 않은 서버(Google Drive·Gmail)는 '! Needs authentication'으로 표시되며 세션에서 /mcp로 인증함.

추가 직후 claude mcp list를 보면 ! Needs authentication 상태입니다. 세션에서 /mcp를 열어 해당 서버의 Authenticate를 고르면 브라우저가 열리고, 로그인을 마치면 ✓ Connected로 바뀝니다. 서버가 401/403을 주면 Claude Code가 이를 자동 감지해 기본적으로 Dynamic Client Registration으로 클라이언트를 등록한 뒤 브라우저 리다이렉트 로그인으로 넘어갑니다. DCR을 지원하지 않는 서버는 --client-id와 --client-secret을 함께 넘겨야 합니다.

토큰·헤더

PAT 같은 정적 토큰을 쓰는 서버는 --header로 인증 헤더를 실어 추가합니다. 예로 GitHub의 원격 MCP 서버입니다.

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer <PAT>"

같은 헤더를 .mcp.json의 headers에 둘 수도 있습니다(아래 스코프 절). 이때 토큰은 환경변수 확장으로 빼냅니다. 헤더를 요청마다 동적으로 만들거나 OAuth 메타데이터를 덮어쓰는 고급 설정도 있지만, 일반적인 연동에는 정적 헤더로 충분합니다.

토큰 저장과 철회

인증 토큰은 OS 자격증명 저장소가 보호합니다 — macOS Keychain, Windows 자격증명 관리자, Linux는 파일 권한입니다. 갱신은 자동이라 매번 다시 로그인할 필요가 없습니다. 인증을 끊으려면 /mcp에서 해당 서버의 Clear authentication을 고릅니다.

스코프 전략과 팀 공유

모든 서버 설정은 스코프를 가집니다. 어디에 저장되고 이름이 겹칠 때 누가 이기는지를 짚겠습니다.

스코프	저장 위치	범위
`--scope local` (기본)	`~/.claude.json` (프로젝트 항목)	현재 프로젝트, 본인만
`--scope project`	`.mcp.json` (저장소 루트)	팀 공유, VCS 커밋
`--scope user`	`~/.claude.json` (전역 `mcpServers` 항목)	모든 프로젝트, 본인만

MCP 스코프 계층 구조도 — local(본인·현재 프로젝트)이 project(.mcp.json 팀 공유)를, project가 user(전역·본인)를 덮는 우선순위로 좁은 범위가 넓은 범위를 이김.

같은 이름의 서버가 여러 스코프에 있으면 우선순위는 local > project > user입니다 — 좁은 범위가 넓은 범위를 덮습니다. 팀 공통 서버가 보이지 않을 때는 같은 이름의 local 서버가 있는지 먼저 확인하세요.

팀이 함께 쓸 서버는 --scope project로 추가합니다. 저장소 루트의 .mcp.json에 기록되고, 이 파일을 커밋하면 같은 저장소를 받은 동료가 같은 구성을 공유합니다. 구조는 최상위 mcpServers 키 아래 서버별 설정입니다.

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT}"
      }
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

각 서버는 type과 함께 url 또는 command/args를, 필요하면 env·headers를 가집니다. ${GITHUB_PAT}가 환경변수 확장입니다 — .mcp.json에서는 ${VAR}와 ${VAR:-default} 문법을 command·args·env·url·headers 자리에서 쓸 수 있습니다. 덕분에 실제 토큰은 각자 환경에 남고, 커밋되는 파일에는 변수 이름만 들어갑니다.

토큰·키를 .mcp.json에 평문으로 커밋하지 마세요 — 환경변수 확장으로 빼거나 OAuth를 쓰면 시크릿이 저장소에 남지 않습니다. 무엇을 입력해도 되고 무엇은 안 되는지(시크릿 빨간선)는 안전·시크릿 입력이 정본입니다.

동료가 이 .mcp.json을 처음 받으면 서버가 곧장 로드되지 않고 신뢰를 묻는 프롬프트를 거칩니다. 그 동작은 아래 보안 절에서 다룹니다.

트러블슈팅

연결이 안 되면 claude mcp list의 상태부터 봅니다. 상태별로 원인과 조치가 갈립니다.

증상	진단·조치
`✗ Failed to connect` · `✗ Connection error`	HTTP면 `curl -I <url>`로 도달성 확인(`401`/`403`=인증 필요, 무응답=URL·네트워크 문제). stdio면 서버 실행 커맨드를 터미널에서 직접 실행해 에러를 확인
`! Needs authentication`	세션에서 `/mcp` → Authenticate
도구가 안 보임	필수 환경변수 누락 — `--env KEY=value`로 넘기거나 `.mcp.json`의 `env`에 추가
`.mcp.json` 변경이 반영 안 됨	Claude Code는 세션 시작 시에만 읽음 — 세션을 재시작. 이전에 거부한 프로젝트 서버면 `claude mcp reset-project-choices`로 승인 상태 초기화
연결 타임아웃	`MCP_TIMEOUT` 환경변수로 조정(기본값은 버전에 따라 다름)

HTTP 서버의 도달성은 curl로 먼저 끊어 봅니다.

curl -I https://mcp.sentry.dev/mcp

보안·조직 통제

MCP 서버는 Claude의 도구입니다 — 즉 작업 중의 프롬프트와 컨텍스트가 그 서버로 전달됩니다. 이 점이 보안 판단의 출발점입니다.

리모트(HTTP/SSE) 서버는 그 요청을 서버 운영자가 접근할 수 있습니다. 그래서 민감한 내용이 섞인 작업은 신뢰할 수 있는 서버에만 연결합니다. 반면 stdio 로컬 서버는 로컬 프로세스라 외부로 나가는 egress가 없습니다. 또한 외부 콘텐츠를 가져오는 서버는 그 콘텐츠에 숨은 지시가 섞이는 prompt injection 위험이 있으니, 역시 신뢰하는 서버만 붙입니다.

프로젝트 스코프 서버를 처음 만나면 ⏸ Pending approval로 뜨며 신뢰를 묻습니다. 서버명, URL 또는 command, 스코프를 확인한 뒤 승인하면 로드됩니다. 동료가 받은 .mcp.json도 이 게이트를 거칩니다.

조직 차원에서는 관리자가 허용 서버를 고정할 수 있습니다. managed-mcp.json(MDM으로 배포)이나 managed settings의 allowedMcpServers·deniedMcpServers로 서버를 allowlist/denylist합니다. denylist가 우선이라 allow로 되돌릴 수 없고, allowManagedMcpServersOnly를 켜면 managed allowlist만 유효해져 user·project·local 설정은 무시됩니다. 사내에서 실제로 어떤 서버를 허용하는지·어떤 managed 정책을 쓰는지는 조직 계정·정책에 따라 다르니 팀 설정을 확인하세요.

서버를 신중히 고르고 통제하는 가드레일이 왜 필요한지 — 그 배경은 에이전트 개념·3원칙에서 다룹니다. 다음으로 나아갈 곳을 모았습니다.

에이전트 가드레일 — 붙인 서버를 에이전트가 안전하게 쓰도록 통제하는 다음 단계.
Claude Code 실무 — MCP 개념과 기본 추가 형태. 이 문서의 출발점입니다.
안전·시크릿 입력 — 서버 설정·.mcp.json에 무엇을 넣어도 되고 무엇은 안 되는지.
에이전트 개념·3원칙 — 가드레일이 왜 필요한지의 근거.
용어집 — 낯선 용어는 여기서 한 줄로 확인.