MCP-Atlas: 실제 MCP 서버를 활용한 도구 사용 역량 평가를 위한 대규모 벤치마크

MCP-Atlas는 AI 에이전트가 실제 작업을 완료하기 위해 도구를 얼마나 잘 사용하는지 평가합니다. 재현 가능한 Docker 샌드박스 환경에서 36개의 MCP(Model Context Protocol) 서버를 대상으로 LLM-as-judge 방식으로 점수를 산출합니다.

• 논문: arxiv.org/abs/2602.00933 (로컬 복사본)

• 리더보드: scale.com/leaderboard/mcp_atlas

• 데이터셋: huggingface.co/datasets/ScaleAI/MCP-Atlas

개요

• 36개의 실제 MCP 서버 — 검색, 코드 실행, 데이터베이스, API, 생산성 도구를 포함하며, 20개는 설정이 필요 없고, 11개는 API 키가 필요하며, 5개는 API 키와 데이터 설정이 필요합니다(data_exports/README.md 참조). 모든 서버는 오픈소스이며 재현 가능성을 위해 버전이 고정되어 있습니다.

• 500개의 작업 — 정답 예상 도구 호출과 답변이 포함되어 있습니다.

• LLM-as-judge 점수 산정 — 통과율과 커버리지를 보고하며, 작업별 실패 모드 진단을 제공합니다.

서버 정의는 mcp_server_template.json에 있으며, 36개 서버와 307개 도구의 전체 목록은 여기에서 확인할 수 있습니다.

Related MCP server: Forage MCP Server

빠른 시작

docker, jq, Python 3.10+이 필요합니다.

git clone git@github.com:scaleapi/mcp-atlas.git && cd mcp-atlas

1. 설정

cp env.template .env

.env 파일에 다음을 설정합니다:

• LLM_API_KEY — 평가 대상 모델의 키입니다(쉼표로 구분된 키는 요청별로 순환됩니다).

• LLM_BASE_URL — OpenAI Chat-Completions 호환 엔드포인트(LiteLLM 프록시, OpenAI, Anthropic-via-LiteLLM, Azure, 또는 자체 호스팅 vLLM/TGI 서버)입니다.

• EVAL_LLM_API_KEY / EVAL_LLM_BASE_URL / EVAL_LLM_MODEL — 선택 사항으로, 점수 산정 및 진단을 위한 판정 모델 설정입니다. LLM_* 값을 대체하며, 판정 모델의 기본값은 gemini/gemini-3.1-pro-preview입니다.

• MCP_SANDBOX_URL — 선택 사항이며, 기본값은 http://localhost:1984입니다.

에이전트 하네스는 v2.0.0에서 Python에서 TypeScript로 재작성되었습니다. 자세한 내용은 CHANGELOG.md를 참조하세요.

2. MCP 서버 시작

Docker에 최소 8GB(10GB+ 권장)를 할당하세요.

옵션 A — 사전 빌드된 이미지(권장):

docker pull ghcr.io/scaleapi/mcp-atlas:1.2.7
docker tag ghcr.io/scaleapi/mcp-atlas:1.2.7 agent-environment:latest
make run-docker

옵션 B — 소스에서 빌드(서버 세트, 고정 버전, 내장 데이터를 수정하는 경우에만 해당):

make build && make run-docker

두 옵션 모두 API 키를 내장하지 않으며, 런타임에 .env에서 주입합니다. 시작하는 데 1분 이상 소요됩니다. Uvicorn running on http://0.0.0.0:1984 메시지를 기다리세요. 키가 필요 없는 20개 서버는 기본적으로 활성화되며, 키가 필요한 서버는 해당 키가 존재할 때 활성화됩니다. 확인:

curl -s http://localhost:1984/enabled-servers | jq -c

3. 에이전트 하네스 시작(새 터미널)

make install-harness
make run-harness

TypeScript 하네스를 포트 3001에서 시작하여 /v2/mcp_eval/run_agent를 노출합니다. 이는 모델을 샌드박스에 대해 실행하여 작업을 완료하거나 제한에 도달할 때까지 반복하는 다중 턴 에이전트 루프입니다.

