MCP-Atlas: Un Benchmark a Gran Escala para la Competencia en el Uso de Herramientas con Servidores MCP Reales

MCP-Atlas evalúa qué tan bien los agentes de IA utilizan herramientas para completar tareas del mundo real, abarcando 36 servidores del Protocolo de Contexto de Modelo (MCP) en un entorno Docker reproducible, con puntuación mediante un LLM como juez.

• Artículo: arxiv.org/abs/2602.00933 (copia local)

• Tabla de clasificación: scale.com/leaderboard/mcp_atlas

• Conjunto de datos: huggingface.co/datasets/ScaleAI/MCP-Atlas

Resumen

• 36 servidores MCP reales que abarcan búsqueda, ejecución de código, bases de datos, APIs y herramientas de productividad — 20 no requieren configuración, 11 requieren claves API y 5 requieren claves API más configuración de datos (consulta data_exports/README.md). Todos son de código abierto y con versiones fijadas para garantizar la reproducibilidad.

• 500 tareas con llamadas a herramientas y respuestas esperadas como referencia.

• Puntuación mediante LLM como juez que reporta la tasa de aprobación y cobertura, además de diagnósticos por tarea sobre modos de fallo.

Las definiciones de los servidores están en mcp_server_template.json; una lista completa de los 36 servidores y 307 herramientas está aquí.

Related MCP server: Forage MCP Server

Inicio Rápido

Requiere docker, jq y Python 3.10+.

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

1. Configurar

cp env.template .env

Establece en .env:

• LLM_API_KEY — clave para el modelo bajo evaluación (las claves separadas por comas se rotan por solicitud).

• LLM_BASE_URL — cualquier endpoint compatible con OpenAI Chat-Completions (un proxy LiteLLM, OpenAI, Anthropic vía LiteLLM, Azure o un servidor vLLM/TGI autoalojado).

• EVAL_LLM_API_KEY / EVAL_LLM_BASE_URL / EVAL_LLM_MODEL — opcional configuraciones del juez para puntuación y diagnósticos; recurre a LLM_*, con el juez predeterminado gemini/gemini-3.1-pro-preview.

• MCP_SANDBOX_URL — opcional, por defecto http://localhost:1984.

El motor del agente fue reescrito de Python a TypeScript en v2.0.0 — consulta CHANGELOG.md.

2. Iniciar los servidores MCP

Asigna al menos 8 GB (se recomiendan 10 GB+) a Docker.

Opción A — imagen preconstruida (recomendada):

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

Opción B — compilar desde el código fuente (solo si modificas el conjunto de servidores, las versiones fijadas o los datos incorporados):

make build && make run-docker

Ninguna incorpora claves API — ambas las inyectan en tiempo de ejecución desde .env. El inicio toma 1+ minuto; espera a que aparezca Uvicorn running on http://0.0.0.0:1984. Los 20 servidores sin clave están habilitados por defecto; los servidores con clave se activan cuando sus claves están presentes. Verifica:

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

3. Iniciar el motor del agente (nueva terminal)

make install-harness
make run-harness

Inicia el motor TypeScript en el puerto 3001, exponiendo /v2/mcp_eval/run_agent — el bucle del agente de múltiples turnos que ejecuta el modelo contra el entorno aislado hasta que finaliza o alcanza un límite.

4. Probar una tarea (nueva terminal)

Respuesta esperada: "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. Ejecutar la evaluación completa

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

Obtiene el conjunto de datos de 500 tareas de HuggingFace por defecto; pasa --input tasks.csv para un CSV local (columnas TASK, PROMPT, ENABLED_TOOLS). Las reejecuciones omiten los task_id ya completados, por lo que una ejecución interrumpida se reanuda al volver a ejecutar el mismo comando. Columnas de salida: task_id, raw_conversation_history, response.

Mantén juntos los artefactos de cada ejecución escribiendo --output en un directorio por ejecución y apuntando los pasos de puntuación/diagnóstico al mismo directorio.

Configuración

Anula cualquier valor predeterminado por ejecución:

• --extra-llm-params establece opciones de razonamiento/proveedor específicas, ej. --extra-llm-params '{"reasoning_effort": "high"}' (usa la clave que tu proveedor espere; el valor predeterminado es el del propio proveedor).

