Diseño de herramientas y MCP: arquitectura, seguridad…

Diseño de herramientas y MCP: arquitectura, seguridad y escala

Una herramienta bien diseñada es la diferencia entre un agente fiable en producción y un sistema frágil que genera incidentes. En la práctica, tu arquitectura depende de qué sistemas permites que Claude alcance, cómo describes eso, y qué garantías de seguridad estableciste antes de darle acceso. Este es exactamente el territorio donde muchos arquitectos se equivocan: no es un problema solo de técnica, sino de decisiones sistémicas.

En esta lección aprenderás a pensar como arquitecto sobre herramientas y MCP: granularidad funcional, descripciones que Claude entienda de verdad, manejo de fallos, y cómo Model Context Protocol cambia el juego cuando necesitas exponer APIs complejas de forma segura y controlada.

¿Qué es una herramienta desde la perspectiva de arquitectura?

Para Claude, una herramienta es un contrato: una definición estructurada (nombre, descripción, parámetros de entrada, tipos, restricciones) que le permite decidir si usarla y cómo usarla. No es simplemente "una función que puedes llamar". Es una declaración arquitectónica de capacidad.

Desde el punto de vista de diseño:

Una herramienta representa un dominio de responsabilidad: debe hacer una cosa bien, no múltiples cosas.
Su descripción es tu SLA con Claude: si la describes mal, Claude la usará mal o no la usará.
Los tipos y validaciones son defensas de seguridad: no son solo metadata, son barreras de comportamiento.

Cuando diseñas herramientas, estás respondiendo estas preguntas arquitectónicas:

¿Qué capacidades necesita Claude para resolver el problema?
¿Cuál es la unidad mínima de responsabilidad que puedo exponer?
¿Qué errores pueden ocurrir y cómo manejo la confiabilidad?
¿Quién puede usar esto y bajo qué restricciones?

Granularidad: el equilibrio entre poder y seguridad

Este es uno de los errores más comunes: herramientas demasiado anchas o demasiado estrechas.

Herramientas demasiado amplias:

- Nombre: ejecutar_sql
- Descripción: "Ejecuta cualquier consulta SQL contra la base de datos"
- Parámetros: query (string)

Problema: Claude podría ejecutar DROP TABLE usuarios. No hay protección en la arquitectura.

Herramientas demasiado específicas:

- obtener_usuario_por_id
- obtener_usuario_por_email
- obtener_usuario_por_teléfono
- actualizar_nombre_usuario
- actualizar_email_usuario
...

Problema: complejidad cognitiva, mayor latencia (más llamadas), difícil de mantener.

Punto de equilibrio (Goldilocks):

- obtener_usuario (parámetros: id, email o teléfono; retorna: nombre, email, rol)
- actualizar_usuario (parámetros: id, campos permitidos: nombre, email; validaciones)

La granularidad correcta es la que:

Agrupa operaciones lógicamente relacionadas
Limita el riesgo exponiendo solo lo necesario
Reduce el número de llamadas que Claude debe hacer
Permite validación concentrada

Pregúntate: ¿puede Claude resolver el problema en 3-5 llamadas a herramientas? Si necesita 20, tu granularidad es demasiado fina.

Descripciones claras: el manual que Claude entiende

La descripción de una herramienta no es documentación técnica. Es instrucción operacional. Claude la lee una sola vez antes de decidir usarla.

Ejemplo malo:

Nombre: process_payment
Descripción: "Procesa pagos"
Parámetros:
  - amount (number): el monto
  - currency (string): la moneda
  - account_id (string): ID de cuenta

Claude no sabe: ¿debo usar esta herramienta siempre? ¿Solo en ciertos casos? ¿Qué pasa si falla? ¿Qué monedas soporta?

Ejemplo bueno:

