Claude Code에 MCP 서버 추가(claude mcp add, .mcp.json, 스코프)

원격 서버에는 HTTP가 권장 전송 방식입니다. Stdio 서버는 머신의 로컬 프로세스로 실행됩니다. stdio에서는 -- 구분자가 Claude 자체 옵션(--transport, --env, --scope 등)과 서버를 시작하는 명령을 구분합니다. -- 뒤의 모든 내용은 그대로 서버에 전달됩니다.

# Remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# HTTP server with a Bearer token header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# Local stdio server with an environment variable
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

• 환경 변수는 -e 또는 --env로 설정합니다. 예: -e KEY=value.
• 서버 이름이 --env 바로 뒤에 오면 CLI가 이름을 또 다른 쌍으로 읽고 거부합니다. --env와 이름 사이에 --transport stdio 같은 다른 옵션을 넣습니다.
• --transport와 --header는 짧은 형식 -t와 -H도 받습니다.
• SSE는 지원 중단되었습니다. SSE 전용 서버에 연결하려면 여전히 --transport sse를 전달할 수 있습니다.
• 서버의 JSON 설정이 이미 있다면 claude mcp add-json NAME 'JSON'으로 추가합니다.

-s 또는 --scope로 세 가지 스코프 중 하나를 선택합니다. Local(기본값)은 현재 프로젝트에서만 로드되며 ~/.claude.json에 저장됩니다. Project는 프로젝트 루트의 .mcp.json에 저장되므로 팀이 버전 관리로 받습니다. User도 ~/.claude.json에 저장되지만 모든 프로젝트에서 로드됩니다. 같은 서버 이름이 여러 스코프에 정의되면 local이 project보다, project가 user보다 우선합니다.

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

.mcp.json은 command, args, env, url, headers에서 ${VAR}와 ${VAR:-default} 확장을 지원합니다. 원격 항목에는 항상 type을 설정합니다. Claude Code는 type이 없는 항목을 stdio 서버로 취급하므로, url은 있지만 type이 없는 항목은 설정 오류입니다.

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    },
    "local-weather": {
      "type": "stdio",
      "command": "/path/to/weather-cli",
      "args": ["--api-key", "${WEATHER_API_KEY}"],
      "env": { "CACHE_DIR": "/tmp" }
    }
  }
}

• Claude Code는 .mcp.json의 project 스코프 서버를 사용하기 전에 승인을 요청합니다. 그 선택은 claude mcp reset-project-choices로 초기화합니다.
• 참조한 변수가 설정되지 않았고 기본값도 없으면 서버는 리터럴 ${VAR} 텍스트로 로드되며, claude mcp list에 경고가 표시됩니다.

Claude Code는 원격 서버에 OAuth 2.0을 지원합니다. 로그인이 필요한 서버를 추가한 후 Claude Code 안에서 /mcp를 실행하고 브라우저에서 로그인을 완료합니다. 토큰은 안전하게 저장되며 자동으로 갱신됩니다. 접근 권한을 취소하려면 /mcp 메뉴의 Clear authentication을 사용합니다.

claude mcp list
claude mcp get notion
claude mcp remove notion
claude mcp login sentry
claude mcp logout sentry

원격 서버를 제거하면 Claude Code가 저장한 해당 서버의 OAuth 토큰도 삭제됩니다. 한 스코프에서만 정의를 제거하려면 claude mcp remove NAME --scope SCOPE를 실행합니다.

• MCP_TIMEOUT은 서버 시작 타임아웃을 밀리초 단위로 설정합니다. 예: MCP_TIMEOUT=10000 claude.
• MCP_TOOL_TIMEOUT은 도구 실행 타임아웃을 설정합니다. 특정 서버에 대해서는 해당 서버의 .mcp.json 항목에 timeout 필드(밀리초)로 재정의합니다.
• Claude Code는 MCP 도구 출력이 10,000 token을 넘으면 경고하고, 기본적으로 25,000 token으로 제한합니다. 제한을 높이려면 MAX_MCP_OUTPUT_TOKENS를 사용합니다.

export MAX_MCP_OUTPUT_TOKENS=50000
MCP_TIMEOUT=10000 claude