mcp-agent MCP — Casos de uso, Instalar & Demo en vivo

Por qué usarlo

Características clave

Librería de patrones: Orchestrator, Router, Evaluator, Swarm, Parallel, Deep Research
Flujos de trabajo durables via Temporal (mismo código, solo cambia executor)
El ciclo de vida de MCPApp gestiona conexiones de servidor de manera limpia
Decoradores: @app.workflow, @app.tool, @app.workflow_task

Demo en vivo

Cómo se ve en la práctica

mcp-agent.replay ▶ listo

0/0

Instalar

Elige tu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-agent": {
      "command": "uvx",
      "args": [
        "mcp-agent"
      ]
    }
  }
}

Abre Claude Desktop → Settings → Developer → Edit Config. Reinicia después de guardar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-agent": {
      "command": "uvx",
      "args": [
        "mcp-agent"
      ]
    }
  }
}

Cursor usa el mismo esquema mcpServers que Claude Desktop. La configuración del proyecto prevalece sobre la global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-agent": {
      "command": "uvx",
      "args": [
        "mcp-agent"
      ]
    }
  }
}

Haz clic en el icono MCP Servers de la barra lateral de Cline y luego en "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-agent": {
      "command": "uvx",
      "args": [
        "mcp-agent"
      ]
    }
  }
}

Mismo formato que Claude Desktop. Reinicia Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-agent",
      "command": "uvx",
      "args": [
        "mcp-agent"
      ]
    }
  ]
}

Continue usa un array de objetos de servidor en lugar de un mapa.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-agent": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-agent"
        ]
      }
    }
  }
}

Añádelo a context_servers. Zed recarga en caliente al guardar.

claude mcp add mcp-agent -- uvx mcp-agent

Un solo comando. Verifica con claude mcp list. Quita con claude mcp remove.

Casos de uso

Usos del mundo real: mcp-agent

Construir un agente orquestador-trabajadores para tareas de investigación

👤 Desarrolladores de Python que construyen agentes multi-paso ⏱ ~60 min advanced

Cuándo usarlo: La tarea es demasiado grande para un pase de LLM, pero se descompone en subtareas paralelas (p. ej., investigar 10 competidores).

Requisitos previos

Python 3.10+ — estándar
Servidores MCP que quieres que use el agente — Enuméralos en la configuración de mcp-agent

Flujo

Define agentes trabajadores

Crea 2 Agentes — scraper con el servidor firecrawl, writer con sistema de archivos. Dale a cada uno un conjunto de instrucciones enfocado.✓ Copiado

→ Dos instancias de Agent
Conecta el orquestador

Envuélvelos con create_orchestrator(planner_llm=..., workers=[scraper, writer]). Max iterations = 10.✓ Copiado

→ El orquestador devuelve plan + identificador de ejecución
Ejecuta una tarea real

Ejecuta: 'Investiga los 5 MCPs de Postgres mejor calificados en GitHub. Para cada uno, escribe un resumen de 1 página en ./reports/<slug>.md.'✓ Copiado

→ 5 archivos generados con contenido coherente

Resultado: Un agente paralelizado que completa lo que serían 30 min de trabajo manual multi-paso en 3-5 min.

Errores comunes

El orquestador crea demasiadas o muy pocas subtareas — Dale al LLM planificador guía explícita: 'divide en 3-7 subtareas, cada una <5 minutos de trabajo'
Los trabajadores vuelven a recuperar los mismos datos — Comparte una caché vía el estado de la app o pasa resultados explícitamente a través del plan

Combinar con: mcp-use · fastmcp

Construir un agente evaluador-optimizador para escritura de alta calidad

👤 Equipos que envían pipelines de contenido ⏱ ~45 min advanced

Cuándo usarlo: La salida de LLM en primer borrador es demasiado descuidada para producción. Necesitas un bucle automático 'sigue iterando hasta que pase'.

Flujo

Define el escritor y el evaluador

Escritor: produce un borrador dado un resumen. Evaluador: puntúa en [precisión, claridad, tono] 1-5, con justificación.✓ Copiado

→ Dos agentes definidos
Configura el bucle

Usa EvaluatorOptimizer con min_rating=4 en todos los criterios, max_iterations=5. Pasa brief como entrada.✓ Copiado

→ El bucle se ejecuta, iteraciones visibles en logs
Observa la convergencia

Para 10 resúmenes diversos, registra: puntuación inicial, puntuación final, iteraciones necesarias. ¿Hay resúmenes que nunca convergen?✓ Copiado

→ Estadísticas con valores atípicos identificados

Resultado: Salida de calidad consistente sin revisión humana en el bucle.

Errores comunes

El evaluador es indulgente, el bucle sale en iter 1 con salida mediocre — Calibra el evaluador — dale 3 entradas de ejemplo con puntuaciones esperadas en el system prompt
El presupuesto se dispara cuando max_iterations es alto — Limítalo a 3-4; si no converge para entonces, el problema es el brief, no el modelo

Hacer un flujo de trabajo de agente duradero con Temporal

👤 Ingenieros de plataforma ejecutando agentes en producción ⏱ ~90 min advanced

