Connexions MCP

Un serveur MCP publie des définitions d’outils et exécute les appels d’outils. L’API Agents découvre les outils, appelle le serveur et renvoie les résultats à l’agent. Votre application n’a pas besoin de gérer chaque appel.

Choisissez d’où établir la connexion en fonction de l’endroit depuis lequel le serveur est accessible :

Connectez-vous depuis OpenAI

Ajoutez un serveur MCP HTTP à agent.tools. Le serveur doit être accessible depuis OpenAI. Cette configuration fonctionne avec ou sans environnement de session.

Par exemple, le serveur MCP de la documentation OpenAI autorise l’accès anonyme :

12345678910{
  "type": "mcp",
  "server_label": "openai_docs",
  "transport": {
    "type": "http",
    "server_url": "https://developers.openai.com/mcp"
  },
  "connection_origin": "service",
  "required": true
}

Connectez-vous depuis votre environnement

Une connexion MCP via l’exécuteur est établie depuis l’environnement de la session. Utilisez-la pour les serveurs d’un réseau privé ou les logiciels installés dans cet environnement.

Définissez environment.type de la session sur self_hosted ou openai_hosted. Pour un environnement auto-hébergé, connectez l’exécuteur avant que l’agent utilise ses outils.

Connectez-vous via HTTP

Utilisez HTTP pour un serveur déjà en cours d’exécution. Ajoutez cette entrée à agent.tools, en remplaçant l’URL par une adresse accessible depuis votre environnement :

12345678910{
  "type": "mcp",
  "server_label": "internal_search",
  "transport": {
    "type": "http",
    "server_url": "https://mcp.internal.example.com/search"
  },
  "connection_origin": "environment",
  "required": true
}

Ici, une URL localhost renvoie à l’environnement de la session. Si vous omettez connection_origin, la connexion est établie depuis OpenAI.

Démarrez un serveur via stdio

Utilisez stdio pour permettre à l’exécuteur de démarrer un processus serveur. Installez d’abord le serveur et ses dépendances dans l’environnement.

Pour cet exemple de recherche de clients, installez le SDK MCP :

python3 -m venv /workspace/mcp-demo
/workspace/mcp-demo/bin/python -m pip install 'mcp==1.26.0'

Enregistrez le serveur dans /workspace/lookup_mcp.py :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import sys

from mcp.server.fastmcp import FastMCP

server = FastMCP("customer-lookup", host="127.0.0.1", port=8765, stateless_http=True)


@server.tool()
def get_customer(customer_id: str) -> dict:
    """Look up a customer in the example data."""
    customers = {"123": {"name": "Example Customer", "plan": "pro"}}
    return {"customer": customers.get(customer_id)}


if __name__ == "__main__":
    transport = sys.argv[1] if len(sys.argv) > 1 else "streamable-http"
    server.run(transport=transport)

Ajoutez le serveur à agent.tools. L’argument stdio sélectionne le transport du script :

1234567891011{
  "type": "mcp",
  "server_label": "customer_lookup",
  "transport": {
    "type": "stdio",
    "command": "/workspace/mcp-demo/bin/python",
    "args": ["/workspace/lookup_mcp.py", "stdio"],
    "cwd": "/workspace"
  },
  "required": true
}

Pour stdio, command et un chemin absolu pour cwd sont requis ; args est facultatif. Omettez connection_origin.

Envoyez un message demandant à l’agent de rechercher le client 123. L’outil renvoie Example Customer, qui dispose de l’offre pro.

Pour les serveurs MCP stdio hébergés par OpenAI, omettez la politique réseau ou définissez-la sur enabled. Les politiques réseau disabled et restricted ne sont pas prises en charge pour ces connexions.

Ajoutez l’authentification

Pour un serveur qui autorise l’accès anonyme, omettez les champs d’authentification et vault_ids. Sinon, choisissez la source des informations d’authentification pour votre connexion :

• Informations d’authentification HTTP pour une session : Définissez transport.authorization ou transport.headers lors de la création de la session. L’API Agents chiffre ces valeurs et les exclut de la ressource de session renvoyée.
• Informations d’authentification HTTP réutilisables : Stockez les informations d’authentification dans un coffre-fort et rattachez-le via vault_ids. Les coffres-forts s’appliquent uniquement aux connexions établies depuis OpenAI. Les informations d’authentification sont sélectionnées en fonction de l’URL du serveur ; utilisez credential_id pour choisir une entrée lorsque plusieurs correspondent.
• Informations d’authentification stdio : Fournissez les valeurs dans l’environnement et indiquez leurs noms dans transport.env_vars. Ces valeurs peuvent être lues par le code exécuté dans l’environnement. Les sessions auto-hébergées n’acceptent pas de valeurs fournies directement dans transport.env.

Par exemple, un transport HTTP peut inclure un token Bearer et un autre en-tête :

123456{
  "type": "http",
  "server_url": "https://mcp.example.com/mcp",
  "authorization": "Bearer YOUR_MCP_ACCESS_TOKEN",
  "headers": { "X-Tenant-ID": "tenant_123" }
}

Utilisez une seule source pour Authorization : une configuration fournie directement ou une entrée correspondante dans un coffre-fort. D’autres en-têtes peuvent accompagner l’authentification par coffre-fort. Les connexions HTTP établies depuis l’environnement n’utilisent pas les informations d’authentification des coffres-forts ; fournissez-les directement ou utilisez un proxy de confiance.

N’incluez aucun secret dans les définitions d’agents réutilisables, les archives de plugins et les journaux. Pour que les informations d’authentification restent inaccessibles au code généré par l’agent, utilisez un proxy ou un serveur de confiance qui les fournit en dehors de l’environnement.

Contrôlez l’accès aux outils et le démarrage

Définissez allowed_tools pour limiter les outils que l’agent peut découvrir et appeler. Définissez required: true pour faire échouer le tour si le serveur ne peut pas s’initialiser. L’initialisation est facultative par défaut.

Consultez la référence de création de session pour connaître tous les champs de configuration MCP.

Résolvez les problèmes de connexion

Si un serveur requis ne peut pas s’initialiser, examinez l’erreur dans agent.session.turn.failed. Pour les serveurs stdio, consultez également les journaux du processus MCP.

• Accès réseau : Vérifiez l’URL et connection_origin. Pour les connexions établies depuis l’environnement, vérifiez que l’exécuteur est connecté et que son réseau permet d’accéder au serveur.
• Informations d’authentification : Vérifiez le token ou les en-têtes. Si vous utilisez un coffre-fort, vérifiez que l’entrée d’authentification correspond à l’URL du serveur.
• Exécutable et dépendances : Vérifiez que la commande configurée s’exécute dans l’environnement.
• Répertoire de travail : Pour une configuration stdio fournie directement, définissez cwd sur le chemin absolu d’un répertoire existant.

Guides connexes

• Les plugins regroupent la configuration MCP et les skills pour les réutiliser dans plusieurs sessions.
• Le guide Recherche d’outils explique la découverte automatique des outils MCP avec les modèles et fournisseurs pris en charge.