MCP-Atlas: Ein groß angelegter Benchmark zur Bewertung der Werkzeugnutzungskompetenz mit echten MCP-Servern

MCP-Atlas bewertet, wie gut KI-Agenten Werkzeuge zur Erledigung realer Aufgaben einsetzen können, und zwar über 36 Model Context Protocol (MCP)-Server hinweg in einer reproduzierbaren Docker-Sandbox, bewertet mit einem LLM-as-Judge.

• Paper: arxiv.org/abs/2602.00933 (lokale Kopie)

• Bestenliste: scale.com/leaderboard/mcp_atlas

• Datensatz: huggingface.co/datasets/ScaleAI/MCP-Atlas

Überblick

• 36 echte MCP-Server aus den Bereichen Suche, Codeausführung, Datenbanken, APIs und Produktivitätstools – 20 benötigen keine Einrichtung, 11 erfordern API-Schlüssel und 5 erfordern API-Schlüssel plus Dateneinrichtung (siehe data_exports/README.md). Alle sind Open Source und versionsfestgelegt für Reproduzierbarkeit.

• 500 Aufgaben mit Ground-Truth-erwarteten Tool-Aufrufen und Antworten.

• LLM-as-Judge-Bewertung mit Berichterstattung über Bestehensquote und Abdeckung sowie aufgabenspezifischer Fehlermodus-Diagnose.

Serverdefinitionen befinden sich in mcp_server_template.json; eine vollständige Liste der 36 Server und 307 Tools finden Sie hier.

Related MCP server: Forage MCP Server

Schnellstart

Erfordert docker, jq und Python 3.10+.

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

1. Konfigurieren

cp env.template .env

Setzen Sie in .env:

• LLM_API_KEY – Schlüssel für das zu evaluierende Modell (durch Kommas getrennte Schlüssel werden pro Anfrage rotiert).

• LLM_BASE_URL – ein beliebiger, mit OpenAI Chat-Completions kompatibler Endpunkt (ein LiteLLM-Proxy, OpenAI, Anthropic via LiteLLM, Azure oder ein selbst gehosteter vLLM/TGI-Server).

• EVAL_LLM_API_KEY / EVAL_LLM_BASE_URL / EVAL_LLM_MODEL – optionale Judge-Einstellungen für Bewertung und Diagnose; fallen auf LLM_* zurück, wobei der Judge standardmäßig gemini/gemini-3.1-pro-preview verwendet.

• MCP_SANDBOX_URL – optional, standardmäßig http://localhost:1984.

Das Agent-Harness wurde in v2.0.0 von Python nach TypeScript umgeschrieben – siehe CHANGELOG.md.

2. Starten der MCP-Server

Weisen Sie Docker mindestens 8 GB (10 GB+ empfohlen) zu.

Option A – vorgefertigtes Image (empfohlen):

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

Option B – aus dem Quellcode erstellen (nur, wenn Sie das Serverset, die festgelegten Versionen oder die eingebetteten Daten ändern):

make build && make run-docker

Keines der beiden backt API-Schlüssel ein – beide injizieren sie zur Laufzeit aus .env. Der Startvorgang dauert 1+ Minute; warten Sie auf Uvicorn running on http://0.0.0.0:1984. Die 20 schlüssellosen Server sind standardmäßig aktiviert; schlüsselgeschützte Server werden aktiviert, wenn ihre Schlüssel vorhanden sind. Überprüfen:

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

3. Starten des Agent-Harness (neues Terminal)

make install-harness
make run-harness

Startet das TypeScript-Harness auf Port 3001 und macht /v2/mcp_eval/run_agent verfügbar – die Multi-Turn-Agent-Schleife, die das Modell gegen die Sandbox ausführt, bis es fertig ist oder ein Limit erreicht.

4. Rauchtest einer Aufgabe (neues Terminal)

Erwartete Antwort: "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. Ausführen der vollständigen Evaluierung

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

Ruft standardmäßig den 500-Aufgaben-Datensatz von HuggingFace ab; übergeben Sie --input tasks.csv für eine lokale CSV (Spalten TASK, PROMPT, ENABLED_TOOLS). Wiederholungsläufe überspringen bereits abgeschlossene task_ids, sodass ein unterbrochener Lauf durch erneutes Ausführen desselben Befehls fortgesetzt wird. Ausgabespalten: task_id, raw_conversation_history, response.

Bewahren Sie die Artefakte jedes Laufs zusammen auf, indem Sie --output in ein verzeichnispro-Lauf-Verzeichnis schreiben und die Schritte zur Bewertung/Diagnose auf dasselbe Verzeichnis ausrichten.

Konfiguration

Überschreiben Sie jeden Standard pro Lauf:

• --extra-llm-params legt Reasoning-/Anbieter-spezifische Optionen fest, z. B. --extra-llm-params '{"reasoning_effort": "high"}' (verwenden Sie den Schlüssel, den Ihr Anbieter erwartet; Standard ist der des Anbieters selbst).

