Un flujo de trabajo agentivo es un bucle plan-act-observe conectado a una herramienta real, una verificación real y una condición de parada real, no un diagrama. Este laboratorio conecta uno con Claude Code: un servidor MCP que agrega una herramienta, un hook PreToolUse que rechaza las llamadas riesgosas que esa herramienta permite, un par PostToolUse/Stop que ejecuta lint y pruebas después de cada edición, y tres lugares donde un humano aún tiene que actuar. Cada comando a continuación proviene de la documentación oficial de Claude Code, los servidores de referencia MCP o el repositorio del servidor MCP de GitHub.
Paso 1 — Dale al agente una herramienta con MCP
Claude Code no llama herramientas directamente; lee una lista de herramientas que un cliente ensambló, y MCP es cómo esa lista crece. El registro oficial de MCP mantiene dos servidores de referencia que cubren la mayoría de las necesidades de un laboratorio de DevOps: un servidor del sistema de archivos y un servidor de GitHub, ambos enviados por el grupo de dirección o por GitHub mismo, no un paquete de terceros aleatorio.
Servidor del sistema de archivos. Publicado como @modelcontextprotocol/server-filesystem, lee, escribe, mueve y busca archivos en directorios nombrados en su línea de comandos. Ese argumento se documenta como el único método que funciona con cada versión de protocolo que el servidor admite; una lista de directorio suministrada por cliente (Roots) es una conveniencia obsoleta para clientes más antiguos, no algo en lo que depender. Agrégalo como un servidor limitado al proyecto para que la entrada viva en un .mcp.json que el equipo pueda revisar:
claude mcp add --scope project --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem "$CLAUDE_PROJECT_DIR"
Eso escribe:
{
"mcpServers": {
"filesystem": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "${CLAUDE_PROJECT_DIR}"]
}
}
}
Servidor de GitHub. GitHub mantiene github/github-mcp-server, distribuido como una imagen de Docker en ghcr.io/github/github-mcp-server, y recomienda mantener el token de acceso personal fuera del archivo de configuración pasándolo a través del entorno:
export GITHUB_PAT=your_token_here
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PAT -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
Existe una alternativa alojada en https://api.githubcopilot.com/mcp/ si prefieres no ejecutar el contenedor localmente; de cualquier manera, limita el token estrechamente, ya que el servidor puede acceder a la mayoría de la API de GitHub que ese token permite.
Abre una sesión y confirma que el servidor se cargó con /mcp. Los hosts, clientes y transportes se tratan en Servidores MCP explicados; este laboratorio va directamente a los controles alrededor de la herramienta.
Paso 2 — Bloquea las llamadas peligrosas con un hook PreToolUse
Una herramienta MCP aparece en eventos de hook bajo un patrón de nombre fijo: mcp__<servidor>__<herramienta>. Las herramientas de escritura del servidor del sistema de archivos son write_file y edit_file, por lo que los nombres completos son mcp__filesystem__write_file y mcp__filesystem__edit_file. Un coincididor construido solo a partir de letras, dígitos, guiones bajos y | se compara como una lista exacta de strings, por lo que este coincididor golpea solo esas dos herramientas y nada con un prefijo similar:
.claude/hooks/guard-fs-write.sh:
#!/bin/bash
# Deny filesystem MCP writes outside the project's scratch/ directory.
input=$(cat)
path=$(printf '%s' "$input" | jq -r '.tool_input.path // empty')
scratch="${CLAUDE_PROJECT_DIR:-.}/scratch"
case "$path" in
"$scratch"/*) exit 0 ;;
"") exit 0 ;;
*)
echo "Blocked: $path is outside scratch/. Widen the hook on purpose if this edit is intended." >&2
exit 2
;;
esac
{
"hooks": {
"PreToolUse": [
{
"matcher": "mcp__filesystem__write_file|mcp__filesystem__edit_file",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard-fs-write.sh"
}
]
}
]
}
}
Salida 2 cancela la llamada y entrega al agente la línea stderr como la razón, por lo que un bucle que siga llegando fuera de scratch/ se redirige en lugar de ser silenciosamente rechazado. La misma sintaxis cubre el servidor de GitHub: mcp__github__.* es una expresión regular (contiene un punto) que coincide con cada herramienta que ese servidor expone; estréchala más para puerta solo las herramientas que escriben.
Este es el mismo mecanismo que usan las herramientas Edit y Write incorporadas, cubierto en la guía de hooks; una herramienta MCP es solo un nombre más largo en el mismo campo tool_name.
Paso 3 — Ejecuta el pipeline de validación automáticamente
Un hook PostToolUse se ejecuta después de que una llamada a herramienta ya tuvo éxito, que es el punto correcto para un formateador o una ejecución de prueba estrecha, no para prevenir la escritura. Encadénalo después de las herramientas de edición incorporadas y la herramienta MCP del sistema de archivos para que ningún camino omita la verificación:
.claude/hooks/validate-change.sh:
#!/bin/bash
# Lint, then test, the file Claude just touched. Block the result on failure.
input=$(cat)
path=$(printf '%s' "$input" | jq -r '.tool_input.path // .tool_input.file_path // empty')
[ -f "$path" ] || exit 0
case "$path" in
*.py)
ruff check "$path" >&2 || exit 2
pytest "$path" >&2 || exit 2
;;
*.ts|*.js)
npx eslint "$path" >&2 || exit 2
npm test -- "$path" >&2 || exit 2
;;
esac
exit 0
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write|mcp__filesystem__write_file|mcp__filesystem__edit_file",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/validate-change.sh",
"timeout": 120
}
]
}
]
}
}
Un hook Stop cierra la brecha que una verificación por archivo deja: nada arriba re-ejecuta la suite completa. Stop se dispara en cada turno, ignora completamente los coincididores y puede bloquear el fin del turno hasta que salga 0:
.claude/hooks/require-green-suite.sh:
#!/bin/bash
# Block the end of the turn until the full test suite is green.
if ! npm test >&2; then
echo "Full suite is red. Fix the failure before the turn ends." >&2
exit 2
fi
exit 0
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/require-green-suite.sh",
"timeout": 180
}
]
}
]
}
}
Claude Code detiene de honrar un hook Stop bloqueante después de ocho bloqueos consecutivos sin llamada a herramienta entre ellos, por lo que esto es un respaldo contra una prueba flaky, no reintento infinito. Un sub-agente es la otra forma documentada para este trabajo: un agente code-reviewer con herramientas de solo lectura, llamado después de un lote de ediciones, reporta hallazgos bloqueantes y no bloqueantes sin tocar archivos. La guía de subagentes tiene el formato de archivo; usa un hook Stop para una verificación pass/fail determinista, un sub-agente para una llamada de criterio que un script no puede hacer.
Paso 4 — Pon un humano en tres lugares específicos
Los hooks mantienen el bucle dentro de un carril. No reemplazan a una persona decidiendo que el carril es correcto. Tres checkpoints se construyen en Claude Code y no necesitan un script personalizado:
- Prompts de permisos. En modo
default, Claude Code pregunta antes del primer uso de cada herramienta en una sesión, incluyendo una herramienta MCP que el proyecto acaba de agregar. Ese prompt único es aún el momento de notar un servidor que no debería haber sido aprobado. - Modo plan.
claude --permission-mode plan,/plan, o Shift+Tab coloca la sesión en una pasada de investigación de solo lectura: Claude lee archivos y explora pero no edita, y las ediciones permanecen bloqueadas hasta que el plan sea aprobado, incluso si un hookPreToolUsepermitiría uno. Alcanza esto antes del primer prompt en un repo desconocido. - Revisión de solicitud de extracción. Apunta el servidor MCP de GitHub a abrir una rama y una solicitud de extracción de borrador en lugar de empujar a una rama predeterminada, y requiere la aprobación humana usual antes de fusionar. El pipeline de validación es la puerta antes de que exista la PR; la revisión es la puerta antes de que aterrice.
Nada de esto es un sandbox por sí solo. Mantén bypassPermissions para un contenedor o VM aislado, como lo alcanza la documentación del modo de permisos, no para una sesión en ejecución contra tu árbol de trabajo.
El bucle de extremo a extremo
┌────────────────────────────────────────────────┐
│ │
▼ │
┌───────────┐ ┌───────────┐ ┌────────────┐ ┌─────────────┐
│ PLAN │ --> │ ACT │ --> │ VALIDATE │ --> │ HUMAN GATE │
│ plan mode │ │ MCP tool │ │ PostToolUse│ │ permission │
│ read-only │ │ call, │ │ lint+test, │ │ prompt, PR │
│ research │ │ guarded │ │ Stop hook │ │ review │
│ │ │ by │ │ re-runs │ │ │
│ │ │ PreToolUse│ │ full suite │ │ │
└───────────┘ └───────────┘ └─────┬──────┘ └──────┬──────┘
│ exit 2 │ reject plan
└── keep acting ◄────────┘
El modo plan es la entrada; PreToolUse se sienta en cada llamada MCP dentro de act; PostToolUse y Stop son validar; el prompt de permisos, la aprobación del plan y la revisión de la PR son las tres puertas humanas. Un hook Stop fallido envía el bucle de vuelta a act, no alrededor de la puerta humana.
Un nodo AI Agent de n8n construye el mismo bucle fuera de un agente de codificación, con nodos de flujo de trabajo en el lugar de hooks; ver el primer flujo de trabajo de n8n para un objetivo en forma de HTTP en lugar de un repo. Un equipo formalizando la validación como especificaciones escritas en lugar de pruebas ad hoc puede llevar la misma puerta a desarrollo impulsado por especificación.
Trampas
Bucles desbocados. El límite de ocho bloques del hook Stop es un respaldo, no un diseño. El control real es alcanzar lo que act puede alcanzar primero: un conjunto de herramientas MCP estrecho, un directorio scratch/ y bypassPermissions reservado para un contenedor que puedas tirar.
Permisos de herramienta demasiado amplios. La lista de directorio permitido del servidor del sistema de archivos solo cubre rutas pasadas en su línea de comandos; no confíes en el soporte de Roots de un cliente en su lugar, ya que ese es el único método garantizado de funcionar en cada versión de protocolo. Para GitHub, limita el token a los repos y acciones que el laboratorio necesita, no un token con acceso de cuenta completa.
Secretos en env de MCP. Pasa GITHUB_PERSONAL_ACCESS_TOKEN a través del env del servidor, como arriba, nunca en línea en un .mcp.json confirmado. El alcance del proyecto se comparte a través de git a propósito; un token cocido en ese archivo se envía a todos los que clonan el repo.
Costo. Cada llamada a herramienta MCP, invocación de hook y revisión de sub-agente es su propia unidad de trabajo contra la sesión. Un hook Stop que re-ejecuta una suite lenta en cada turno, o un bucle que sigue reintentando una edición bloqueada, suma rápido; mantén la verificación de suite completa en Stop, no PostToolUse, y mantén la verificación por archivo estrecha.
Trata todo el pipeline como algo que escribirás una vez que funcione, de la misma manera que una lista de verificación de gobernanza de IA espera que un equipo registre qué herramientas puede alcanzar un agente y quién aprueba lo que cambia.
Preguntas frecuentes
¿Qué es un flujo de trabajo agentivo?
Un bucle donde un modelo planifica un paso, llama una herramienta, lee el resultado y decide el siguiente paso, en lugar de devolver una respuesta. Continúa hasta que no haya llamada a herramienta, una verificación falle o un humano lo detenga. Las piezas que lo hacen seguro ejecutar son el límite de herramienta, un paso de validación y al menos un punto donde una persona tiene que decir que sí.
¿Cómo le doy a Claude Code una nueva herramienta sin escribir un servidor?
Agrega un servidor MCP de referencia oficial. El servidor del sistema de archivos (@modelcontextprotocol/server-filesystem) y el servidor de GitHub (github/github-mcp-server) son mantenidos por el grupo de dirección del protocolo y por GitHub. Registra cualquiera con claude mcp add, o escribe la entrada en .mcp.json tú mismo.
¿Qué evento de hook bloquea una acción peligrosa antes de que se ejecute?
PreToolUse. Dale un coincididor para la herramienta exacta, incluyendo el nombre completo mcp__server__tool de una herramienta MCP, y sale 2 del script del hook con una razón en stderr. Una JSON permissionDecision de deny hace lo mismo sin depender del código de salida.
¿Reemplaza un hook Stop la revisión humana del diff?
No. Un hook Stop puede bloquear el fin de un turno hasta que un comando salga cero, que es útil para una suite de prueba, pero Claude Code se rinde después de ocho bloqueos consecutivos sin llamada a herramienta entre ellos. Los prompts de permisos, el modo plan y una revisión de pull request son los checkpoints humanos reales; el hook solo mantiene el bucle lo suficiente para llegar a uno.
¿Cómo evito que el agente se quede en bucle para siempre?
Alcanza primero los permisos propios del servidor MCP, por ejemplo el argumento allowed-directory del servidor del sistema de archivos, para que un mal bucle solo pueda tocar un árbol pequeño. Mantén bypassPermissions para un contenedor aislado, no tu portátil. El límite de ocho bloques del hook Stop es un respaldo, no el control principal.
Cómo se verificó esta guía
Escrita a mano a partir de la documentación oficial, con cada comando comprobado de nuevo y una segunda revisión antes de publicar. Última revisión: .
Fuentes oficiales consultadas para este artículo
- code.claude.com/docs/en/mcp
- code.claude.com/docs/en/hooks
- code.claude.com/docs/en/hooks-guide
- code.claude.com/docs/en/permission-modes
- code.claude.com/docs/en/permissions
- code.claude.com/docs/en/agent-sdk/permissions
- github.com/modelcontextprotocol/servers
- github.com/modelcontextprotocol/servers/blob/main/src/filesystem/README.md
- github.com/github/github-mcp-server
- docs.github.com/en/copilot/how-tos/provide-context/use-mcp-in-your-ide/set-up-the-github-mcp-server

