Documentación Oficial de MCP en Español
  1. Conceptos
Documentación Oficial de MCP en Español
  • Empezar
    • Introducción
    • Servidores de ejemplo
    • Clientes de ejemplo
    • Inicio rápido
      • Para desarrolladores de servidores
      • Para desarrolladores de clientes
      • Para usuarios de Claude Desktop
  • Tutoriales
    • Construyendo MCP con LLMs
    • Depuración
    • Inspector
  • Conceptos
    • Arquitectura central
    • Recursos
    • Indicaciones
    • Herramientas
    • Muestreo
    • Raíces
    • Transportes
  • Desarrollo
    • Qué hay de nuevo
    • Hoja de ruta
    • Contribuyendo
  1. Conceptos

Herramientas

Habilitar a las LLMs para realizar acciones a través de tu servidor
Las herramientas son una primitiva poderosa en el Protocolo de Contexto del Modelo (MCP) que permite a los servidores exponer funcionalidad ejecutable a los clientes. A través de las herramientas, las LLMs pueden interactuar con sistemas externos, realizar cálculos y tomar acciones en el mundo real.
Las herramientas están diseñadas para ser controladas por el modelo, lo que significa que las herramientas se exponen desde los servidores a los clientes con la intención de que el modelo de IA pueda invocarlas automáticamente (con un humano en el circuito para conceder la aprobación).

Descripción general#

Las herramientas en MCP permiten a los servidores exponer funciones ejecutables que pueden ser invocadas por los clientes y utilizadas por las LLMs para realizar acciones. Los aspectos clave de las herramientas incluyen:
Descubrimiento: Los clientes pueden listar las herramientas disponibles a través del endpoint tools/list
Invocación: Las herramientas se llaman utilizando el endpoint tools/call, donde los servidores realizan la operación solicitada y devuelven los resultados
Flexibilidad: Las herramientas pueden variar desde cálculos simples hasta interacciones complejas de API
Al igual que los recursos, las herramientas se identifican por nombres únicos y pueden incluir descripciones para guiar su uso. Sin embargo, a diferencia de los recursos, las herramientas representan operaciones dinámicas que pueden modificar el estado o interactuar con sistemas externos.

Estructura de definición de herramientas#

Cada herramienta se define con la siguiente estructura:

Implementación de herramientas#

Aquí hay un ejemplo de implementación de una herramienta básica en un servidor MCP:
TypeScript
Python

Ejemplos de patrones de herramientas#

Aquí hay algunos ejemplos de tipos de herramientas que un servidor podría proporcionar:

Operaciones del sistema#

Herramientas que interactúan con el sistema local:

Integraciones de API#

Herramientas que envuelven APIs externas:

Procesamiento de datos#

Herramientas que transforman o analizan datos:

Mejores prácticas#

Al implementar herramientas:
1.
Proporcionar nombres y descripciones claros y descriptivos
2.
Utilizar definiciones detalladas de JSON Schema para los parámetros
3.
Incluir ejemplos en las descripciones de las herramientas para demostrar cómo el modelo debe usarlas
4.
Implementar el manejo y la validación de errores adecuados
5.
Utilizar informes de progreso para operaciones largas
6.
Mantener las operaciones de las herramientas enfocadas y atómicas
7.
Documentar las estructuras de valores de retorno esperadas
8.
Implementar timeouts adecuados
9.
Considerar la limitación de velocidad para operaciones intensivas en recursos
10.
Registrar el uso de la herramienta para la depuración y el monitoreo

Consideraciones de seguridad#

Al exponer herramientas:

Validación de entrada#

Validar todos los parámetros contra el esquema
Sanear las rutas de archivos y los comandos del sistema
Validar las URLs y los identificadores externos
Comprobar los tamaños y rangos de los parámetros
Prevenir la inyección de comandos

Control de acceso#

Implementar la autenticación donde sea necesario
Utilizar las comprobaciones de autorización apropiadas
Auditar el uso de la herramienta
Limitar la velocidad de las solicitudes
Monitorear el abuso

Manejo de errores#

No exponer los errores internos a los clientes
Registrar los errores relevantes para la seguridad
Manejar los timeouts apropiadamente
Limpiar los recursos después de los errores
Validar los valores de retorno

Descubrimiento y actualizaciones de herramientas#

MCP soporta el descubrimiento dinámico de herramientas:
1.
Los clientes pueden listar las herramientas disponibles en cualquier momento
2.
Los servidores pueden notificar a los clientes cuando las herramientas cambian utilizando notifications/tools/list_changed
3.
Las herramientas se pueden agregar o eliminar durante el tiempo de ejecución
4.
Las definiciones de herramientas se pueden actualizar (aunque esto debe hacerse con cuidado)

Manejo de errores#

Los errores de las herramientas deben informarse dentro del objeto de resultado, no como errores de nivel de protocolo MCP. Esto permite a la LLM ver y potencialmente manejar el error. Cuando una herramienta encuentra un error:
1.
Establecer isError en true en el resultado
2.
Incluir los detalles del error en el array content
Aquí hay un ejemplo de manejo de errores adecuado para las herramientas:
TypeScript
Python
Este enfoque permite a la LLM ver que se produjo un error y potencialmente tomar medidas correctivas o solicitar la intervención humana.

Prueba de herramientas#

Una estrategia de prueba integral para las herramientas MCP debe cubrir:
Pruebas funcionales: Verificar que las herramientas se ejecuten correctamente con entradas válidas y manejar las entradas no válidas de manera apropiada
Pruebas de integración: Probar la interacción de la herramienta con sistemas externos utilizando dependencias reales y simuladas
Pruebas de seguridad: Validar la autenticación, la autorización, el saneamiento de la entrada y la limitación de la velocidad
Pruebas de rendimiento: Comprobar el comportamiento bajo carga, el manejo del timeout y la limpieza de los recursos
Manejo de errores: Asegurarse de que las herramientas informen correctamente los errores a través del protocolo MCP y limpien los recursos
Previous
Indicaciones
Next
Muestreo
Built with