Cuándo usarlo: Tu flujo de agente se ejecuta durante mucho tiempo (minutos a horas), no puedes permitirte reiniciar desde cero si un nodo muere.

Requisitos previos

Clúster Temporal en ejecución — temporal server start-dev para local, Temporal Cloud o auto-alojado para prod

Flujo

Anota los flujos de trabajo

Decora mi función orquestadora existente con @app.workflow y pasos individuales con @app.workflow_task.✓ Copiado

→ Flujo de trabajo registrado en Temporal
Cambia el ejecutor

Cambia la configuración de la app executor: 'temporal'. Registra el trabajador. Inicia un flujo de trabajo.✓ Copiado

→ La UI de Temporal muestra el flujo de trabajo en ejecución
Verifica la recuperación de caída

Mata el trabajador de Python a mitad del flujo de trabajo. Reinícialo. Confirma que el flujo de trabajo se reanuda desde la última actividad completada.✓ Copiado

→ Sin trabajo duplicado, sin estado perdido

Resultado: Los flujos de trabajo del agente sobreviven a reinicios de procesos, despliegues y OOMs — crítico para tareas de investigación de horas.

Errores comunes

Las actividades no son idempotentes y la reanudación causa escrituras dobles — Cada actividad debe ser segura para reintentar — usa claves de idempotencia en escrituras externas

Combinaciones

Combínalo con otros MCPs para multiplicar por 10

mcp-agent + mcp-use

mcp-use para plomería de cliente + mcp-agent para patrones de flujo de trabajo

Usa mcp-use para conectar filesystem + git. Envuelve con el Orchestrator de mcp-agent para planificar una refactorización multi-repo.✓ Copiado

mcp-agent + fastmcp

Construir MCPs personalizados con FastMCP que tus flujos de trabajo mcp-agent consumen

Expón nuestra API de clasificación interna via FastMCP, luego úsala en un Router de mcp-agent que clasifica preguntas de clientes.✓ Copiado

Herramientas

Lo que expone este MCP

Herramienta	Entradas	Cuándo llamar	Coste
MCPApp	config_path u objeto config	Nivel superior — uno por proceso	gratuito
Agent(name, instruction, server_names)	configurado con los servidores MCP que puede usar	Define cada trabajador/rol	gratuito
AugmentedLLM.generate / generate_str / generate_structured	mensajes, esquema opcional	Llamada directa a LLM con herramientas MCP conectadas	tokens de LLM
create_parallel_llm / create_router_llm / create_orchestrator	agentes + LLM planificador	Instancia uno de los patrones integrados	tokens de LLM × dispersión de patrón
@app.workflow / @app.workflow_task	decorador en función async	Al usar ejecutor Temporal	gratuito
EvaluatorOptimizer	writer_agent, evaluator_agent, min_rating, max_iterations	Salidas críticas de calidad	costoso — limita max_iterations

Coste y límites

Lo que cuesta ejecutarlo

Cuota de API: Ninguno de mcp-agent; LLM + costos de MCP se transfieren
Tokens por llamada: Los patrones amplifican — un Parallel con 5 trabajadores es 5× los tokens de una llamada de LLM única
Monetario: Librería gratuita; LLM + infra Temporal opcional son costos reales
Consejo: Patrones como Orchestrator se dispersan — pon una verificación de presupuesto de tokens explícita en el system prompt del LLM planificador

Seguridad

Permisos, secretos, alcance

Almacenamiento de credenciales: variables de entorno para claves de LLM + secretos por-MCP

Salida de datos: Proveedor de LLM + cada servidor MCP configurado + Temporal (si está habilitado)

Resolución de problemas

Errores comunes y soluciones

El flujo de trabajo se cuelga al inicio sin logs

El servidor MCP no se pudo generar. Habilita logging de depuración: logger: {level: 'DEBUG'} en config. Generalmente un comando/env incorrecto en la entrada del servidor.

El orquestador devuelve plan pero no ejecución

Llamaste .plan() en lugar de .generate(). Usa el método completo para ejecutar el plan.

El flujo de trabajo Temporal falla con error de serialización

Tu actividad devuelve un objeto no serializable (p. ej., un identificador de cliente MCP). Las actividades deben devolver valores serializables a JSON.

El LLM ignora herramientas disponibles y alucina

El system prompt probablemente está truncado o le falta la lista de herramientas. Actualiza a un modelo fuerte en uso de herramientas (Sonnet, GPT-4o) y verifica herramientas en list_tools antes de ejecutar.

Alternativas

mcp-agent vs otros

Alternativa	Cuándo usarla	Contrapartida
mcp-use	Quieres plomería de cliente más ligera sin la librería de patrones	Escribe el código de orquestación tú mismo
LangGraph	Quieres gráficos con estado con depuración de viaje en el tiempo	Más centrado en LangChain; MCP es algo añadido
CrewAI	Quieres equipos de agentes basados en roles con opinión	Modelo mental diferente; el soporte de MCP es secundario

Más

Recursos

📖 Lee el README oficial en GitHub

🐙 Ver issues abiertas

🔍 Ver todos los 400+ servidores MCP y Skills