MCP-Atlas：一个用于评估工具使用能力的大规模基准测试，基于真实 MCP 服务器

MCP-Atlas 评估 AI 代理使用工具完成真实世界任务的能力，涵盖 36 个模型上下文协议（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、通过 LiteLLM 的 Anthropic、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 分配至少 8 GB（建议 10 GB 以上）内存。

选项 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 个任务的数据集；使用 --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）。

• 每次运行会在输出 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 作为裁判的声明覆盖率评分（默认裁判 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）——Docker 化沙箱，通过 HTTP 提供 36 个 MCP 服务器。

• 评分（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}
}