• Los tiempos de espera de las solicitudes del motor se configuran mediante variables de entorno para modelos lentos: TOOL_CALL_TIMEOUT_MS (60000), LIST_TOOLS_TIMEOUT_MS (180000), LLM_TIMEOUT_MS (600000).

• Cada ejecución escribe un run_config.json junto al CSV de salida; el puntuador lo incrusta en coverage_stats_*.json para que cada resultado sea trazable hasta su configuración.

6. Puntuar

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

Puntuación de cobertura de afirmaciones mediante LLM como juez (juez predeterminado gemini/gemini-3.1-pro-preview). El archivo de referencia es el conjunto de datos de HuggingFace exportado a CSV (columnas TASK, PROMPT, GTFA_CLAIMS), o el mismo CSV --input si ejecutaste localmente. Genera scored_<model>.csv, coverage_stats_<model>_*.json (tasas de aprobación en umbrales de cobertura de 0.50 y 0.75) y un histograma de cobertura. --concurrency se ajusta automáticamente según el modelo juez.

6b. Diagnosticar fallos (opcional)

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

Clasifica cada tarea fallida en uno de 11 modos de fallo (4 de llamada a herramienta + 7 cognitivos) sobre una trayectoria enriquecida, y escribe un diagnosis_*.csv más una narrativa a nivel de modelo.

7. Evaluar otro modelo

Cambia LLM_API_KEY / LLM_BASE_URL en .env, reinicia el motor y vuelve a ejecutar con un --model diferente. Consulta Proveedores de LiteLLM para los nombres de los modelos.

Escalado del rendimiento

Un único entorno aislado maneja tareas concurrentes sin problemas, y puedes ejecutar varias evaluaciones en paralelo contra él. El bucle del agente está limitado por E/S — la mayor parte del tiempo de cada tarea se gasta esperando al modelo, no llamando a herramientas — por lo que un entorno aislado se mantiene muy por debajo de su capacidad con una concurrencia típica. Aumenta --concurrency o lanza múltiples ejecuciones según sea necesario; recurre a las opciones de escalado horizontal a continuación solo cuando el propio entorno aislado se convierta en el cuello de botella (concurrencia muy alta, o cargas de trabajo intensivas en herramientas donde algunos servidores MCP se degradan bajo carga):

Fragmentar en pilas independientes (lo más simple). Ejecuta varios pares de entorno aislado + motor en diferentes puertos, apunta run_eval.py a un subconjunto de tareas para cada uno y luego concatena los CSVs de salida. Cada tarea se ejecuta de principio a fin en una pila, por lo que el estado dentro de la tarea (sistema de archivos, memoria, git) se mantiene consistente. El .env del motor no anula las variables ya establecidas en el entorno, por lo que las anulaciones de PORT / MCP_SANDBOX_URL por pila funcionan sin problemas:

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

Apuntar a un orquestador (escala más lejos). Dado que el motor accede al entorno aislado únicamente a través de MCP_SANDBOX_URL, puedes apuntarlo a un servicio que aprovisione un entorno aislado efímero por tarea — sin cambios en el motor; cualquier endpoint HTTP que implemente la API del entorno del agente funciona.

Una regla al agregar entornos aislados: mantén todas las llamadas a herramientas de una tarea en el mismo entorno aislado. El balanceo de carga por llamada entre réplicas rompe las herramientas con estado (sistema de archivos, memoria, git, MongoDB), que asumen una vista consistente dentro de una tarea.

Qué Incluye

• Motor del agente (services/agent-harness/, TypeScript) — bucle del agente de múltiples turnos, se comunica con el entorno aislado a través de MCP_SANDBOX_URL.

• Entorno del agente (services/agent-environment/, Python) — entorno aislado en Docker que sirve los 36 servidores MCP a través de HTTP.

• Puntuación (services/scoring/, Python) — puntuación de cobertura de afirmaciones mediante LLM como juez.

• Diagnósticos (services/diagnostics/, Python) — clasificación de modos de fallo en una taxonomía de 11 modos.

Citación

Si usas MCP-Atlas en tu investigación, por favor cita:

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