MCP2026.09.03

[MCP] Claude Code에 MCP 서버 붙이기: 등록부터 연결 확인까지

공개된 MCP 서버를 Claude Code에 등록해 대화 중에 새 도구를 쓰는 방법을, 명령어와 설정 파일 형식까지 순서대로 정리했습니다.

안녕하세요, muaco입니다.

이 글로 할 수 있는 일

이 글을 끝까지 따라 하면 이미 공개된 MCP 서버를 Claude Code에 붙여서 원래 없던 도구를 대화 중에 쓰게 됩니다. 터미널에서 claude mcp add 한 줄로 서버를 등록하고 claude mcp list로 연결 상태를 확인하고 로그인이 필요한 서버는 /mcp에서 인증까지 마칩니다. 설정을 팀과 공유하는 .mcp.json 파일 형식도 같이 봅니다. 서버를 직접 개발하지는 않습니다. 남이 만들어 둔 서버를 가져다 연결만 합니다.

MCP(Model Context Protocol)는 AI 애플리케이션을 외부 시스템에 연결하는 공개 표준입니다. 공식 문서는 MCP를 기기를 하나의 규격으로 잇는 USB 단자에 비유합니다. 참여자는 셋입니다. Claude Code 같은 AI 앱이 호스트, 서버마다 하나씩 만들어지는 연결 담당이 클라이언트, 실제 기능을 내주는 프로그램이 서버입니다. 서버가 내주는 기능도 세 가지로 나뉩니다. 실행 가능한 함수인 도구(tools), 참고 자료를 넘겨주는 리소스(resources), 대화 틀을 담은 프롬프트(prompts)입니다. 업무에서 체감하는 부분은 대부분 도구입니다.

미리 갖춰야 할 준비물

Claude Code가 설치돼 있고 터미널(명령을 글자로 쳐서 쓰는 검은 창)에서 claude 명령이 실행되어야 합니다.
붙일 서버 정보가 필요합니다. 인터넷 너머에 있는 원격 서버라면 접속 주소(URL), 내 컴퓨터에서 돌리는 로컬 서버라면 실행 명령입니다.
서버가 요구하면 토큰이나 계정이 필요합니다. 예를 들어 GitHub 서버 예제는 개인 액세스 토큰을 헤더에 넣습니다.
로컬 서버 실행에 npx를 쓰는 경우가 많습니다. 이때는 Node.js가 미리 깔려 있어야 합니다.
MCP 연결 자체의 추가 요금은 공식 문서에 나와 있지 않습니다. 연결하는 외부 서비스가 따로 요금을 매길 수는 있습니다.

따라 하기

