클로드 코드 mcp 연결 — 추가·확인·삭제 명령 정리
클로드 코드에 MCP 서버를 붙이는 건 명령 한 줄입니다. 인터넷에 있는 원격 서버는 claude mcp add --transport http 이름 주소, 내 컴퓨터에서 프로그램으로 도는 서버는 claude mcp add 이름 -- 실행명령입니다. 붙었는지는 claude mcp list로 보고(✔ Connected가 떠야 정상), 뗄 때는 claude mcp remove 이름입니다. 설정 파일을 손으로 열 필요가 없습니다. 아래에 명령별 실제 출력, 저장 위치(스코프) 세 가지, 그리고 윈도우 파워셸에서만 나는 unknown option '-y' 오류까지 정리했습니다. (2026년 8월 1일 기준 · CLI 2.1.204)
1. 원격 MCP 서버 연결하기 (http)
요즘 나오는 MCP 서버 대부분은 웹 주소 하나로 붙는 HTTP 방식입니다. 설치할 것도 없고 주소만 있으면 됩니다.
# 기본 형태
claude mcp add --transport http <이름> <주소>
# 실제 예
claude mcp add --transport http deepwiki https://mcp.deepwiki.com/mcp제대로 등록되면 아래처럼 Added ... 한 줄과 어느 파일이 바뀌었는지가 같이 나옵니다.
Added HTTP MCP server deepwiki with URL: https://mcp.deepwiki.com/mcp to local config
File modified: C:\Users\사용자\.claude.json [project: D:\project\myapp]토큰이 필요한 서버라면 --header로 인증 헤더를 같이 넘깁니다.
claude mcp add --transport http secure-api https://api.example.com/mcp \
--header "Authorization: Bearer 내토큰"--transport를 안 쓰면 stdio(내 컴퓨터에서 실행)로 봅니다. 주소를 넣었는데 --transport http를 빠뜨리면 그 주소를 실행할 프로그램 이름으로 읽습니다. 원격 서버를 붙일 때는 꼭 붙이세요. 예전 방식인 sse는 공식 문서에서 더 이상 권하지 않습니다(HTTP 권장).
2. 내 컴퓨터에서 도는 서버 연결하기 (stdio)
파일 접근처럼 로컬 권한이 필요한 서버는 내 컴퓨터에서 프로그램으로 돌아가는 방식(stdio)입니다. 이때는 --(하이픈 두 개) 뒤에 실행할 명령을 씁니다.
# 기본 형태
claude mcp add <이름> -- <실행명령> [인자...]
# 환경변수를 같이 넘기는 예
claude mcp add airtable -e AIRTABLE_API_KEY=내키 -- npx -y airtable-mcp-server--가 하는 일이 중요합니다. 그 앞은 클로드 코드의 옵션, 그 뒤는 서버를 실행할 명령이라고 갈라 줍니다. 이게 없으면 서버 쪽 플래그(-y, --port 같은 것)를 클로드 코드가 자기 옵션으로 잘못 읽고 오류를 냅니다. 6번 항목에서 다시 다룹니다.
3. 잘 붙었는지 확인하기 — list와 get
등록만 됐다고 연결까지 된 건 아닙니다. claude mcp list는 서버마다 실제로 연결을 시도해 상태를 찍어 줍니다.
$ claude mcp list
Checking MCP server health…
shared: https://mcp.deepwiki.com/mcp (HTTP) - ⏸ Pending approval (run `claude` to approve)
deepwiki: https://mcp.deepwiki.com/mcp (HTTP) - ✔ Connected
b2: npx some-mcp-server - ✘ Failed to connect| 표시 | 뜻과 할 일 |
|---|---|
✔ Connected |
정상. 바로 쓸 수 있습니다 |
✘ Failed to connect |
주소나 실행 명령이 틀렸거나 서버가 안 뜬 것. 목록 명령이 실패한 게 아닙니다 |
! Needs authentication |
로그인이 필요. claude mcp login 이름으로 인증 |
⏸ Pending approval |
프로젝트 스코프(.mcp.json) 서버가 승인 대기 중. claude를 켜서 승인 |
서버 하나만 자세히 보려면 claude mcp get 이름입니다. 어느 스코프에 저장됐는지와 지우는 명령까지 같이 알려 줍니다.
$ claude mcp get deepwiki
deepwiki:
Scope: Local config (private to you in this project)
Status: ✔ Connected
Type: http
URL: https://mcp.deepwiki.com/mcp
To remove this server, run: claude mcp remove deepwiki -s local클로드 코드를 켠 뒤 세션 안에서는 /mcp를 치면 연결된 서버와 도구 개수를 화면으로 볼 수 있습니다. 어떤 서버를 붙일지 고르는 단계라면 개발자에게 쓸모 있는 MCP 서버 추천을 먼저 보고 오세요.
4. 어디에 저장되나 — 스코프 3가지
--scope(-s) 옵션이 설정을 어느 파일에 쓸지를 정합니다. 안 쓰면 local입니다.
| 스코프 | 적용 범위 | 팀 공유 | 저장 위치 |
|---|---|---|---|
local (기본) |
지금 이 프로젝트만 | 안 됨 | ~/.claude.json |
project |
지금 이 프로젝트만 | 됨 (깃에 올림) | 프로젝트 루트의 .mcp.json |
user |
내 모든 프로젝트 | 안 됨 | ~/.claude.json |
팀원 모두가 같은 서버를 쓰게 하려면 --scope project로 넣고 .mcp.json을 깃에 올리면 됩니다. 명령을 실행하면 파일이 알아서 만들어집니다.
$ claude mcp add --transport http shared --scope project https://example.com/mcp
Added HTTP MCP server shared with URL: https://example.com/mcp to project config
File modified: D:\project\myapp\.mcp.json
$ cat .mcp.json
{
"mcpServers": {
"shared": {
"type": "http",
"url": "https://example.com/mcp"
}
}
}단, .mcp.json으로 받은 서버는 바로 연결되지 않고 승인을 기다립니다(위 표의 ⏸ Pending approval). 아무 저장소나 받아서 열었을 때 모르는 서버가 자동으로 붙는 걸 막기 위해서입니다. claude를 켜서 승인하면 그때부터 연결됩니다. 승인 기록을 되돌리려면 claude mcp reset-project-choices입니다.
API 키를 .mcp.json에 그대로 적어 올리면 안 됩니다. 환경변수 자리를 만들어 두는 문법이 있습니다.
{
"mcpServers": {
"api-server": {
"type": "http",
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": { "Authorization": "Bearer ${API_KEY}" }
}
}
}${API_KEY}는 환경변수 값으로, ${VAR:-기본값}은 변수가 없을 때 기본값으로 바뀝니다. 변수도 없고 기본값도 없으면 설정이 죽지는 않고, claude mcp list에 경고가 뜨면서 ${VAR} 글자 그대로 쓰입니다. 즉 조용히 잘못된 값으로 붙을 수 있으니 목록 출력을 한 번은 봐야 합니다.
5. 삭제와 자주 보는 메시지
$ claude mcp remove deepwiki
Removed MCP server "deepwiki" from local config
# 이름을 틀리면 — 지금 등록된 이름을 같이 알려 준다
$ claude mcp remove nosuch
No MCP server named "nosuch". Configured servers: b2, deepwiki, p2, shared
# 같은 이름으로 또 추가하면 — 덮어쓰지 않고 거절한다
$ claude mcp add --transport http deepwiki https://mcp.deepwiki.com/mcp
MCP server deepwiki already exists in local config주소를 바꾸고 싶다면 지우고 다시 추가해야 합니다. 같은 이름으로 덮어쓰기는 안 됩니다. 설정을 남겨 둔 채 잠깐만 끄고 싶으면 지우지 말고 세션 안 /mcp 화면에서 토글로 끄면 됩니다.
6. 윈도우 파워셸에서 unknown option '-y' 가 뜰 때
공식 문서 그대로 쳤는데 아래 오류가 나면, 명령이 틀린 게 아니라 파워셸이 --를 먹어 버린 것입니다.
PS> claude mcp add airtable -e API_KEY=xxx -- npx -y airtable-mcp-server
error: unknown option '-y'Windows PowerShell 5.1은 프로그램을 부를 때 인자로 넘긴 -- 하나를 지워 버립니다. 그래서 뒤에 오는 -y가 클로드 코드 자신의 옵션처럼 보이고, 모르는 옵션이라며 멈춥니다. 같은 명령을 Git Bash나 명령 프롬프트에서 치면 정상 등록됩니다.
--를 따옴표로 감싸면 그대로 넘어갑니다. 참고로 파싱 중지 토큰 --%는 이 경우 unknown option '--%'가 떠서 해결이 안 됩니다.
PS> claude mcp add airtable -e API_KEY=xxx '--' npx -y airtable-mcp-server
Added stdio MCP server airtable with command: npx -y airtable-mcp-server to local config클로드 코드를 아직 안 깔았거나 명령 자체가 안 먹으면 클로드 코드 설치 글의 경로 설정 부분을 먼저 확인하세요.
자주 묻는 질문 (FAQ)
Q. ✘ Failed to connect이 떴는데 명령이 실패한 건가요?
아닙니다. 등록은 됐고 연결만 안 된 상태입니다. 원격 서버면 주소·토큰을, stdio 서버면 -- 뒤 실행 명령이 그 자리에서 실제로 돌아가는지(예: npx -y 패키지명) 먼저 확인하세요.
Q. 설정 파일을 직접 열어서 고쳐도 되나요?
됩니다. local·user는 ~/.claude.json, project는 프로젝트 루트의 .mcp.json입니다. 다만 ~/.claude.json은 프로젝트별 항목이 섞여 있어 손으로 고치다 깨뜨리기 쉬우니 명령을 쓰는 쪽이 안전합니다.
Q. 같은 이름의 서버가 여러 곳에 있으면 어느 게 이기나요?
공식 문서 기준 local → project → user → 플러그인 제공 서버 → claude.ai 커넥터 순서입니다. 앞선 것 하나가 통째로 쓰이고, 스코프끼리 설정을 합치지는 않습니다.
Q. 플러그인으로 들어온 MCP 서버도 이 명령으로 관리하나요?
아닙니다. 플러그인이 딸려 오는 서버는 플러그인 쪽에서 켜고 끕니다. 클로드 코드 플러그인 설치를 참고하세요.
마무리
정리하면 원격은 claude mcp add --transport http 이름 주소, 로컬은 claude mcp add 이름 -- 실행명령, 확인은 claude mcp list, 삭제는 claude mcp remove 이름 네 개면 충분합니다. 혼자 쓸 거면 기본값(local)으로 두고, 팀과 같이 쓸 거면 --scope project로 .mcp.json을 만들어 깃에 올리되 키는 ${환경변수}로 빼세요. 윈도우 파워셸이라면 --를 따옴표로 감싸는 것만 기억하면 됩니다.
MCP는 클로드 코드 버전이 오를 때마다 동작이 조금씩 달라지는 편입니다. 위 내용은 CLI 2.1.204 기준이니, 명령이 예상과 다르게 동작하면 claude mcp --help와 아래 공식 문서를 먼저 확인해 보세요.
📚 참고 출처 (2026년 8월 1일 확인)
· Claude Code — Connect Claude Code to tools via MCP
· 본문의 명령 출력은 Windows 11 · Claude Code 2.1.204 에서 직접 실행해 확인했습니다.
COMMENTS