Ir al contenido principal
Español— Elegir un idioma
Menú

Descripción y herramientas permitidas

Lección 5 de 12 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Dos palancas opcionales, dos efectos muy distintos
  2. server_description: dar contexto al modelo
  3. allowed_tools: reducir el alcance
  4. Por qué restringir, incluso cuando todo funciona
  5. Haz que ambos trabajen juntos
  6. Puntos clave

Dos palancas opcionales, dos efectos muy distintos

La URL y la etiqueta bastan para establecer la conexión, pero no le indican a Grok cómo utilizar el servidor. Dos parámetros opcionales subsanan esta carencia y se complementan: server_description explica para qué sirve el servidor, mientras que allowed_tools —o allowed_tool_names, según el SDK— decide a qué tiene permiso para tocar. El primero guía; el segundo restringe.

server_description: dar contexto al modelo

Este parámetro proporciona a Grok una descripción en lenguaje natural de las capacidades del servidor. El modelo la utiliza para arbitrar: ¿debe consultar este servidor, otro o ninguno?

mcp(
    server_url="https://api.example.com/mcp",
    server_label="docs",
    server_description="Servidor de documentación técnica. Permite buscar artículos, consultar guías y obtener ejemplos de código para la API interna."
)

Sin esta descripción, Grok solo dispone de los nombres y descripciones individuales de las herramientas expuestas. Funciona, pero el modelo razona sin una visión de conjunto: ve una colección de herramientas sin saber qué forman colectivamente. Una buena descripción le aporta tres cosas que ningún nombre de herramienta puede transmitir: cuándo es relevante este servidor frente a otro, el tipo de solicitudes que debe enrutar hacia él y, algo que a menudo se pasa por alto pero resulta decisivo, qué no hace el servidor, lo cual evita llamadas condenadas al fracaso.

Redacta esta descripción como si le explicaras el servicio a un colega que se incorpora al proyecto. Sé específico: «Base de datos de documentación técnica del producto» es útil; «Documentación», no. Nombra las acciones realmente posibles, como «permite buscar, leer y actualizar tickets». Y si el alcance es restringido, indícalo claramente: «acceso de solo lectura, sin modificaciones» ahorrará al modelo un intento fallido.

allowed_tools: reducir el alcance

Por defecto, conectar Grok a un servidor MCP inyecta todas las herramientas que ese servidor expone en el contexto del modelo, sin excepción. En un CRM, esto significa que crear, modificar y eliminar contactos están tan accesibles como buscarlos.

mcp(server_url="https://api.example.com/mcp",
    server_label="crm")
# Grok ve TODAS las herramientas: create_contact, update_contact,
# delete_contact, search_contacts, export_data, etc.

El parámetro allowed_tool_names invierte este comportamiento al establecer una lista blanca explícita. Todo lo que no figure en ella se vuelve invisible para el modelo.

mcp(server_url="https://api.example.com/mcp",
    server_label="crm",
    allowed_tool_names=["search_contacts", "get_contact_details"])
# Grok solo ve search_contacts y get_contact_details

Por qué restringir, incluso cuando todo funciona

La primera razón es la seguridad, y sigue el principio de mínimo privilegio. Si tu aplicación solo necesita leer, no dejes herramientas de modificación o eliminación al alcance del modelo. Una inyección de instrucciones exitosa —una instrucción maliciosa colada en un documento que Grok analiza— no podrá desencadenar un delete_contact que nunca se expuso. La lista blanca convierte un incidente potencial en un no-evento.

# Solo lectura para un chatbot público
allowed_tool_names=["search_database", "get_record", "format_data"]

La segunda razón es el rendimiento. Cada herramienta expuesta ocupa espacio en la ventana de contexto, ya que su nombre, descripción y esquema de parámetros deben caber allí. Un servidor MCP que publica cincuenta herramientas consume un volumen considerable antes incluso de que el usuario haya formulado su pregunta. Al reducirlo a cinco herramientas realmente útiles, recuperas ese espacio para lo importante: la conversación en sí.

La tercera razón es la precisión. Cuanto más extenso es el catálogo, más duda el modelo entre herramientas similares; y dos herramientas con descripciones parecidas producen elecciones inestables de una ejecución a otra. Un catálogo ajustado a tu caso de uso hace que la selección sea significativamente más fiable.

Haz que ambos trabajen juntos

El resultado es realmente limpio cuando combinas ambos parámetros, siempre que cuenten la misma historia.

mcp(
    server_url="https://api.example.com/mcp",
    server_label="crm",
    server_description="CRM de solo lectura. Búsqueda y visualización de contactos y empresas.",
    allowed_tool_names=["search_contacts", "get_contact", "search_companies", "get_company"]
)

Aquí, la descripción anuncia acceso de solo lectura y la lista blanca lo garantiza técnicamente. Cuidado con la situación contraria, que ocurre más a menudo de lo que crees: una descripción heredada de una versión anterior que promete capacidades de escritura ahora eliminadas de la lista blanca. El modelo intentará la llamada, fallará y perderás tiempo buscando un error que no existe. Revisa siempre estos dos parámetros juntos, nunca por separado.

Puntos clave

  • server_description ayuda a Grok a entender cuándo usar este servidor MCP
  • Sin allowed_tools, todas las herramientas del servidor se inyectan en el contexto
  • Restringir herramientas refuerza la seguridad, el rendimiento y la precisión
  • Combina descripción y restricción para un control óptimo
  • Redacta la descripción como una explicación en lenguaje natural de las capacidades del servidor