Claude MCP 구성은 Claude Code 또는 Claude Desktop을 데이터베이스, 코드 실행기, API, 사용자 정의 서버와 같은 외부 도구에 연결합니다. Claude Code의 경우 claude mcp add를 사용하고, Claude Desktop의 경우 JSON 구성을 편집한 후 전송, 범위 및 도구 목록을 확인하세요. 이 가이드에서는 두 가지 설정 경로, 일반적인 실패 사례, 도구 사용 추론 및 샌드박스 실행을 다룹니다.
Claude MCP 구성 작동 방식
MCP는 Anthropic의 오픈 표준으로, 언어 모델이 외부 도구를 호출하는 통일된 방법을 제공합니다. MCP 이전에는 모든 AI 앱이 사용하려는 각 도구에 대해 맞춤형 글루 코드가 필요했습니다. MCP를 사용하면 모든 호환 가능한 서버가 표준 검색 및 호출 프로토콜을 통해 기능을 노출하며, Claude를 포함한 모든 호환 가능한 호스트는 도구별 통합 작업 없이 이를 사용할 수 있습니다.
실제로 말하자면: Claude에 MCP 서버를 추가하면 Claude 호스트에 도구 세트를 찾을 수 있는 위치를 알려주는 것입니다. 그러면 Claude는 세션 중에 해당 도구를 나열하고 작업이 필요할 때 이름으로 호출할 수 있습니다. 서버는 실행을 담당하고, Claude는 언제, 어떻게 호출할지에 대한 추론을 담당합니다.
MCP를 뒷받침하는 세 가지 핵심 개념은 다음과 같습니다:
| 개념 | 설명 | 예시 |
|---|---|---|
| 도구(Tool) | 서버가 노출하는 호출 가능한 함수 | run_python, query_db, list_models |
| 리소스(Resource) | 서버가 컨텍스트로 제공하는 읽기 전용 데이터 | 파일, 데이터베이스 행, 데이터셋 |
| 프롬프트(Prompt) | 서버에 번들로 제공되는 사전 구축된 명령 템플릿 | 시스템 수준 작업 설명 |
대부분의 개발자에게 가장 중요한 것은 도구입니다. 리소스와 프롬프트는 보다 구조화된 에이전트 파이프라인을 구축할 때 관련성이 높아집니다.
Claude Code에서 MCP 서버 추가하기
Claude Code는 claude mcp 하위 명령어 그룹을 통해 MCP 관리를 제공합니다. 구성 파일을 수동으로 건드릴 필요 없이 서버를 추가, 제거 및 나열할 수 있습니다.
claude mcp add — 기본 형식
claude mcp add <name> <command> [args...]
예를 들어, 로컬 Python MCP 서버를 추가하려면:
claude mcp add my-tools python /path/to/mcp_server.py
이렇게 하면 my-tools라는 이름의 서버가 등록되며, stdio 전송을 사용하여 python /path/to/mcp_server.py를 실행합니다. Claude Code는 세션을 시작할 때 프로세스를 실행하고 세션이 지속되는 동안 유지합니다.
환경 변수 전달하기
많은 MCP 서버에는 API 키나 엔드포인트 URL이 필요합니다. 등록 시 --env를 사용하여 전달하세요:
claude mcp add my-tools python /path/to/mcp_server.py \
--env API_KEY=your_key_here \
--env BASE_URL=https://api.example.com
값은 Claude Code의 구성에 저장되며 시작 시 서버 프로세스에 주입됩니다. 서버 명령어 자체에 비밀 정보를 하드코딩하지 마세요.
claude mcp add json — JSON 사양으로 등록하기
이미 JSON으로 작성된 서버 사양이 있는 경우(팀 간에 구성을 공유할 때 일반적), 직접 파이프로 전달할 수 있습니다:
echo '{
"command": "python",
"args": ["/path/to/mcp_server.py"],
"env": {
"API_KEY": "your_key"
}
}' | claude mcp add my-tools --json
또는 파일을 전달합니다:
claude mcp add my-tools --json < server-spec.json
이는 위치 인수 형식과 동일하지만 버전 관리 및 공유가 가능한 단일 구성 아티팩트를 제공합니다.
서버 목록 보기 및 제거하기
# 등록된 모든 서버 보기
claude mcp list
# 서버 제거
claude mcp remove my-tools
범위: 프로젝트 vs 사용자
기본적으로 claude mcp add는 서버를 사용자 수준 구성에 등록하여 모든 Claude Code 세션에서 사용할 수 있게 합니다. 현재 프로젝트에만 등록하려면(.claude/settings.json에 저장) --scope project를 추가하세요:
claude mcp add my-tools python /path/to/mcp_server.py --scope project
프로젝트 범위 서버는 다른 프로젝트에 다른 도구가 필요하고 구성을 격리된 상태로 유지하려는 경우 유용합니다.
claude mcp serve — Claude Code를 MCP 서버로 노출하기
반대 방향도 작동합니다. claude mcp serve는 Claude Code 자체를 MCP 서버로 시작하여 다른 MCP 호스트가 연결하여 도구를 사용할 수 있게 합니다:
claude mcp serve
이는 다른 호스트가 도구 호출을 오케스트레이션하는 더 큰 에이전트 파이프라인에 Claude Code 기능을 구성하려는 경우 유용합니다.
Claude Desktop MCP 서버 구성
Claude Desktop은 MCP 서버 구성을 JSON 파일에 저장합니다. 위치는 운영 체제에 따라 다릅니다:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
파일이 없으면 생성하세요. 구조는 다음과 같습니다:
{
"mcpServers": {
"my-tools": {
"command": "python",
"args": ["/path/to/mcp_server.py"],
"env": {
"API_KEY": "your_key_here"
}
}
}
}
mcpServers 아래의 각 키는 Claude가 식별에 사용할 서버 이름입니다. 필요한 만큼 많은 서버를 등록할 수 있습니다. Claude Desktop은 시작 시 모두 로드합니다.
파일을 편집한 후 변경 사항을 적용하려면 Claude Desktop을 다시 시작하세요. MCP 도구가 성공적으로 로드되면 채팅 입력 영역에 망치 아이콘이 표시됩니다.
SSE를 통한 원격 MCP 서버 추가
stdio 대신 SSE(Server-Sent Events) 전송을 사용하는 원격 서버의 경우 구성 형태가 약간 다릅니다:
{
"mcpServers": {
"remote-tools": {
"url": "https://your-mcp-server.example.com/sse"
}
}
}
일부 원격 서버는 인증이 필요합니다. 서버에서 예상하는 경우 headers 필드에 bearer 토큰을 전달하세요:
{
"mcpServers": {
"remote-tools": {
"url": "https://your-mcp-server.example.com/sse",
"headers": {
"Authorization": "Bearer your_token_here"
}
}
}
}
MCP 전송 유형: stdio vs SSE
MCP 서버는 두 가지 전송 메커니즘 중 하나를 통해 Claude 호스트와 통신합니다:
stdio — 서버가 동일한 머신에서 서브프로세스로 실행됩니다. 호스트가 프로세스를 실행하고 표준 입출력을 통해 JSON-RPC 메시지를 읽고 씁니다. 이는 로컬 서버의 기본값이며 설정이 가장 간단합니다.
SSE(Server-Sent Events) — 서버가 원격으로 실행되고 HTTP 엔드포인트를 노출합니다. 호스트가 URL에 연결하고 스트림으로 도구 응답을 받습니다. 이는 머신 간에 작동하며 공유 팀 인프라나 호스팅된 도구 서비스에 적합한 선택입니다.
대부분의 개별 개발자가 시작할 때는 stdio가 더 쉽습니다. 네트워킹이 필요 없고 서버 프로세스가 자동으로 관리됩니다. SSE는 팀이 단일 MCP 서버를 공유하거나 도구 자체가 특정 네트워크 환경에서 실행되어야 할 때 유용합니다.
Claude가 MCP 도구를 추론하는 방식
세션이 시작되고 MCP 서버가 등록되면 Claude는 각 서버에 사용 가능한 도구를 쿼리합니다. 이렇게 하면 도구 이름과 JSON Schema 설명 목록이 생성됩니다. Claude는 추측성으로 도구를 호출하지 않습니다. 도구 설명이 수행하는 작업에 따라 대화나 작업이 필요할 때만 도구를 호출합니다.
도구 호출 흐름은 다음과 같이 작동합니다:
- 사용자가 메시지나 작업을 보냅니다.
- Claude가 등록된 도구 중 도움이 될 수 있는 것이 있는지 평가합니다.
- 있다면, Claude가 적절한 인수로 도구 호출을 구성합니다.
- MCP 호스트가 올바른 서버로 호출을 보냅니다.
- 서버가 실행되고 결과를 반환합니다.
- Claude가 결과를 추론에 통합하고 계속 진행합니다.
이 루프는 단일 턴에서 여러 번 발생할 수 있습니다. Claude는 도구 호출을 체이닝하고, 한 도구의 결과를 다른 도구의 인수에 사용하며, 동일한 세션에서 여러 서버의 결과를 집계할 수 있습니다.
도구 설명의 품질이 여기서 매우 중요합니다. 모호한 설명은 호출 누락이나 잘못된 호출로 이어집니다. 도구가 무엇을 하는지, 인수의 의미는 무엇인지, 무엇을 반환하는지 포함하는 정확한 설명은 Claude가 추측 없이 정확하게 호출을 라우팅할 수 있게 합니다.
샌드박스에서 도구 실행하기
MCP 도구가 코드(Python 스크립트, 셸 명령, 파일 작업)를 실행할 때 로컬 머신에서 실행하면 격리 문제가 발생합니다. 파일 시스템 액세스, 프로세스 생성, 네트워크 호출 기능이 있는 도구는 잘못 작동하거나 예상치 못한 경로로 프롬프트될 경우 광범위한 영향을 미칠 수 있습니다.
Novita AI Agent Sandbox는 도구 실행을 위한 격리된 클라우드 환경을 제공하여 이 문제를 해결합니다. MCP 서버를 로컬에서 실행하는 대신 샌드박스 인스턴스 내부에 배포합니다. 샌드박스는 자체 파일 시스템, 네트워크 범위 및 리소스 제한을 갖습니다. 에이전트는 해당 경계 내에서 파일을 쓰고, 코드를 실행하고, 내부 API를 호출할 수 있으며 호스트 머신에는 영향을 미치지 않습니다.
샌드박스 내부에서 실행되는 MCP 서버는 SSE 전송을 통해 도구를 노출하고 Claude는 원격으로 연결합니다. 따라서 Claude의 관점에서 통합은 동일합니다. 차이점은 전적으로 도구가 실제로 실행되는 환경에 있습니다.
MCP 배포를 위한 Novita Sandbox의 주요 특징:
- 빠른 시작: 인스턴스가 약 200ms 이내에 실행되어 도구 왕복 지연 시간을 낮게 유지합니다.
- 초 단위 과금: 유휴 예약이 아닌 활성 실행 시간에 대해서만 비용을 지불합니다.
- 격리된 파일시스템: 각 샌드박스 인스턴스는 별도의 작업 공간을 가지므로 세션 간 데이터 유출을 방지합니다.
- 구성 가능한 네트워크 정책: 도구가 도달할 수 있는 외부 서비스를 제어합니다.
Novita Sandbox를 기반으로 한 MCP 서버 구축에 대한 단계별 가이드는 Novita Sandbox 및 mcp-use 라이브러리로 원격 코드 실행 MCP 서버 구축하기를 참조하세요.
MCP 도구 사용 추론에 Novita LLM API 사용하기
Claude 자체 모델이 도구 사용을 기본적으로 처리하지만, 비용, 지연 시간 또는 특화 이유로 일부 MCP 도구 사용 추론을 다른 모델을 통해 라우팅하고 싶을 수 있습니다. Novita LLM API는 함수 호출 및 구조화된 도구 호출을 지원하는 모델에 액세스할 수 있는 OpenAI 호환 엔드포인트를 제공합니다.
이는 MCP 아키텍처에서 두 가지 방식으로 활용됩니다:
1. 사용자 정의 MCP 호스트 뒤의 추론 모델: 자체 MCP 호스트를 구축하는 경우(Claude Code 또는 Claude Desktop을 사용하지 않는 경우), Novita LLM API를 사용하여 모델 계층을 구동할 수 있습니다. 호스트는 도구 목록과 대화와 함께 Novita API를 호출하고, 모델은 도구 호출 지침을 반환하며, 호스트는 이를 MCP 서버로 전달합니다.
import openai
client = openai.OpenAI(
base_url="https://api.novita.ai/v3/openai",
api_key="your_novita_api_key",
)
response = client.chat.completions.create(
model="meta-llama/llama-3.3-70b-instruct",
messages=[{"role": "user", "content": "사용 가능한 도구를 나열하고 빠른 테스트를 실행해 주세요"}],
tools=[
{
"type": "function",
"function": {
"name": "list_models",
"description": "API에서 사용 가능한 모든 모델을 나열합니다.",
"parameters": {"type": "object", "properties": {}},
}
}
],
tool_choice="auto",
)
2. MCP 도구 자체 내부의 LLM: MCP 도구는 내부적으로 Novita LLM API를 사용할 수 있습니다. 예를 들어 요약 도구, 분류 도구, 코드를 생성하는 도구 등이 있습니다. 도구는 에이전트로부터 입력을 받아 Novita API를 호출하고 결과를 반환합니다. 이렇게 하면 모델 추론 비용이 기본 에이전트 모델 비용과 분리되고 각 하위 작업에 적합한 모델을 선택할 수 있습니다.
Novita API를 호출하는 MCP 서버 구축에 대한 실제 예제는 Novita AI로 첫 번째 MCP 서버 구축하는 방법을 참조하세요.
일반적인 문제 및 해결 방법
서버가 Claude Desktop에 나타나지 않음
가장 일반적인 원인은 claude_desktop_config.json의 JSON 구문 오류입니다. 저장하기 전에 JSON 검증기를 사용하세요. 후행 쉼표만 있어도 파일 로딩이 실패할 수 있습니다. 편집 후에는 항상 Claude Desktop을 다시 시작하세요.
claude mcp add 명령을 찾을 수 없음
이는 Claude Code가 설치되지 않았거나 PATH에 없음을 의미합니다. npm install -g @anthropic-ai/claude-code를 통해 Claude Code를 설치하고 claude --version으로 확인하세요.
도구가 나열되지만 호출되지 않음
Claude는 도구가 현재 작업과 관련이 있다고 판단될 때만 도구를 호출합니다. 도구 설명이 너무 모호하면 Claude가 도구를 선택하지 않습니다. 도구의 기능, 사용 시기, 입력 및 출력 형태에 대한 구체적인 내용을 추가하세요.
서버가 실행 직후 종료됨
서버 명령이 올바른지, 필요한 모든 환경 변수가 설정되었는지 확인하세요. 터미널에서 명령을 직접 실행하여 실제 오류 출력을 확인하세요. Claude Code는 일부 구성에서 서브프로세스 stderr를 숨길 수 있습니다.
SSE 연결 거부됨
서버 URL이 Claude를 실행 중인 머신에서 연결 가능한지, 서버가 예상 포트에서 실제로 수신 중인지, 필요한 인증 헤더가 올바르게 구성되었는지 확인하세요.
도구 호출이 유효성 검사 오류로 실패함
Claude가 전달하는 인수는 도구가 선언한 JSON Schema와 일치해야 합니다. 도구의 inputSchema 정의를 검토하세요. 필수 필드가 누락되었거나 유형이 일치하지 않으면 서버가 호출을 거부합니다. Claude는 스키마를 기반으로 인수를 구성하므로 불완전한 스키마는 불완전한 호출로 이어집니다.
자주 묻는 질문(FAQ)
Claude Code가 MCP를 지원하나요?
네. Claude Code는 claude mcp 하위 명령어를 통해 기본 MCP를 지원합니다. claude mcp add를 사용하여 서버를 등록하고, claude mcp list로 등록된 항목을 확인하고, claude mcp remove로 등록을 해제합니다. 전체 명령어 참조는 claude mcp --help를 실행하세요.
Claude Code에 MCP 서버를 어떻게 추가하나요?
stdio 서버의 경우 claude mcp add <name> <command> [args...]를 실행하거나, --json을 사용하여 JSON 사양을 전달하세요. 프로젝트 범위 등록의 경우 --scope project를 추가하세요. 추가한 후 새 Claude Code 세션을 시작하면 도구를 즉시 사용할 수 있습니다.
claude mcp serve란 무엇인가요?
claude mcp serve는 Claude Code 자체를 MCP 서버로 실행하여 MCP 프로토콜을 통해 기능을 노출합니다. 그러면 다른 MCP 호스트가 Claude Code에 연결하여 도구 소스로 사용할 수 있습니다. 이는 Claude가 여러 구성 요소 중 하나인 멀티 에이전트 시스템을 구축할 때 유용합니다.
동일한 MCP 서버를 Claude Code와 Claude Desktop에서 모두 사용할 수 있나요?
네. 서버 자체는 어떤 호스트가 연결하는지 상관하지 않습니다. stdio 서버의 경우 Claude Code(claude mcp add를 통해)와 Claude Desktop(claude_desktop_config.json을 통해) 모두 동일한 명령을 실행할 수 있습니다. SSE 서버의 경우 URL에 도달할 수 있는 모든 호스트가 연결할 수 있습니다.
Claude는 어떤 MCP 도구를 호출해야 하는지 어떻게 알 수 있나요?
세션 시작 시 Claude는 등록된 모든 서버에 도구 목록을 쿼리합니다. 각 도구에는 이름과 설명이 있습니다. 작업을 처리할 때 Claude는 설명이 필요한 것과 일치하는지 여부에 따라 도구를 선택합니다. 명확한 사용 사례가 포함된 잘 작성된 설명은 정확한 도구 선택으로 이어지고, 모호한 설명은 호출 누락이나 잘못된 호출로 이어집니다.
등록할 수 있는 MCP 서버 수에 제한이 있나요?
MCP 사양은 하드 제한을 두지 않으며, Claude Code나 Claude Desktop도 마찬가지입니다. 실제로 수백 개의 도구가 있는 수십 개의 서버는 세션 시작 속도를 늦추고(도구 검색이 시작 시 실행됨) Claude의 도구 선택에 잡음을 추가할 수 있습니다. 도구 세트는 특정 프로젝트나 세션에 실제로 필요한 것에 집중하세요.
stdio와 SSE 전송의 차이점은 무엇인가요?
Stdio는 서버를 로컬 서브프로세스로 실행하며 호스트는 stdin/stdout을 통해 통신합니다. SSE는 원격 HTTP 엔드포인트에 연결하고 스트림으로 응답을 받습니다. Stdio는 로컬 개발에 더 간단하고, SSE는 원격, 공유 또는 프로덕션 배포에 더 적합합니다.
