Configuración completa del servidor MCP
En esta página
Uniendo todas las piezas
Has visto cada parámetro de forma aislada. Esta lección los integra en configuraciones completas, tal y como las escribirás en la práctica, mostrando en cada caso el equivalente en los dos SDK principales. El objetivo no es introducir conceptos nuevos, sino ofrecerte patrones que puedas adaptar directamente.
A continuación tienes una visión general de los seis parámetros, indicando si son obligatorios u opcionales.
| Parámetro | Obligatorio | Función |
|---|---|---|
server_url | Sí | URL HTTPS del servidor MCP |
server_label | Sí | Prefijo para la llamada a la herramienta |
server_description | No | Guía a Grok en la selección del servidor |
allowed_tool_names | No | Restringe las herramientas accesibles |
authorization | No | Token de autenticación |
headers | No | Cabeceras HTTP adicionales |
El caso más sencillo
Bastan dos parámetros cuando el servidor es público y no requiere autenticación.
# xAI SDK
tools = [mcp(server_url="https://mcp.deepwiki.com/mcp", server_label="deepwiki")]
# Responses API (OpenAI)
tools = [{
"type": "mcp",
"server_url": "https://mcp.deepwiki.com/mcp",
"server_label": "deepwiki"
}]
Esto es exactamente lo que escribirás para DeepWiki. Grok tendrá acceso a todas las herramientas del servidor, lo cual resulta aceptable aquí porque se trata de un servicio público de solo lectura. En cuanto el servidor pertenezca a tu organización, esta configuración se quedará corta.
Un servidor interno de solo lectura
Subamos un escalón: un CRM empresarial que el agente debe poder consultar, pero nunca modificar. Se añaden tres parámetros, cada uno por una razón distinta: la descripción guía al modelo, el token acredita la identidad y la lista de permitidos prohíbe las escrituras.
# xAI SDK
tools = [
mcp(
server_url="https://api.monentreprise.com/mcp",
server_label="crm",
server_description="CRM interno. Solo búsqueda de contactos y empresas.",
authorization=f"Bearer {os.getenv('CRM_TOKEN')}",
allowed_tool_names=["search_contacts", "get_contact", "list_companies"]
)
]
# Responses API (OpenAI)
tools = [{
"type": "mcp",
"server_url": "https://api.monentreprise.com/mcp",
"server_label": "crm",
"server_description": "CRM interno. Solo búsqueda de contactos y empresas.",
"authorization": f"Bearer {os.getenv('CRM_TOKEN')}",
"allowed_tool_names": ["search_contacts", "get_contact", "list_companies"]
}]
Compara ambos bloques: el contenido es idéntico; solo cambia el contenedor. La función auxiliar mcp() acepta argumentos con nombre; el formato de OpenAI espera un diccionario con una clave adicional "type". Esta es la única diferencia que debes recordar al trasladar una configuración de un SDK al otro.
Una configuración exhaustiva
Paso final: los seis parámetros combinados en una llamada real al SDK de xAI.
import os
from xai_sdk import Client
from xai_sdk.tools import mcp
client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
model="grok-4.20-0309-reasoning",
tools=[
mcp(
server_url="https://tools.monentreprise.com/v1/mcp",
server_label="outils-internes",
server_description="Plataforma de herramientas internas: gestión documental, tickets de soporte, base de conocimientos. Acceso de solo lectura.",
authorization=f"Bearer {os.getenv('TOOLS_MCP_TOKEN')}",
headers={
"X-Organization-Id": os.getenv("ORG_ID"),
"X-Environment": "production",
"X-Request-Source": "grok-agent"
},
allowed_tool_names=[
"search_documents",
"get_document",
"search_tickets",
"get_ticket",
"search_knowledge_base"
]
)
],
include=["verbose_streaming"],
)
Observa la coherencia interna de este ejemplo. La descripción anuncia acceso de solo lectura y las cinco herramientas permitidas son operaciones de consulta; no hay contradicción entre lo que el modelo cree que puede hacer y lo que la configuración permite. La cabecera X-Environment establecida en production evita que un agente de prueba escriba en datos en vivo, y X-Request-Source hará que los rastros de tu servidor sean accionables si necesitas localizar el origen de una solicitud inesperada.
Revisa antes de desplegar
Seis puntos merecen una revisión antes de cualquier despliegue en producción; cada uno corresponde a una trampa encontrada anteriormente en este curso. La URL debe ser HTTPS con un certificado válido; de lo contrario, nada funcionará. La etiqueta debe ser breve, descriptiva y única dentro de la configuración. La descripción debe coincidir con las herramientas realmente expuestas; si no, el modelo intentará llamadas destinadas a fallar. Las herramientas permitidas deben reducirse al mínimo estricto. El token debe proceder de una variable de entorno, no del código fuente. Y las cabeceras adicionales deben ser exactamente las que espera tu servidor, con la capitalización correcta: un error de mayúsculas en X-Organization-Id provoca un fallo silencioso especialmente doloroso de diagnosticar.
Puntos clave
- La configuración mínima solo requiere
server_urlyserver_label - Añade
server_descriptionpara guiar a Grok, especialmente en entornos con varios servidores - Restringe con
allowed_tool_namespor seguridad y rendimiento - Usa
authorizationyheaderspara la autenticación - Ambos SDK (xAI nativo y OpenAI Responses) aceptan los mismos parámetros con sintaxis distinta