Source: https://aiprimetech.io/ko/claude-code/mcp/

[홈](/ko/) › [Claude Code](/ko/claude-code/) › MCP

[개요](/ko/claude-code/)[설치](/ko/claude-code/install/)[CLI 참조](/ko/claude-code/cli/)[요금 및 한도](/ko/claude-code/pricing/)[Agent SDK](/ko/claude-code/sdk/)[스킬 및 플러그인](/ko/claude-code/skills/)[GitHub](/ko/claude-code/github/)[웹, 데스크톱 및 IDE](/ko/claude-code/web-and-desktop/)[모델](/ko/claude-code/models/)[오류](/ko/claude-code/errors/)[오픈 소스인가요?](/ko/claude-code/open-source/)[튜토리얼](/ko/claude-code/tutorial/)[학생용 안내](/ko/claude-code/for-students/)[QA 자동화](/ko/claude-code/qa-automation/)[Cursor와 비교](/ko/claude-code/vs-cursor/)[Codex 및 OpenCode와 비교](/ko/claude-code/vs-codex/)[하위 에이전트](/ko/claude-code/subagents/)[훅](/ko/claude-code/hooks/)[MCP](/ko/claude-code/mcp/)[생태계](/ko/claude-code/ecosystem/)[VS Code](/ko/claude-code/vscode/)[OpenRouter](/ko/claude-code/openrouter/)[요청 속도 제한](/ko/claude-code/rate-limits/)[중국어 가이드](/claude-code/zh/)

최종 업데이트: 2026년 10월 11일

# Claude Code MCP: 서버 연결, 범위, 원격 MCP와 실제 예제

MCP(Model Context Protocol)는 Claude Code가 저장소의 파일이 아닌 대상, 즉 데이터베이스, 브라우저, GitHub, 분석 도구, 티켓 추적 도구에 접근하는 방식입니다. 서버는 도구와 리소스를 제공하며, Claude Code가 서버에 연결하면 에이전트는 이를 내장 도구처럼 사용할 수 있습니다. 서버마다 명령 하나로 설정할 수 있습니다.

## TLDR
- claude mcp add <name> -- <command> 로컬(stdio) 서버용; claude mcp add --transport http <name> <url> 원격 서버용.
- 범위: 로컬(본인, 이 프로젝트), 프로젝트(.mcp.json, 저장소와 함께 공유), 사용자(본인, 모든 프로젝트).
- /mcp 세션 내에서 상태를 표시하고, OAuth 서버를 인증하며, 해당 서버의 도구 목록을 보여 줍니다.
- 리소스는 @멘션으로 참조할 수 있으며, 서버 프롬프트는 슬래시 명령으로 표시됩니다.

## 서버 추가 

```
# local server over stdio (runs the command, talks over its stdin/stdout)
claude mcp add playwright -- npx @playwright/mcp@latest

# remote server over HTTP
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# with a header (API-key style auth)
claude mcp add --transport http posthog https://mcp.posthog.com/mcp \
  --header "Authorization: Bearer $POSTHOG_API_KEY"

claude mcp list      # what is configured
claude mcp remove playwright
```

stdio 서버는 Claude Code가 대신 실행해 주는 프로그램입니다. 대부분의 커뮤니티 서버는 이 방식으로 실행하는 npm 또는 Python 패키지입니다. 원격 서버는 URL로 연결하며, OAuth로 인증하거나(세션에서 /mcp 명령을 실행하고 브라우저의 인증 절차를 따름), PostHog 예제처럼 추가할 때 전달하는 헤더로 인증합니다. 원격 엔드포인트는 변경될 수 있으므로 각 제공업체의 문서에서 현재 URL을 확인하세요. 

## 범위와 .mcp.json 
- 로컬 (기본값) — 사용자 설정에 저장되며, 이 프로젝트에만 적용됩니다. 개인용 비공개 서버에 적합합니다.
- 프로젝트 (--scope project) — 다음 파일에 기록됩니다: .mcp.json 저장소 루트에 저장되며, 저장소를 복제하는 모든 사람과 공유됩니다. Claude Code는 프로젝트의 서버를 처음 신뢰하기 전에 확인을 요청합니다.
- 사용자 (--scope user) — 컴퓨터의 모든 프로젝트에서 사용할 수 있습니다. 

