Authentification et headers

Sécuriser la connexion MCP

La plupart des serveurs MCP en production nécessitent une authentification. Sans elle, n’importe qui pourrait utiliser les outils du serveur. xAI fournit deux paramètres pour gérer l’authentification : authorization pour le token d’accès, et headers / extra_headers pour les en-têtes HTTP supplémentaires.

Le paramètre authorization

Le paramètre authorization transmet un token d’authentification au serveur MCP. Ce token est envoyé dans l’en-tête HTTP Authorization de chaque requête vers le serveur.

mcp(
    server_url="https://api.example.com/mcp",
    server_label="internal",
    authorization="Bearer sk-votre-token-ici"
)

Format du token

Le format du token dépend du serveur MCP cible. Les formats les plus courants sont :

• Bearer token : "Bearer sk-xxxx" — le plus répandu, utilisé par la majorité des API REST
• API key : "ApiKey votre-cle" — certains services utilisent un préfixe personnalisé
• Basic auth : "Basic base64(user:password)" — authentification basique encodée en base64

Le paramètre authorization accepte n’importe quelle chaîne — c’est le serveur MCP qui valide le format.

Sécurité du token

Le token est transmis dans chaque requête HTTP vers le serveur MCP. Il est donc essentiel de :

• Ne jamais coder le token en dur dans votre code source. Utilisez des variables d’environnement
• Utiliser des tokens à portée limitée : si le serveur le permet, générez un token qui n’a accès qu’aux outils nécessaires
• Renouveler régulièrement les tokens, surtout en production

import os

mcp(
    server_url="https://api.example.com/mcp",
    server_label="internal",
    authorization=f"Bearer {os.getenv('MCP_SERVER_TOKEN')}"
)

headers et extra_headers

Certains serveurs MCP nécessitent des en-têtes HTTP supplémentaires au-delà du token d’authentification. Le paramètre headers (ou extra_headers selon le SDK) permet d’ajouter ces en-têtes.

mcp(
    server_url="https://api.example.com/mcp",
    server_label="internal",
    authorization="Bearer sk-token",
    headers={
        "X-Organization-Id": "org-123",
        "X-Project-Id": "proj-456"
    }
)

Cas d’usage des headers supplémentaires

Les en-têtes supplémentaires servent généralement à :

• Identifier le projet ou l’organisation : certains serveurs MCP multi-tenant utilisent des headers pour router les requêtes vers le bon tenant
• Spécifier une version d’API : "X-API-Version": "2024-01" pour cibler une version spécifique
• Ajouter des métadonnées de suivi : identifiant de session, identifiant d’agent, etc.
• Gérer le rate limiting : certains serveurs utilisent des headers pour identifier le plan tarifaire

Différence entre headers et extra_headers

Selon le SDK que vous utilisez, le nom du paramètre peut varier :

• SDK xAI natif : utilise headers dans la plupart des cas
• API Responses (OpenAI) : peut utiliser extra_headers pour éviter les conflits avec les headers gérés automatiquement par le SDK

Le comportement est identique : les en-têtes sont ajoutés à chaque requête vers le serveur MCP.

Exemple complet avec authentification

Voici une configuration complète qui combine tous les paramètres d’authentification :

from xai_sdk.tools import mcp
import os

tools = [
    mcp(
        server_url="https://api.monentreprise.com/mcp",
        server_label="interne",
        server_description="Outils internes : CRM, documentation, tickets",
        authorization=f"Bearer {os.getenv('INTERNAL_MCP_TOKEN')}",
        headers={
            "X-Organization-Id": os.getenv("ORG_ID"),
            "X-Environment": "production"
        },
        allowed_tool_names=["search_docs", "get_ticket", "search_contacts"]
    )
]

Cette configuration :

1. Se connecte au serveur MCP interne en HTTPS
2. S’authentifie avec un Bearer token stocké en variable d’environnement
3. Envoie l’identifiant d’organisation dans un header
4. Restreint les outils accessibles à trois opérations de lecture

Points clés à retenir

• authorization transmet le token d’accès au serveur MCP via l’en-tête HTTP Authorization
• Stockez toujours vos tokens dans des variables d’environnement, jamais en dur dans le code
• headers / extra_headers ajoutent des en-têtes HTTP supplémentaires à chaque requête
• Les en-têtes servent à l’identification multi-tenant, au versioning d’API et au suivi
• Combinez authentification et restriction d’outils pour un maximum de sécurité