4. 하나의 작업으로 간단 테스트(새 터미널)

예상 답변: "Customer".

curl -X POST http://localhost:3001/v2/mcp_eval/run_agent \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "What is the first word of the file at /data/Barber Shop.csv?"}],
    "enabledTools": ["filesystem_read_text_file"],
    "image": "ghcr.io/scaleapi/mcp-atlas:1.2.7"
  }' | jq

5. 전체 평가 실행

make install-python   # one-time: deps for run_eval, scoring, diagnostics
python run_eval.py --model "openai/gpt-4o" --output outputs.csv

기본적으로 HuggingFace에서 500개 작업 데이터셋을 가져옵니다. 로컬 CSV 파일을 사용하려면 --input tasks.csv를 전달하세요(TASK, PROMPT, ENABLED_TOOLS 열 필요). 재실행 시 이미 완료된 task_id는 건너뛰므로, 중단된 실행은 동일한 명령어를 다시 실행하여 재개할 수 있습니다. 출력 열: task_id, raw_conversation_history, response.

각 실행의 아티팩트를 함께 유지하려면 --output을 실행별 디렉토리로 지정하고, 점수 산정/진단 단계에서 동일한 디렉토리를 가리키세요.

설정

실행별 기본값 재정의:

• --extra-llm-params는 추론/공급자별 옵션을 설정합니다. 예: --extra-llm-params '{"reasoning_effort": "high"}' (공급자가 예상하는 키를 사용하세요. 기본값은 공급자 자체 설정입니다).

• 하네스 요청 제한 시간은 느린 모델을 위해 환경 변수로 설정 가능합니다: TOOL_CALL_TIMEOUT_MS (60000), LIST_TOOLS_TIMEOUT_MS (180000), LLM_TIMEOUT_MS (600000).

• 각 실행은 출력 CSV 옆에 run_config.json을 작성합니다. 점수 산정기는 이를 coverage_stats_*.json에 포함시켜 모든 결과가 해당 설정으로 추적 가능하도록 합니다.

6. 점수 산정

python services/scoring/score_claims.py \
  --groundtruth-file path/to/groundtruth.csv \
  --model-file outputs.csv \
  --model-name your-model \
  --output-dir results/your-model

LLM-as-judge 클레임 커버리지 점수 산정(기본 판정 모델 gemini/gemini-3.1-pro-preview). 정답 파일은 CSV로 내보낸 HuggingFace 데이터셋(TASK, PROMPT, GTFA_CLAIMS 열)이거나, 로컬에서 실행한 경우 동일한 --input CSV입니다. scored_<model>.csv, coverage_stats_<model>_*.json(0.50 및 0.75 커버리지 임계값에서의 통과율), 그리고 커버리지 히스토그램을 출력합니다. --concurrency는 판정 모델에 따라 자동 조정됩니다.

6b. 실패 진단(선택 사항)

python services/diagnostics/single_model_diagnostic.py --scored-file scored_<model>.csv --verbose

각 실패 작업을 11가지 실패 모드(4가지 도구 호출 + 7가지 인지) 중 하나로 분류하고, 강화된 궤적을 통해 diagnosis_*.csv와 모델 수준의 설명을 작성합니다.

7. 다른 모델 평가

.env에서 LLM_API_KEY / LLM_BASE_URL을 변경하고, 하네스를 다시 시작한 후 다른 --model로 재실행하세요. 모델 이름은 LiteLLM 공급자를 참조하세요.

처리량 확장

단일 샌드박스는 동시 작업을 무리 없이 처리하며, 여러 평가를 병렬로 실행할 수 있습니다. 에이전트 루프는 I/O 바운드입니다. 대부분의 작업 시간은 도구 호출이 아닌 모델 응답을 기다리는 데 소요되므로, 일반적인 동시성 수준에서 하나의 샌드박스는 용량에 여유가 있습니다. 필요에 따라 --concurrency를 높이거나 여러 실행을 시작하세요. 샌드박스 자체가 병목이 되는 경우(매우 높은 동시성, 또는 일부 MCP 서버가 부하에 따라 성능이 저하되는 도구 중심 워크로드)에만 아래의 확장 옵션을 사용하세요:

독립적인 스택으로 분할(가장 간단함). 여러 샌드박스 + 하네스 쌍을 다른 포트에서 실행하고, 각각에 대해 작업의 일부를 run_eval.py에 지정한 후 출력 CSV를 연결하세요. 각 작업은 하나의 스택에서 처음부터 끝까지 실행되므로, 작업 내 상태(파일 시스템, 메모리, git)는 일관성을 유지합니다. 하네스의 .env는 이미 환경에 설정된 변수를 재정의하지 않으므로, 스택별 PORT / MCP_SANDBOX_URL 재정의가 정상 작동합니다:

# Stack A — sandbox on 1984, harness on 3001
docker run -d -p 1984:1984 --env-file .env ghcr.io/scaleapi/mcp-atlas:1.2.7
PORT=3001 MCP_SANDBOX_URL=http://localhost:1984 make run-harness

# Stack B — sandbox on 1985, harness on 3002
docker run -d -p 1985:1984 --env-file .env ghcr.io/scaleapi/mcp-atlas:1.2.7
PORT=3002 MCP_SANDBOX_URL=http://localhost:1985 make run-harness

# Run each half of the dataset against its own harness, then concatenate
HARNESS_URL=http://localhost:3001 python run_eval.py --input tasks_part_a.csv --output out_a.csv --model "<model>"
HARNESS_URL=http://localhost:3002 python run_eval.py --input tasks_part_b.csv --output out_b.csv --model "<model>"

오케스트레이터를 가리키기(가장 확장성 높음). 하네스는 MCP_SANDBOX_URL을 통해서만 샌드박스에 접근하므로, 작업별로 임시 샌드박스를 프로비저닝하는 서비스를 가리킬 수 있습니다. 하네스 변경은 필요 없으며, 에이전트 환경 API를 구현하는 모든 HTTP 엔드포인트가 작동합니다.

샌드박스를 추가할 때의 한 가지 규칙: 한 작업의 모든 도구 호출은 동일한 샌드박스에서 유지하세요. 복제본 간의 호출별 로드 밸런싱은 상태 저장 도구(파일 시스템, 메모리, git, MongoDB)를 손상시킵니다. 이러한 도구는 작업 내에서 일관된 뷰를 가정합니다.

포함된 내용

• 에이전트 하네스 (services/agent-harness/, TypeScript) — 다중 턴 에이전트 루프, MCP_SANDBOX_URL을 통해 샌드박스와 통신합니다.

• 에이전트 환경 (services/agent-environment/, Python) — HTTP를 통해 36개의 MCP 서버를 제공하는 Docker화된 샌드박스입니다.

• 점수 산정 (services/scoring/, Python) — LLM-as-judge 클레임 커버리지 점수 산정입니다.

• 진단 (services/diagnostics/, Python) — 11가지 모드 분류 체계를 통한 실패 모드 분류입니다.

인용

연구에 MCP-Atlas를 사용하신다면 다음을 인용해 주세요:

@misc{bandi2026mcpatlas,
  title         = {MCP-Atlas: A Large-Scale Benchmark for Tool-Use Competency with Real MCP Servers},
  author        = {Bandi, Chaithanya and Dumitru, Razvan-Gabriel and Hertzberg, Ben and Agarwal, Divyansh and Boo, Geobio and Polakam, Tejas and Hassaan, Sami and Da, Jeff and Kim, HiJae and Gupta, Vipul and Sharma, Manasi and Park, Andrew and Dimakis, Martin and Hernandez Montoya, Ernesto Gabriel and Rambado, Dan and Salazar, Ivan and Cruz, Rafael and Rezaei, MohammadHossein and Rane, Chetan and Levin, Ben and Zhang, Daniel Yue and Kenstler, Brad and Liu, Bing},
  year          = {2026},
  eprint        = {2602.00933},
  archivePrefix = {arXiv},
  primaryClass  = {cs.SE},
  url           = {https://arxiv.org/abs/2602.00933}
}