MCP 서버 구성과 연결

서버를 붙이려면 먼저 트랜스포트(transport)를 정해야 한다. 트랜스포트는 클라이언트와 서버가 메시지를 주고받는 통신 방식이며, 세 가지가 있다.

• stdio는 서버를 로컬 자식 프로세스로 띄우고 표준입출력으로 통신한다. 같은 머신에서 도는 로컬 도구(파일 시스템, 로컬 DB, CLI 래퍼)에 적합하다. 네트워크 왕복이 없어 빠르고, 자격증명을 환경변수로 넘기기 쉽다.
• HTTP(스트리밍 가능한 HTTP)는 원격 서버에 네트워크로 연결한다. 팀 공용 지식베이스나 클라우드 서비스처럼 호스트 밖에 있는 서버에 쓴다. 현재의 표준 원격 트랜스포트다.
• SSE(Server-Sent Events)는 이전 세대 원격 트랜스포트로, 현재는 HTTP로 대체되며 사실상 폐기(deprecated) 단계다. 기존 SSE 서버는 아직 동작하지만, 새 서버는 HTTP로 만들어야 한다.

선택 기준은 위치다. 내 머신에서 도는 것은 stdio, 그 밖의 모든 것은 HTTP가 합리적 기본값이다. 시험은 "원격 팀 서버에 SSE로 새로 붙여라" 같은 보기를 함정으로 낸다. SSE는 폐기 중이므로 신규 연결의 정답이 될 수 없다.

연결은 CLI 한 줄로 추가한다. 기본 명령 형태는 다음과 같다.

# 터미널: stdio 서버 추가 (로컬 프로세스)claude mcp add my-db --transport stdio -- npx -y mcp-server-sqlite ./data.db# 터미널: HTTP 원격 서버 추가claude mcp add team-kb --transport http https://mcp.example.com/mcp

-- 뒤는 stdio 서버를 실제로 실행할 명령과 인자다. 이 구분 기호를 빠뜨리면 CLI가 명령 인자를 자기 옵션으로 오해한다. 트랜스포트를 생략하면 stdio가 기본값이다.

CLI 대신 설정 파일로 직접 적을 수도 있다. 프로젝트 루트의 .mcp.json이 그 파일이며, 팀과 공유하려면 이쪽을 쓴다. 구조는 최상위 mcpServers 객체 아래 서버 이름을 키로 둔다.

// .mcp.json{  "mcpServers": {    "my-db": {      "command": "npx",      "args": ["-y", "mcp-server-sqlite", "./data.db"]    },    "team-kb": {      "type": "http",      "url": "https://mcp.example.com/mcp",      "headers": {        "Authorization": "Bearer ${API_TOKEN}"      }    }  }}

여기서 구조를 정확히 외워 두자. stdio 서버는 command·args·env로 정의하고 type을 생략한다. HTTP 서버는 type을 "http"로 두고 url과 필요시 headers를 준다. ${API_TOKEN} 같은 표기는 환경변수 보간이다. 토큰 같은 비밀값을 파일에 직접 쓰지 않고 환경변수로 주입하는 것이 안전 설계이며, 그래서 커밋되는 .mcp.json에는 비밀값 대신 ${...} 참조만 남기는 것이 정석이다. 시험은 "팀 공유 .mcp.json에 API 키를 평문으로 적었다"를 안티패턴으로 묻는다.

서버를 추가한 뒤에는 호스트 안에서 연결 상태를 확인한다. Claude Code에서 /mcp 명령을 실행하면 등록된 서버 목록과 연결 상태(connected, failed 등), 그리고 각 서버가 노출하는 도구·리소스·프롬프트를 볼 수 있다. 원격 HTTP 서버가 OAuth 인증을 요구하면 /mcp가 브라우저 로그인 흐름을 띄워 토큰을 받아 온다. 즉 OAuth는 설정 파일에 적는 것이 아니라 /mcp를 통한 대화형 인증으로 처리한다는 점이 출제 포인트다.

연결이 실패할 때 점검 순서도 알아 두면 좋다. stdio라면 -- 뒤 실행 명령이 실제로 그 머신에서 동작하는지(예: npx·바이너리 경로), HTTP라면 URL과 인증 헤더가 맞는지 본다. 추가했는데 도구가 안 보이는 경우, 잘못된 스코프에 넣어 현재 프로젝트에서 로드되지 않는 상황이 흔하다. 스코프는 다음 절에서 다룬다.

정리

• 트랜스포트는 stdio(로컬 프로세스)·HTTP(원격, 표준)·SSE(폐기 중) 셋이며, "로컬은 stdio, 그 밖은 HTTP"가 기본 선택이다. SSE 신규 연결은 정답이 아니다.
• claude mcp add <이름> --transport <종류> ...로 추가하며, stdio는 -- 뒤에 실행 명령을 둔다. 트랜스포트 생략 시 stdio가 기본값이다.
• .mcp.json은 최상위 mcpServers 아래 서버를 정의한다. stdio는 command/args/env, HTTP는 type:"http"/url/headers를 쓴다.
• 비밀값은 ${ENV} 보간으로 주입하고 파일에 평문 키를 적지 않는다. 연결 확인과 원격 OAuth 로그인은 /mcp 명령으로 처리한다.