Nombre: process_payment
Descripción: "Procesa pagos de clientes. Úsala cuando el usuario 
confirme explícitamente una compra. Soporta USD, EUR, MXN. 
Retorna ID de transacción si es exitoso, o error si fondos insuficientes 
o cuenta está bloqueada. No reintentar automáticamente: si falla, 
informa al usuario."
Parámetros:
  - amount (number): monto positivo, máx 50000
  - currency (string): "USD", "EUR", o "MXN"
  - account_id (string): ID de cuenta válida, formato: ACC-XXXXXX

Buenas prácticas:

Sé específico sobre cuándo usarla: "cuando el usuario confirme..."
Lista límites y restricciones: monedas, rangos, validaciones
Describe el comportamiento en error: qué puede fallar y qué esperar
Usa lenguaje simple: evita jerga interna

Manejo de errores y resiliencia

En arquitectura de herramientas, el error es información. No es un fallo técnico, es parte del contrato.

Cuando diseñes una herramienta, define:

Qué errores pueden ocurrir y son normales (usuario no existe, saldo insuficiente, recurso no disponible)
Cómo representarlos (estructura de error consistente)
Qué debe hacer Claude (reintentar, informar al usuario, usar alternativa)

Estructura recomendada:

{
  "success": false,
  "error_type": "insufficient_balance",
  "error_message": "Usuario tiene saldo de $150, solicita $500",
  "recoverable": true,
  "suggestion": "Pregunta al usuario si desea proceder con monto menor"
}

O para casos exitosos:

{
  "success": true,
  "transaction_id": "TXN-12345",
  "amount": 500,
  "currency": "USD",
  "timestamp": "2025-01-15T10:30:00Z"
}

Esto permite que Claude:

Entienda si debe reintentar
Informe al usuario con contexto real
Tome decisiones basadas en la naturaleza del error

Model Context Protocol (MCP): arquitectura para sistemas complejos

Model Context Protocol es la evolución natural cuando tus herramientas no son simples llamadas API, sino acceso a ecosistemas enteros (repositorios, bases de datos, sistemas externos).

MCP es un protocolo estándar que permite:

Exposición segura de múltiples herramientas: un servidor MCP puede servir 50+ herramientas de forma organizada
Gestión de conexión: Claude se conecta a servidores MCP, no a APIs directas
Contexto persistente: el servidor mantiene sesión, caché, estado
Seguridad por capas: autenticación del servidor, autorización por herramienta

Cuándo usar MCP

Usa MCP cuando:

Necesitas exponer múltiples herramientas relacionadas (15+)
Requieres gestión de estado o sesión (ej: conectarse a una BD)
Quieres separación clara entre tu código y Claude
Necesitas que múltiples aplicaciones/agentes accedan al mismo conjunto de herramientas

No necesitas MCP si:

Tienes 3-5 herramientas simples
Cada herramienta es una llamada HTTP stateless
No hay requisitos de contexto persistente

Arquitectura típica con MCP

┌─────────────┐
│   Claude    │
└──────┬──────┘
       │ (usa herramientas vía API oficial)
       │
┌──────▼──────────────────────────────────────┐
│  Tu aplicación / Agente                     │
│  - Gestiona conversación                    │
│  - Maneja orquestación                      │
└──────┬──────────────────────────────────────┘
       │ (conecta a MCP como cliente)
       │
┌──────▼──────────────┐
│  Servidor MCP       │ ← Tu código
│  - Herramientas     │
│  - Recursos         │
│  - Autenticación    │
└──────┬──────────────┘
       │
  ┌────┴─────────────┐
  │                  │
┌─▼──────┐      ┌───▼──┐
│  BD    │      │ APIs │
└────────┘      └──────┘

MCP es especialmente poderoso para:

Integración con repositorios Git: exposición de lectura/escritura de código
Acceso a bases de datos: múltiples tablas y operaciones, todo seguro
Sistemas de gestión: ERP, CRM, project management

Seguridad y permisos: el corazón de la arquitectura

Este es el aspecto que nunca debes dejar al azar. Cuando expones herramientas, estás creando superficies de ataque potencial.

Diseño de herramientas y MCP: arquitectura, seguridad y escala