Claude Code MCP 서버 — claude mcp add, 원격 서버, PostHog MCP, .mcp.json (2026)

서버 추가

# 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로 계정 만들기

자주 묻는 질문

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 키 발급받기 무제한 요금제 보기

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

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

TLDR