server_url et server_label

Les deux paramètres obligatoires

Pour connecter Grok à un serveur MCP distant, deux paramètres sont indispensables : server_url et server_label. Sans eux, l’API refuse la requête. Ce sont les fondations de toute configuration MCP.

server_url : l’adresse du serveur MCP

Le paramètre server_url contient l’URL complète du serveur MCP auquel Grok doit se connecter. Cette URL doit respecter plusieurs règles strictes.

HTTPS obligatoire

L’URL doit commencer par https://. xAI refuse toute connexion en HTTP non chiffré. C’est une mesure de sécurité fondamentale : les échanges entre Grok et le serveur MCP contiennent potentiellement des données sensibles (requêtes utilisateur, résultats d’outils, tokens d’authentification).

# Correct
mcp(server_url="https://mcp.deepwiki.com/mcp")

# Refusé par l'API
mcp(server_url="http://mcp.deepwiki.com/mcp")

Format de l’URL

L’URL pointe vers l’endpoint MCP du serveur. Ce n’est pas forcément la racine du domaine — la plupart des serveurs exposent leur endpoint MCP sur un chemin spécifique comme /mcp, /api/mcp ou /v1/mcp.

Exemples d’URL valides :

https://mcp.deepwiki.com/mcp
https://api.example.com/mcp
https://tools.monentreprise.com/v1/mcp

Pas de localhost

Puisque l’URL doit être en HTTPS et accessible depuis les serveurs xAI, vous ne pouvez pas utiliser localhost ou une adresse IP privée. Le serveur MCP doit être déployé sur un domaine public avec un certificat SSL valide.

Pour le développement local, vous devrez utiliser un tunnel (comme ngrok ou Cloudflare Tunnel) pour exposer votre serveur MCP local en HTTPS.

server_label : l’identifiant du serveur

Le server_label est un identifiant court que Grok utilise pour préfixer les appels d’outils issus de ce serveur. Il joue un rôle crucial dans la lisibilité et la désambiguïsation des outils.

Rôle du label

Quand Grok appelle un outil MCP, il préfixe le nom de l’outil avec le server_label. Si votre serveur expose un outil search_docs et que le label est deepwiki, l’appel apparaîtra comme deepwiki__search_docs dans les logs et les réponses.

mcp(
    server_url="https://mcp.deepwiki.com/mcp",
    server_label="deepwiki"
)
# Les outils seront préfixés : deepwiki__search_docs, deepwiki__get_page, etc.

Règles de nommage

Choisissez un label qui soit :

• Court : il préfixe chaque appel d’outil, donc un label trop long alourdit les logs
• Descriptif : il doit permettre d’identifier la source d’un appel d’un coup d’oeil
• Unique : si vous utilisez plusieurs serveurs MCP, chaque label doit être différent

Exemples de bons labels :

server_label="deepwiki"     # Documentation GitHub
server_label="crm"          # Système de gestion clients
server_label="jira"         # Suivi de tickets
server_label="search"       # Moteur de recherche interne

Importance en multi-serveur

Le label devient essentiel quand vous connectez plusieurs serveurs MCP à la même session. Si deux serveurs exposent un outil nommé search, le label permet à Grok de savoir lequel utiliser. Sans labels distincts, les noms d’outils entreraient en conflit.

Exemple complet avec les deux paramètres

from xai_sdk.tools import mcp

tools = [
    mcp(
        server_url="https://mcp.deepwiki.com/mcp",
        server_label="deepwiki"
    )
]

Avec l’API Responses (format OpenAI) :

tools = [{
    "type": "mcp",
    "server_url": "https://mcp.deepwiki.com/mcp",
    "server_label": "deepwiki",
}]

Points clés à retenir

• server_url et server_label sont les deux seuls paramètres obligatoires
• L’URL doit être en HTTPS avec un certificat SSL valide, pas de localhost
• Le label préfixe tous les appels d’outils issus de ce serveur (format label__outil)
• Choisissez des labels courts, descriptifs et uniques par serveur
• Le label est indispensable pour le multi-serveur afin d’éviter les conflits de noms