Claude는 Model Context Protocol(MCP)을 기본 지원하여 데이터베이스, 코드 실행기, API, 사용자 지정 서버 등 외부 도구를 워크플로에 직접 연결할 수 있도록 합니다. 터미널에서 Claude Code를 사용하든, 머신에서 Claude Desktop을 사용하든, MCP 구성은 프로토콜 수준에서 동일한 방식으로 작동하며, 서버 등록 방법에 몇 가지 차이점이 있습니다. 이 가이드에서는 두 가지 경로를 다룹니다: Claude Code용 claude mcp add CLI 명령어와 Claude Desktop용 JSON 설정 파일, 그리고 도구 사용 추론과 샌드박스 실행이 어떻게 적용되는지도 함께 설명합니다.
Claude에서 MCP의 역할
MCP는 Anthropic의 개방형 표준으로, 언어 모델이 외부 도구를 호출하는 통일된 방법을 제공합니다. MCP 이전에는 모든 AI 앱이 사용하려는 각 도구에 대해 개별적인 글루 코드가 필요했습니다. MCP를 사용하면 모든 호환 서버가 표준 검색 및 호출 프로토콜을 통해 기능을 노출하며, Claude를 포함한 모든 호환 호스트가 도구별 통합 작업 없이 이를 사용할 수 있습니다.
실제로는: Claude에 MCP 서버를 추가하면 Claude 호스트에게 도구 세트를 어디에서 찾을 수 있는지 알려주는 것입니다. 그러면 Claude는 세션 중에 해당 도구를 나열하고 작업에 필요할 때 이름으로 호출할 수 있습니다. 서버는 실행을 처리하고, Claude는 언제, 어떻게 호출할지에 대한 추론을 처리합니다.
MCP를 뒷받침하는 세 가지 핵심 개념은 다음과 같습니다:
| 개념 | 설명 | 예시 |
|---|---|---|
| 도구 | 서버가 노출하는 호출 가능한 함수 | run_python, query_db, list_models |
| 리소스 | 서버가 컨텍스트로 제공하는 읽기 전용 데이터 | 파일, 데이터베이스 행, 데이터셋 |
| 프롬프트 | 서버에 번들된 사전 구축된 명령 템플릿 | 시스템 수준 작업 설명 |
대부분의 개발자에게 가장 중요한 것은 도구입니다. 리소스와 프롬프트는 더 구조화된 에이전트 파이프라인을 구축할 때 관련성이 높아집니다.
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 파일에 저장합니다. 위치는 OS에 따라 다릅니다:
- 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 대신 Server-Sent Events(SSE) 전송을 사용하는 원격 서버의 경우 구성 형태가 약간 다릅니다:
{
"mcpServers": {
"remote-tools": {
"url": "https://your-mcp-server.example.com/sse"
}
}
}
일부 원격 서버에는 인증이 필요합니다. 서버에서 요구하는 경우 헤더 필드에 베어러 토큰을 전달합니다:
{
"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 스키마 설명 목록이 생성됩니다. 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 서버 구축에 대한 단계별 가이드는 Build a Remote Code Execution MCP Server with Novita Sandbox and mcp-use Library를 참조하십시오.
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 서버 구축에 대한 실제 예제는 How to Build Your First MCP Server with Novita AI를 참조하십시오.
일반적인 문제 및 해결 방법
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 스키마와 일치해야 합니다. 도구의 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는 원격, 공유 또는 프로덕션 배포에 더 적합합니다.