```
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
    }
  }
}
```

.mcp.json 환경 변수 확장을 지원하므로, 저장소에 서버 정의를 포함하면서 각 개발자가 자신의 인증 정보를 제공할 수 있습니다. 

## 세션에서 서버 사용 

연결되면 서버의 도구를 바로 사용할 수 있습니다. "PostHog에서 최근 24시간 동안 발생한 오류"를 요청하면 Claude Code가 해당 도구를 호출합니다. 서버가 제공하는 리소스는 @멘션(@github:issue://123)으로 참조할 수 있으며, 필요할 때 컨텍스트로 불러옵니다. 서버가 정의한 프롬프트는 다음 경로 아래에 슬래시 명령으로 표시됩니다: /mcp__<server>__<prompt>. /mcp 연결 상태를 표시하고, 재연결이나 인증을 수행할 수 있으며, 모든 도구와 각 도구의 설명을 나열합니다. 

## 복사해서 활용할 만한 예제 
- PostHog MCP — 에이전트 내에서 제품 분석을 수행합니다. "이 코드는 어떤 기능 플래그로 제어되며, 롤아웃 상태는 어떤가요?" PostHog는 원격 MCP 서버를 제공합니다. 다음 명령으로 추가하고 --transport http 개인 API 키를 Bearer 헤더로 전달하세요.
- GitHub — 이슈와 풀 리퀘스트를 컨텍스트로 사용합니다. GitHub 가이드의 Action과 함께 사용하여 리뷰를 반복하세요.
- Playwright — 엔드투엔드 테스트와 방금 변경한 UI 확인에 사용하는 실제 브라우저입니다. QA 자동화 가이드를 참고하세요.
- Postgres / SQLite — 스키마를 고려한 쿼리와 마이그레이션입니다. 쓰기 작업을 의도한 경우가 아니라면 읽기 전용 사용자를 지정하세요.
- 저장소 외부의 파일 시스템 — --add-dir 추가 디렉터리에는 더 간단한 방법입니다. MCP는 파일이 아닌 대상을 위한 것입니다. 

## 비용과 컨텍스트 

MCP 서버가 반환하는 모든 도구 결과는 대화에 포함되며, 이후 매 턴마다 다시 전송됩니다. 5,000개의 행을 반환하는 서버는 컨텍스트를 폭증시킵니다. 결과 수를 제한할 수 있는 도구를 우선 사용하고, 요약을 요청하며, /compact 대량 쿼리 후에 실행하세요. 서버는 로컬이나 제공업체 측에서 실행되며 모델 엔드포인트를 거치지 않으므로 ANTHROPIC_BASE_URL=https://aiprimetech.io 에는 영향을 주지 않습니다. 결과가 소비하는 토큰에 대해서만 요금이 부과됩니다.

## 먼저 무료로 사용해 보세요

신규 계정에는 $5의 무료 API 크레딧이 제공됩니다 사용할 코드: CLAUDECODE — Sonnet으로 저녁 한나절 Claude Code를 사용하기에 충분합니다. 이후에는 액면가의 7.69231배에 해당하는 크레딧이 제공됩니다.

```
export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key
```

[코드 CLAUDECODE로 계정 만들기](/register?promo=CLAUDECODE)

## 자주 묻는 질문

Claude Code에 MCP 서버를 어떻게 추가하나요?

로컬 서버에는 `claude mcp add <name> -- <command>`을, 원격 서버에는 `claude mcp add --transport http <name> <url>`을 사용하세요. .mcp.json을 통해 공유하려면 `--scope project`를 추가하세요.PostHog를 Claude Code에 어떻게 연결하나요?

PostHog의 MCP 문서에 있는 URL을 사용하여 `claude mcp add --transport http posthog <url> --header "Authorization: Bearer <api key>"`으로 PostHog 원격 MCP 서버를 추가한 다음, 세션에서 이벤트, 플래그 또는 오류에 관해 질문하세요.MCP는 게이트웨이를 통해서도 작동하나요?

네. MCP 서버는 로컬이나 제공업체 측에서 실행되며 모델 엔드포인트와 독립적입니다. 서버 결과가 소비하는 토큰에 대해서만 게이트웨이를 통해 요금이 부과됩니다.

## 게이트웨이에서 Claude Code 실행하기

동일한 모델, 환경 변수 두 개, 액면가의 7.69231배에 해당하는 크레딧 또는 정액 무제한 요금제를 이용하세요. 신규 계정: 코드 CLAUDECODE로 $5의 무료 API 크레딧을 받으세요.[API 키 발급받기](/register?promo=CLAUDECODE) [무제한 요금제 보기](/ko/plans/)

AI Prime Tech는 독립 API 게이트웨이이며 Anthropic과 제휴 관계가 없고, Anthropic의 보증이나 후원을 받지 않습니다. “Claude”와 “Claude Code”는 Anthropic의 상표입니다. 여기에 설명된 Claude Code 기능은 작성 당시 Anthropic의 공개 문서를 기준으로 하며 자주 변경됩니다. 이 페이지의 가격과 모델 목록은 이 게이트웨이의 실시간 설정에서 가져옵니다.

## 더 많은 Claude Code 가이드

[Claude Code: 완벽 가이드](/ko/claude-code/)[Claude Code 설치 방법](/ko/claude-code/install/)[Claude Code CLI 문서: 명령어와 플래그](/ko/claude-code/cli/)[Claude Code 요금 및 한도 설명](/ko/claude-code/pricing/)[Claude Code SDK, 이제 Claude Agent SDK로](/ko/claude-code/sdk/)[Claude Code 스킬과 플러그인](/ko/claude-code/skills/)[GitHub에서 Claude Code 사용하기: App, Action 및 @claude](/ko/claude-code/github/)[Claude Code에 웹 인터페이스가 있나요? 웹, 데스크톱 및 IDE 설명](/ko/claude-code/web-and-desktop/)[Claude Code가 사용하는 모델과 변경 방법](/ko/claude-code/models/)[Claude Code 오류와 해결 방법](/ko/claude-code/errors/)[Claude Code는 오픈 소스인가요?](/ko/claude-code/open-source/)[Claude Code 튜토리얼: 첫 실전 세션](/ko/claude-code/tutorial/)[학생을 위한 Claude: Claude Code, API 및 교육 분야에서 실제로 제공되는 혜택](/ko/claude-code/for-students/)[QA 자동화에 Claude Code를 사용하는 방법](/ko/claude-code/qa-automation/)[Claude Code와 Cursor 비교: 어떤 도구를 언제 선택하고, 둘 다 어떻게 사용할까](/ko/claude-code/vs-cursor/)[Claude Code vs Codex vs OpenCode: 터미널 에이전트 비교](/ko/claude-code/vs-codex/)[Claude Code 하위 에이전트: 작동 방식, 정의 방법, 에이전트 팀](/ko/claude-code/subagents/)[Claude Code 훅: 에이전트 동작에 대한 결정론적 제어](/ko/claude-code/hooks/)[Claude Code 생태계: 라우터, 프레임워크, 플러그인과 이를 모아 둔 목록](/ko/claude-code/ecosystem/)[VS Code에서 Claude Code 사용하기: 확장 프로그램, 터미널 사용 방식, 오류](/ko/claude-code/vscode/)[Claude Code에서 OpenRouter를 사용하는 방법과 사용하지 않는 편이 나은 경우](/ko/claude-code/openrouter/)[Claude 요청 한도 오류: "API 오류: 요청 한도 도달"의 의미와 해결 방법](/ko/claude-code/rate-limits/)[Claude Code 사용법: 설치부터 일상적인 사용까지](/claude-code/zh/)