server_url et server_label

Les deux paramètres sans lesquels rien ne part

Toute connexion entre Grok et un serveur MCP distant repose sur deux paramètres : server_url et server_label. Ils ne sont pas négociables — en leur absence, l’API refuse la requête avant même d’avoir tenté quoi que ce soit. Tous les autres paramètres que vous découvrirez ensuite viennent affiner ce socle, jamais le remplacer.

server_url : l’adresse exacte de l’endpoint

Le paramètre server_url contient l’URL complète du serveur MCP auquel Grok doit se connecter, et cette URL obéit à des règles strictes.

La première est le HTTPS. L’URL doit commencer par https://, et xAI rejette toute connexion en HTTP non chiffré. La raison est facile à saisir : les échanges entre Grok et le serveur MCP transportent les requêtes de vos utilisateurs, les résultats des outils et parfois le token d’authentification lui-même. Laisser cela circuler en clair serait indéfendable.

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

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

La deuxième règle concerne la précision du chemin. L’URL doit pointer vers l’endpoint MCP, pas vers la racine du domaine. Presque tous les serveurs exposent leur endpoint sur un chemin dédié, et la convention varie de l’un à l’autre. Voici trois formes valides que vous rencontrerez :

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

La troisième règle découle des deux premières : localhost et les adresses IP privées sont exclus. Le serveur doit être joignable depuis l’infrastructure xAI, sur un domaine public, avec un certificat SSL valide. Cela pose une question très concrète en développement, puisque votre serveur MCP en cours d’écriture tourne sur votre machine. La réponse habituelle consiste à passer par un tunnel — ngrok ou Cloudflare Tunnel, par exemple — qui expose votre instance locale derrière une URL HTTPS publique le temps de vos tests.

server_label : l’identité du serveur dans la conversation

Le server_label est un identifiant court que Grok utilise pour préfixer les appels d’outils issus de ce serveur. Son rôle est double : rendre les traces lisibles, et lever toute ambiguïté quand plusieurs serveurs cohabitent.

Le mécanisme est mécanique. Si votre serveur expose un outil nommé search_docs et que vous lui donnez le label deepwiki, l’appel apparaîtra sous la forme deepwiki__search_docs dans les logs comme dans les réponses de l’API.

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

Trois critères guident le choix d’un bon label. Il doit être court, puisqu’il s’ajoute au nom de chaque appel et qu’un label verbeux alourdit inutilement vos logs. Il doit être descriptif, pour que la source d’un appel se lise d’un coup d’oeil sans consulter la configuration. Il doit être unique dans votre configuration, faute de quoi vous ne saurez plus distinguer deux serveurs. Les exemples ci-dessous satisfont ces trois exigences :

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

L’enjeu devient beaucoup plus tangible dès que vous connectez plusieurs serveurs à une même session. Supposez que votre documentation interne et DeepWiki exposent tous deux un outil appelé search. Sans labels distincts, les noms d’outils entrent en collision et Grok n’a aucun moyen de savoir lequel viser. Avec des labels, les deux outils s’appellent deepwiki__search et docs-internes__search, et la confusion disparaît. Vous reviendrez sur ce point dans la leçon consacrée au multi-serveur.

La configuration minimale, dans les deux SDK

Réunis, ces deux paramètres suffisent à faire fonctionner un serveur MCP public. Avec le SDK xAI natif :

from xai_sdk.tools import mcp

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

Et le strict équivalent avec l’API Responses au 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