MCP-Atlas: 実在のMCPサーバを用いたツール使用能力の大規模ベンチマーク

MCP-Atlasは、AIエージェントが現実世界のタスクを完了するためにツールをどの程度適切に使用できるかを評価します。36のModel Context Protocol（MCP）サーバを再現可能なDockerサンドボックス上で動作させ、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、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. 1タスクのスモークテスト（新しいターミナル）

期待される回答: "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）。正解ファイルはHuggingFaceデータセットをCSVにエクスポートしたもの（列: TASK、PROMPT、GTFA_CLAIMS）、またはローカルで実行した場合は同じ--inputCSVです。出力: 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プロバイダを参照してください。

スループットの拡張

1つのサンドボックスで同時タスクを快適に処理でき、複数の評価を並行して実行することも可能です。 エージェントループはI/Oバウンドです。各タスクの時間のほとんどはツール呼び出しではなくモデルの応答待ちに費やされるため、通常の同時実行数では1つのサンドボックスで十分余裕があります。必要に応じて--concurrencyを上げるか、複数の実行を起動してください。サンドボックス自体がボトルネックになる場合（非常に高い同時実行数、または一部のMCPサーバが負荷で劣化するツール主体のワークロード）にのみ、以下のスケールアウトオプションを検討してください:

独立したスタックにシャーディング（最もシンプル）。 複数のサンドボックス＋ハーネスペアを異なるポートで実行し、run_eval.pyに各スタックのタスクスライスを指定し、出力CSVを連結します。各タスクは1つのスタックでエンドツーエンドに実行されるため、タスク内の状態（ファイルシステム、メモリ、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エンドポイントで動作します。

サンドボックスを追加する際のルール: 1つのタスクのすべてのツール呼び出しは同じサンドボックスで行ってください。レプリカ間での呼び出しごとの負荷分散は、ステートフルなツール（ファイルシステム、メモリ、git、MongoDB）を壊します。これらのツールはタスク内で一貫したビューを前提としているためです。

含まれるもの

• エージェントハーネス（services/agent-harness/、TypeScript） — マルチターンエージェントループ。MCP_SANDBOX_URL経由でサンドボックスと通信します。

• エージェント環境（services/agent-environment/、Python） — Docker化されたサンドボックス。36のMCPサーバをHTTP経由で提供します。

• スコアリング（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}
}