쉽게 배우는 Claude Code ⑬ /mcp — 외부 도구(GitHub·DB 등) 연결하기

지금까지 Claude Code는 주로 “내 컴퓨터 안”에서 일했습니다. 파일을 읽고, 코드를 고치고, 셸 명령을 돌리는 식으로요. 그런데 실제 개발은 거기서 끝나지 않죠. GitHub에 이슈가 쌓이고, 데이터베이스에 데이터가 들어 있고, 사내 API가 돌아갑니다. “이 작업을 Claude가 직접 해주면 좋을 텐데” 싶은 순간이 옵니다.

이럴 때 다리를 놓아 주는 게 MCP(Model Context Protocol)이고, 그 연결을 관리하는 명령이 /mcp입니다. 이번 편에서 쉽게 정리해 보겠습니다.

한 줄로

MCP는 Claude가 GitHub·데이터베이스·사내 API 같은 외부 도구·서비스에 연결해 그 기능을 도구처럼 쓸 수 있게 해주는 표준입니다.

/mcp는 그 MCP 서버 연결과 인증(OAuth)을 관리하는 명령입니다. MCP 서버를 한 번 붙여 두면, Claude가 그 서버가 제공하는 도구들을 직접 호출할 수 있게 됩니다.

언제 쓰나

핵심은 “Claude가 내 컴퓨터 밖의 도구를 직접 쓰게 하고 싶을 때”입니다. 몇 가지 예를 보겠습니다.

★ 예제 1 — GitHub의 이슈·PR을 Claude가 직접 조회/처리

“이번 마일스톤에 열려 있는 이슈를 정리해줘” 같은 부탁을, 사람이 GitHub를 일일이 뒤져 복사해 오지 않고 맡기고 싶을 때가 있습니다.

GitHub MCP 서버를 연결해 두면, Claude가 이슈와 PR을 직접 조회하고 처리할 수 있습니다. 정보를 사람이 떠먹여 줄 필요 없이, Claude가 그 도구를 호출해 알아서 가져옵니다.

★ 예제 2 — 사내 데이터베이스에 대고 질문에 답하게

“지난달 가입자 수가 몇 명이지?” 같은 질문에 답하려면 보통 누군가 DB에 쿼리를 날려야 합니다.

사내 데이터베이스 조회 도구를 MCP로 붙여 두면, Claude가 그 도구로 데이터를 직접 조회해 답을 만들어 줄 수 있습니다. 데이터에 대한 질문을, 데이터에 닿을 수 있는 Claude에게 바로 던지는 셈입니다.

★ 예제 3 — 인증이 만료돼 도구가 안 먹을 때 빠르게 재연결

외부 서비스 연결에는 보통 OAuth 인증이 따라옵니다. 그런데 OAuth 토큰은 시간이 지나면 만료되죠. 어제까지 잘 되던 GitHub 도구가 갑자기 안 먹는 일이 생깁니다.

이럴 때는 /mcp reconnect <서버>로 해당 서버를 다시 인증하면 됩니다. 연결 전체를 처음부터 다시 설정할 필요 없이, 막힌 서버 하나만 빠르게 되살리는 용도입니다.

어떻게

연결 목록 보기 — /mcp

세션 중에 인자 없이 /mcp를 입력하면, 현재 연결된 MCP 서버 목록을 대화형으로 보여줍니다. 어떤 서버가 붙어 있고, 인증 상태가 어떤지 여기서 확인합니다.

/mcp

관리하기 — /mcp [reconnect|enable|disable]

목록을 보는 데서 그치지 않고, 인자로 곧장 관리할 수도 있습니다.

명령	하는 일
`/mcp`	연결 목록을 대화형으로 표시
`/mcp reconnect <서버>`	해당 서버를 빠르게 재연결(재인증)
`/mcp enable <서버\|all>`	해당 서버(또는 전체)를 켜기
`/mcp disable <서버\|all>`	해당 서버(또는 전체)를 끄기

예를 들어 /mcp reconnect github은 GitHub 서버만 다시 인증하고, /mcp disable all은 모든 서버를 한 번에 꺼 둡니다.

시작할 때 정의하기 — --mcp-config

세션 도중이 아니라 시작 시점에 MCP 서버를 정의하고 싶을 때는 시작 플래그를 씁니다. JSON 파일이나 문자열로 서버를 지정합니다.

claude --mcp-config ./mcp-servers.json

로컬 도구나 사내 API처럼 “이 세션에서 쓸 서버”를 미리 정해 두는 데 잘 맞습니다. 매번 손으로 붙이지 않고, 설정으로 한 번에 들고 시작하는 방식입니다.

팁 & 함정

쓸 도구는 가급적 미리 설정해 두세요. 세션 도중에 MCP 도구를 추가하거나 제거하면 프롬프트 캐시가 무효화될 수 있습니다. 캐시가 깨지면 그만큼 처리 비용과 시간이 늘 수 있으니, 이번 작업에 필요한 도구는 --mcp-config로 시작할 때 들고 들어가는 편이 깔끔합니다.
안 쓰는 서버는 꺼 두세요. 붙여 두기만 하고 쓰지 않는 서버가 많으면 목록이 어수선해집니다. /mcp disable로 꺼 두면 깔끔하고, 필요할 때 enable로 다시 켜면 됩니다.
도구가 갑자기 안 먹으면 인증부터 의심하세요. OAuth 만료가 흔한 원인입니다. 연결을 통째로 다시 만들기 전에 /mcp reconnect <서버>로 해당 서버만 재인증해 보세요.
MCP 서버는 외부에 닿습니다. 외부 서비스·데이터에 접근하는 통로인 만큼, 신뢰할 수 있는 서버만 붙이는 게 좋습니다. 권한 관리는 앞 편에서 다룬 /permissions와도 이어집니다 — MCP 도구 접근도 같은 방식으로 조절할 수 있습니다.

한 장 정리

상황	손잡이
연결된 MCP 서버를 보고 싶다	`/mcp`
인증이 만료돼 도구가 안 먹는다	`/mcp reconnect <서버>`
서버를 켜거나 끄고 싶다	`/mcp enable\|disable <서버\|all>`
시작할 때 서버를 정의하고 싶다	`claude --mcp-config <json>`
GitHub·DB·사내 API를 Claude가 직접 쓰게 하고 싶다	MCP 서버 연결
캐시를 지키고 싶다	쓸 도구는 미리 설정, 안 쓰는 건 `disable`

다음 편: /diff — 내가 뭘 바꿨는지 한눈에 보기.