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

Configuración completa del servidor MCP

Lección 7 de 12 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Uniendo todas las piezas
  2. El caso más sencillo
  3. Un servidor interno de solo lectura
  4. Una configuración exhaustiva
  5. Revisa antes de desplegar
  6. Puntos clave

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ámetroObligatorioFunción
server_urlSíURL HTTPS del servidor MCP
server_labelSíPrefijo para la llamada a la herramienta
server_descriptionNoGuía a Grok en la selección del servidor
allowed_tool_namesNoRestringe las herramientas accesibles
authorizationNoToken de autenticación
headersNoCabeceras 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_url y server_label
  • Añade server_description para guiar a Grok, especialmente en entornos con varios servidores
  • Restringe con allowed_tool_names por seguridad y rendimiento
  • Usa authorization y headers para la autenticación
  • Ambos SDK (xAI nativo y OpenAI Responses) aceptan los mismos parámetros con sintaxis distinta