• Zeitüberschreitungen für Harness-Anfragen sind über Umgebungsvariablen für langsame Modelle konfigurierbar: TOOL_CALL_TIMEOUT_MS (60000), LIST_TOOLS_TIMEOUT_MS (180000), LLM_TIMEOUT_MS (600000).

• Jeder Lauf schreibt eine run_config.json neben die Ausgabe-CSV; der Scorer bettet sie in coverage_stats_*.json ein, sodass jedes Ergebnis seiner Konfiguration zugeordnet werden kann.

6. Bewerten

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-Claim-Coverage-Bewertung (Standard-Judge gemini/gemini-3.1-pro-preview). Die Ground-Truth-Datei ist der in CSV exportierte HuggingFace-Datensatz (Spalten TASK, PROMPT, GTFA_CLAIMS) oder dieselbe --input-CSV, wenn Sie lokal ausgeführt haben. Ausgaben: scored_<model>.csv, coverage_stats_<model>_*.json (Bestehensquoten bei 0,50 und 0,75 Abdeckungsschwellen) und ein Abdeckungshistogramm. --concurrency passt sich automatisch pro Judge-Modell an.

6b. Fehler diagnostizieren (optional)

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

Klassifiziert jede fehlgeschlagene Aufgabe in einen von 11 Fehlermodi (4 Tool-Aufruf + 7 kognitive) über eine angereicherte Trajektorie und schreibt eine diagnosis_*.csv plus eine narrative Zusammenfassung auf Modellebene.

7. Ein weiteres Modell evaluieren

Ändern Sie LLM_API_KEY / LLM_BASE_URL in .env, starten Sie das Harness neu und führen Sie es mit einem anderen --model erneut aus. Siehe LiteLLM-Anbieter für Modellnamen.

Durchsatz skalieren

Eine einzelne Sandbox bewältigt gleichzeitige Aufgaben problemlos, und Sie können mehrere Evaluierungen parallel dagegen ausführen. Die Agent-Schleife ist I/O-gebunden – die meiste Zeit jeder Aufgabe wird mit dem Warten auf das Modell verbracht, nicht mit dem Aufrufen von Tools –, sodass eine Sandbox bei typischer Parallelität deutlich unter der Kapazitätsgrenze bleibt. Erhöhen Sie --concurrency oder starten Sie bei Bedarf mehrere Läufe; greifen Sie nur dann auf die unten stehenden Skalierungsoptionen zurück, wenn die Sandbox selbst zum Engpass wird (sehr hohe Parallelität oder Tool-lastige Arbeitslasten, bei denen einige MCP-Server unter Last nachlassen):

Aufteilen auf unabhängige Stacks (am einfachsten). Führen Sie mehrere Sandbox- + Harness-Paare auf verschiedenen Ports aus, weisen Sie run_eval.py für jedes einen Teil der Aufgaben zu und verketten Sie dann die Ausgabe-CSVs. Jede Aufgabe wird Ende-zu-Ende auf einem Stack ausgeführt, sodass der Zustand innerhalb der Aufgabe (Dateisystem, Speicher, Git) konsistent bleibt. Das .env des Harness überschreibt keine bereits in der Umgebung gesetzten Variablen, sodass pro-Stack-PORT / MCP_SANDBOX_URL-Überschreibungen einfach funktionieren:

# 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>"

Auf einen Orchestrator ausrichten (skaliert am weitesten). Da das Harness die Sandbox ausschließlich über MCP_SANDBOX_URL erreicht, können Sie es auf einen Dienst ausrichten, der eine flüchtige Sandbox pro Aufgabe bereitstellt – keine Harness-Änderungen erforderlich; jeder HTTP-Endpunkt, der die Agent-Umgebungs-API implementiert, funktioniert.

Eine Regel beim Hinzufügen von Sandboxes: Halten Sie alle Tool-Aufrufe einer Aufgabe auf derselben Sandbox. Eine Lastverteilung pro Aufruf über Replikate hinweg unterbricht zustandsbehaftete Tools (Dateisystem, Speicher, Git, MongoDB), die eine konsistente Sicht innerhalb einer Aufgabe voraussetzen.

Enthaltene Komponenten

• Agent-Harness (services/agent-harness/, TypeScript) – Multi-Turn-Agent-Schleife, kommuniziert mit der Sandbox über MCP_SANDBOX_URL.

• Agent-Umgebung (services/agent-environment/, Python) – Dockerisierte Sandbox, die die 36 MCP-Server über HTTP bereitstellt.

• Bewertung (services/scoring/, Python) – LLM-as-Judge-Claim-Coverage-Bewertung.

• Diagnose (services/diagnostics/, Python) – Fehlermodus-Klassifizierung über eine 11-Modus-Taxonomie.

Zitation

Wenn Sie MCP-Atlas in Ihrer Forschung verwenden, zitieren Sie bitte:

@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}
}