MCP-Atlas: Крупномасштабный бенчмарк для оценки компетенций использования инструментов с реальными MCP-серверами

MCP-Atlas оценивает, насколько хорошо AI-агенты используют инструменты для выполнения реальных задач, на 36 серверах Model Context Protocol (MCP) в воспроизводимой Docker-песочнице, с оценкой с помощью LLM-судьи.

• Статья: 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-судьи, сообщающая о проценте прохождения и покрытии, а также о диагностике режимов сбоев для каждой задачи.

Определения серверов находятся в 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 через 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.

Инфраструктура агента была переписана с Python на TypeScript в версии v2.0.0 — см. CHANGELOG.md.

2. Запуск MCP-серверов

Выделите Docker не менее 8 ГБ (рекомендуется 10+ ГБ).

Вариант 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

По умолчанию загружает набор данных из 500 задач с HuggingFace; передайте --input tasks.csv для локального 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).

• Каждый запуск записывает run_config.json рядом с выходным CSV-файлом; оценщик встраивает его в 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-судьи (судья по умолчанию gemini/gemini-3.1-pro-preview). Файл с эталонными данными — это набор данных HuggingFace, экспортированный в CSV (столбцы TASK, PROMPT, GTFA_CLAIMS), или тот же CSV-файл --input, если вы запускали локально. Выводит 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. Оценка другой модели

Измените LLM_API_KEY / LLM_BASE_URL в .env, перезапустите инфраструктуру и повторно запустите с другим --model. См. провайдеры LiteLLM для названий моделей.

Масштабирование пропускной способности

Одна песочница легко справляется с параллельными задачами, и вы можете запускать несколько оценок параллельно против нее. Цикл агента связан с вводом-выводом — большую часть времени каждой задачи занимает ожидание модели, а не вызов инструментов, поэтому одна песочница остается далеко не загруженной при типичной параллельности. Увеличьте --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, вы можете направить ее на сервис, который предоставляет эфемерную песочницу для каждой задачи — без изменений в инфраструктуре; любая конечная точка HTTP, реализующая API среды агента, подходит.

Одно правило при добавлении песочниц: все вызовы инструментов одной задачи должны выполняться в одной песочнице. Балансировка нагрузки по вызовам между репликами нарушает работу инструментов с состоянием (файловая система, память, git, MongoDB), которые предполагают согласованное представление в рамках задачи.

Что включено

• Инфраструктура агента (services/agent-harness/, TypeScript) — многократный цикл агента, взаимодействует с песочницей через MCP_SANDBOX_URL.

• Среда агента (services/agent-environment/, Python) — Docker-песочница, предоставляющая 36 MCP-серверов через HTTP.

• Оценка (services/scoring/, Python) — оценка покрытия утверждений с помощью LLM-судьи.

• Диагностика (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}
}