터미널을 열고 작업 폴더로 이동합니다. 등록 명령의 기본 저장 범위가 현재 프로젝트이기 때문에 어느 폴더에서 명령을 쳤는지가 결과를 바꿉니다. 프롬프트에 그 폴더 이름이 보이면 됐습니다.
원격 서버를 등록합니다. 문서는 원격 서버에 HTTP를 권장합니다. SSE 전송은 문서가 더 이상 권장하지 않는다고(deprecated) 표시했으니, 남의 서버 설명서에 sse가 적혀 있으면 같은 서버의 HTTP 주소가 있는지 먼저 찾아보세요. 터미널에 아래를 칩니다.
```
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"
```
github 자리가 이 서버를 부를 이름입니다. 이름에는 영문자, 숫자, 하이픈, 밑줄만 쓸 수 있습니다. --header는 짧게 -H로도 씁니다. 명령이 끝나고 오류 문구가 없으면 등록은 된 상태입니다. 다만 문서는 claude mcp add가 자격 증명을 확인하지 않고 설정만 저장한다고 밝힙니다. 토큰이 틀려도 등록은 성공하고 나중에 연결 단계에서 실패합니다.
내 컴퓨터에서 도는 서버를 등록합니다. 로컬 프로그램은 표준 입출력으로 이야기하는 stdio 방식을 씁니다.
```
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server
```
여기서 -- 두 개가 중요합니다. 문서는 이 기호가 Claude 자신의 옵션(--transport, --env, --scope)과 서버를 실행할 명령을 갈라놓는다고 설명합니다. 뒤쪽은 손대지 않고 그대로 서버에 넘어갑니다. 이 기호를 빠뜨리면 서버 실행 인자를 Claude가 자기 옵션으로 읽고 실패합니다.
설정을 어디에 저장할지 정합니다. -s 또는 --scope로 고릅니다. local은 기본값이고 현재 프로젝트에서 나만 씁니다. project는 .mcp.json 파일로 저장돼 팀 전체가 공유합니다. user는 내 모든 프로젝트에서 쓰입니다. 혼자 시험할 때는 기본값으로 두고 팀에 퍼뜨릴 때만 --scope project를 붙이면 됩니다.
```
claude mcp add --transport http server-name <url> --scope project
```
설정 파일을 직접 손봅니다. 프로젝트 범위 설정은 프로젝트 최상위 폴더의 .mcp.json에 쌓입니다. 파일이 없으면 새로 만들고 이미 있으면 mcpServers 안쪽에 서버 항목만 추가합니다.
```
{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}
```
토큰을 파일에 그대로 적기 싫다면 환경 변수를 참조합니다. ${VAR}는 값을 끼워 넣고 ${VAR:-default}는 값이 없을 때 기본값을 씁니다.
```
{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}
```
연결 상태를 확인합니다. 터미널에서 claude mcp list를 칩니다. 문서에 적힌 상태 표시는 이렇습니다. Connected는 정상, Needs authentication은 로그인 필요, Failed to connect는 연결 실패입니다. 프로젝트 범위 서버는 처음에 Pending approval (run claude to approve)로 나옵니다. 문구 그대로 터미널에서 claude를 실행해 세션에 들어가면 승인 요청이 뜨고 승인하면 이 상태가 풀립니다. 특정 서버 하나만 자세히 보려면 claude mcp get <name>을 씁니다.
인증이 필요하면 로그인합니다. Claude Code 안에서 /mcp를 치고 서버를 고르면 브라우저 로그인으로 이어집니다. 터미널에서 바로 하려면 claude mcp login <name>입니다. 브라우저가 없는 원격 접속 환경에서는 --no-browser를 붙입니다. 로그인 뒤 claude mcp list가 Connected로 바뀌면 끝났습니다.
실제로 시켜 봅니다. Claude Code 세션에서 그 서버가 담당하는 일을 평소 말투로 부탁합니다. 도구를 쓰겠다는 승인 요청이 뜨고 승인하면 결과가 돌아옵니다. 여기까지 오면 연결이 살아 있다는 증거입니다. 필요 없어진 서버는 claude mcp remove <name>으로 지웁니다.

막히기 쉬운 곳

type을 빠뜨렸다는 오류. 문서에 적힌 문구는 이렇습니다. MCP server "<name>" has a "url" but no "type". JSON에 주소만 적고 종류를 안 적으면 납니다. 해당 항목에 "type": "http"를 넣으면 해결됩니다.
붙여넣은 토큰에 딸려 온 공백과 줄바꿈. Claude Code는 설정 값 앞뒤에 보이지 않는 공백이 있으면 경고합니다. 웹에서 토큰을 복사할 때 끝에 줄바꿈이 묻어 오는 사고가 흔합니다. 값을 다시 정리해 붙여 넣으세요.
환경 변수를 못 찾는 경우. ${VAR}를 썼는데 값도 없고 :- 기본값도 없으면 경고가 뜹니다. export MY_VAR=value로 값을 넣거나 기본값을 적어 두면 됩니다.
서버가 늦게 떠서 실패할 때. 시작 대기 시간은 MCP_TIMEOUT 환경 변수로 늘립니다(단위는 밀리초). 도구 실행이 오래 걸리는 서버라면 MCP_TOOL_TIMEOUT을 쓰거나, .mcp.json의 해당 서버에 timeout 값을 넣습니다.
헤더를 만들어 주는 headersHelper의 상대 경로. 문서는 headersHelper 명령이 어느 폴더에서 실행되는지를 설정 위치별로 표에 정리해 뒀습니다. 프로젝트 .mcp.json이나 local 범위 서버는 그 서버를 적어 둔 프로젝트 폴더, user 범위는 설정 폴더(기본값 ~/.claude)가 기준입니다. 경로가 안 맞으면 절대 경로로 바꿔 보세요.

여기서 더 나아가려면

Claude Desktop에 이미 서버를 등록해 뒀다면 claude mcp add-from-claude-desktop으로 옮겨올 수 있습니다. 다른 도구에서 쓰던 JSON 블록이 있다면 claude mcp add-json <name> '<json>'으로 그대로 넣습니다. 반대로 Claude Code 자체를 서버로 내주는 claude mcp serve도 있으니, 연결에 익숙해진 뒤 공식 문서에서 확인해 보시기 바랍니다.

이상으로 글 마치겠습니다.

출처

#MCP#Claude Code#연동#서버#AI 도구#터미널#업무자동화