Configuration complète d'un serveur MCP

Assembler ce que vous avez appris

Vous avez rencontré chaque paramètre isolément. Cette leçon les remet ensemble dans des configurations complètes, telles que vous les écrirez réellement, en montrant à chaque fois l’équivalent dans les deux SDK principaux. L’objectif n’est pas d’ajouter des notions mais de vous donner des modèles que vous pourrez adapter directement.

Voici d’abord la vue d’ensemble des six paramètres, avec leur caractère obligatoire ou non.

Le cas le plus simple

Deux paramètres suffisent quand le serveur est public et n’attend aucune authentification.

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

# API Responses (OpenAI)
tools = [{
    "type": "mcp",
    "server_url": "https://mcp.deepwiki.com/mcp",
    "server_label": "deepwiki"
}]

C’est exactement ce que vous écrirez pour DeepWiki. Grok a alors accès à l’intégralité des outils du serveur, ce qui reste acceptable ici puisqu’il s’agit d’un service public en lecture. Dès que le serveur appartient à votre organisation, cette configuration devient insuffisante.

Un serveur interne en lecture seule

Franchissons une marche : un CRM d’entreprise, que l’agent doit pouvoir consulter mais jamais modifier. Trois paramètres s’ajoutent, chacun pour une raison distincte — la description oriente le modèle, le token prouve l’identité, la liste blanche interdit l’écriture.

# SDK xAI
tools = [
    mcp(
        server_url="https://api.monentreprise.com/mcp",
        server_label="crm",
        server_description="CRM interne. Consultation de contacts et d'entreprises uniquement.",
        authorization=f"Bearer {os.getenv('CRM_TOKEN')}",
        allowed_tool_names=["search_contacts", "get_contact", "list_companies"]
    )
]

# API Responses (OpenAI)
tools = [{
    "type": "mcp",
    "server_url": "https://api.monentreprise.com/mcp",
    "server_label": "crm",
    "server_description": "CRM interne. Consultation de contacts et d'entreprises uniquement.",
    "authorization": f"Bearer {os.getenv('CRM_TOKEN')}",
    "allowed_tool_names": ["search_contacts", "get_contact", "list_companies"]
}]

Comparez les deux blocs : le contenu est identique, seule l’enveloppe change. Le helper mcp() prend des arguments nommés, le format OpenAI attend un dictionnaire avec une clé "type" supplémentaire. C’est la seule différence à mémoriser lorsque vous transposez une configuration d’un SDK vers l’autre.

Une configuration exhaustive

Dernier palier, avec les six paramètres réunis dans un appel réel au SDK 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="Plateforme d'outils internes : gestion documentaire, tickets support, base de connaissances. Accès en lecture seule.",
            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"],
)

Observez la cohérence interne de cet exemple. La description annonce un accès en lecture seule, et les cinq outils autorisés sont tous des opérations de consultation — aucune contradiction entre ce que le modèle croit pouvoir faire et ce que la configuration lui permet. L’en-tête X-Environment fixé à production évite qu’un agent de test aille écrire dans les données réelles, et X-Request-Source rendra vos traces serveur exploitables le jour où vous chercherez d’où vient une requête inattendue.

Vérifier avant de déployer

Six points méritent une relecture avant toute mise en production, et ils recoupent chacun un piège rencontré plus tôt dans ce cours. L’URL doit être en HTTPS avec un certificat valide, sans quoi rien ne partira. Le label doit rester court, descriptif et unique dans la configuration. La description doit correspondre aux outils réellement exposés, faute de quoi le modèle tentera des appels condamnés. Les outils autorisés doivent être réduits au strict nécessaire. Le token doit provenir d’une variable d’environnement et non du code source. Et les en-têtes supplémentaires doivent être ceux qu’attend votre serveur, avec les bons noms — une faute de casse sur X-Organization-Id produit un échec silencieux particulièrement pénible à diagnostiquer.

Points clés à retenir

• La configuration minimale ne nécessite que server_url et server_label
• Ajoutez server_description pour guider Grok, surtout en multi-serveur
• Restreignez avec allowed_tool_names pour la sécurité et la performance
• Utilisez authorization et headers pour l’authentification
• Les deux SDK (xAI natif et OpenAI Responses) acceptent les mêmes paramètres avec une syntaxe différente