Claude Code sale de fábrica ya siendo capaz, pero se queda corto en cuanto tu proyecto empieza a tocar sistemas externos: un tracker de tickets, una base de datos, tu propio VPS. Esta guía cubre las cuatro piezas que lo convierten en una herramienta de verdad para producción:
MCP (/mcp): conectar servicios externos como herramientas.
Subagentes: delegar tareas a instancias aisladas con su propio contexto.
Skills / slash commands: empaquetar prompts repetitivos como comandos.
Hooks: barandillas deterministas que no dependen de que la IA "se acuerde" de una instrucción.
Hace falta Claude Code instalado y autenticado, y una terminal abierta en cualquier carpeta de proyecto.
1
Conecta tu primer servidor MCP
MCP (Model Context Protocol) permite que Claude Code use herramientas que no trae de serie. Esas herramientas viven en servidores MCP: procesos locales o servicios alojados en una URL. Se añaden con claude mcp add, sin tocar JSON a mano. Empieza con el servidor de documentación oficial, que no pide ni cuenta ni configuración:
bash
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
Confirma que quedó conectado:
bash
claude mcp list
Deberías ver ✔ Connected. Dentro de una sesión, gestiona servidores en cualquier momento con /mcp.
2
Servidor local (stdio) y servidor con login OAuth
Un servidor stdio es un programa que Claude Code arranca como subproceso — útil cuando necesita tocar tu filesystem o un navegador. Ejemplo con Playwright, que no requiere cuenta:
bash
claude mcp add playwright -- npx -y @playwright/mcp@latest
El -- separa las opciones de Claude Code del comando que arranca el servidor. Para servicios que sí piden login (Sentry, Linear, Notion, GitHub), se añade igual y se autentica desde dentro de la sesión:
bash
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
Tras el add verás ! Needs authentication. Entra a una sesión, ejecuta /mcp, selecciona el servidor y elige "Authenticate": se abre el navegador para el login.
Si el servicio usa token estático en vez de OAuth (típico en instancias self-hosted, por ejemplo un Gitea privado), pásalo directamente:
Por defecto, cada servidor se registra en scope "local": solo para ti, solo en el proyecto actual. Hay dos alternativas según cuánto quieras compartir:
bash
# Disponible en todos tus proyectos, privado
claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp
# Compartido con el equipo vía repo (escribe .mcp.json)
claude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp
Scope
Archivo
Para quién
local
~/.claude.json (entrada del proyecto)
Solo tú, solo este proyecto
project
.mcp.json en la raíz del repo
Todo el equipo que clone
user
~/.claude.json (clave global mcpServers)
Solo tú, todos los proyectos
Si prefieres escribir .mcp.json a mano para versionarlo con el equipo:
Un subagente es una instancia con su propio contexto, su propio system prompt y sus propias herramientas, que trabaja de forma aislada y devuelve solo un resumen. Sirve para no inundar tu conversación principal con logs o resultados que no vas a reutilizar, y para reutilizar un mismo "trabajador" una y otra vez con las mismas instrucciones.
Claude Code trae tres subagentes integrados: Explore (búsqueda de código, solo lectura), Plan (investigación durante el modo plan) y general-purpose (tareas complejas con acceso a todo). Para uno propio, basta con pedírselo a Claude:
bash
Crea un subagente personal en ~/.claude/agents/ llamado "code-reviewer" que
revise código en busca de calidad, seguridad y buenas prácticas. Que sea de
solo lectura y use Sonnet.
Claude escribe el archivo con frontmatter YAML + el prompt del sistema:
bash
---
name: code-reviewer
description: Revisa código en busca de calidad, seguridad y buenas prácticas. Úsalo tras escribir o modificar código.
tools: Read, Grep, Glob
model: sonnet
---
Eres un revisor de código senior. Para cada problema que encuentres,
explica el problema, muestra el código actual y ofrece una versión mejorada.
Los campos de frontmatter más útiles: tools (lista blanca de herramientas), disallowedTools (lista negra), model (sonnet/opus/haiku/inherit) y mcpServers (da acceso a un servidor MCP solo a ese subagente, sin cargar su contexto en la conversación principal).
Guárdalo en .claude/agents/ para que sea solo de este proyecto, o en ~/.claude/agents/ para que esté disponible en todos.
5
Invoca subagentes: lenguaje natural, @-mención o sesión completa
Hay tres formas de usar un subagente, de menos a más explícito:
bash
# Lenguaje natural: Claude decide si delega
Usa el subagente code-reviewer para revisar mis cambios recientes
# @-mención: fuerza que se use ese subagente concreto
@"code-reviewer (agent)" revisa la lógica de autenticación
# Sesión completa como ese subagente (system prompt y tools de ese agente)
claude --agent code-reviewer
Para investigaciones independientes, puedes pedir varios subagentes en paralelo:
bash
Investiga en paralelo con subagentes separados los módulos de autenticación,
base de datos y API
Cada uno explora su parte de forma aislada; tú solo recibes la síntesis final en tu conversación principal.
6
Empaqueta prompts repetitivos: slash commands y skills
Si repites la misma instrucción una y otra vez, conviértela en comando. Los comandos clásicos (.claude/commands/*.md) siguen funcionando, pero la forma recomendada ahora son las Skills (.claude/skills//SKILL.md) — si un comando y una skill comparten nombre, gana la skill.
Comando clásico, guardado como .claude/commands/audit-disk.md:
bash
---
description: Auditoría de espacio en disco con umbral configurable
allowed-tools: Read, Bash, Grep
argument-hint: [umbral-porcentaje]
---
Audita el espacio en disco de los servidores. Umbral de alerta: $ARGUMENTS%.
Se invoca con /audit-disk 85. $ARGUMENTS captura todo lo que escribas después del comando; con !comando puedes inyectar salida de shell en vivo (por ejemplo !git diff --cached).
La misma idea como skill, en .claude/skills/audit-disk/SKILL.md:
bash
---
name: audit-disk
description: Auditoría de espacio en disco con umbral configurable. Úsalo cuando el usuario pida revisar espacio en los servidores.
allowed-tools: Read, Bash, Grep
---
Audita el espacio en disco de los servidores...
La ventaja de las skills: pueden empaquetar varios archivos de referencia en la misma carpeta, y Claude puede invocarlas solo, sin que escribas la barra.
7
Pon barandillas deterministas con hooks
Si trabajas en modo autónomo (--dangerously-skip-permissions), los hooks son la forma de bloquear operaciones peligrosas sin depender de que la IA se acuerde de una regla. Se disparan siempre, en el punto exacto del ciclo de vida que definas.
Los dos eventos más usados: PreToolUse (antes de ejecutar una herramienta — sirve para bloquear) y PostToolUse (después — sirve para formatear, lintar o loguear). Se configuran en settings.json:
El script recibe el comando por stdin como JSON, y con exit code 2 bloquea la operación. Ejemplo que impide un pkill demasiado amplio en un servidor donde varios procesos comparten el mismo nombre:
bash
#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$COMMAND" | grep -qE 'pkill.*node|rm -rf /'; then
echo "Bloqueado: comando demasiado amplio o destructivo. Usa PID exacto." >&2
exit 2
fi
exit 0
Recuerda darle permisos de ejecución:
bash
chmod +x ./scripts/validate-command.sh
Otro clásico: formatear cada archivo que Claude toca, sin tener que pedirlo:
Con estas cuatro piezas, Claude Code deja de ser un asistente de terminal y pasa a ser una capa de automatización real: conecta lo que necesite (MCP), delega lo que ensucie el contexto (subagentes), empaqueta lo que se repite (skills) y respeta límites duros que no dependen de su memoria (hooks). El orden recomendado para adoptarlos: primero un servidor MCP de bajo riesgo, luego un subagente de solo lectura, después migra tus comandos a skills sin prisa, y por último —el más rentable si trabajas en modo autónomo— añade al menos un hook que bloquee la operación que más miedo te da.
Administrador de sistemas Windows y Linux en una empresa de telecomunicaciones. El día a día es servidores, Active Directory, Docker y automatización; el tiempo libre, más de lo mismo pero por gusto — siempre liado probando algo nuevo, montando algo en el homelab o viendo qué cacharro se puede automatizar a continuación. Si algo se puede scriptear, mejor que no hacerlo a mano dos veces.
