Connexions MCP

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

Choisissez l’origine de la connexion en fonction de l’endroit depuis lequel le serveur est accessible.

Connexion depuis OpenAI

Ajoutez un serveur MCP utilisant HTTP à agent.tools. Le serveur doit être accessible depuis OpenAI. Cette connexion 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
}

Connexion depuis votre environnement

L’exécuteur peut établir une connexion MCP depuis l’environnement de la session. Utilisez ce mode pour accéder à des serveurs sur un réseau privé ou à des logiciels installés dans cet environnement.

Définissez le champ 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.

Connexion via HTTP

Utilisez HTTP si le serveur est déjà en cours d’exécution. Ajoutez l’entrée suivante à 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 qui utilise localhost pointe vers l’environnement de la session. Si vous omettez connection_origin, OpenAI établit la connexion.

Démarrage d’un serveur avec stdio

Utilisez stdio pour que l’exécuteur lance le processus du 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 code du 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 indique au script quel transport utiliser.

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, indiquez obligatoirement command et un chemin absolu pour cwd. Le champ args est facultatif. Omettez connection_origin.

Envoyez un message demandant à l’agent de rechercher le client 123. L’outil renvoie le nom Example Customer et la formule pro.

Pour les serveurs MCP utilisant stdio dans un environnement hébergé par OpenAI, omettez la politique réseau ou définissez-la sur enabled. Ces connexions ne prennent pas en charge les politiques réseau disabled et restricted.

Ajout de l’authentification

Si le serveur autorise l’accès anonyme, omettez les champs d’authentification et vault_ids. Dans le cas contraire, choisissez la source des identifiants pour votre connexion.

• Identifiants HTTP pour une seule session. Renseignez transport.authorization ou transport.headers à la création de la session. L’API Agents chiffre ces valeurs et les exclut de la ressource de session qu’elle renvoie.
• Identifiants HTTP réutilisables. Stockez les identifiants MCP dans un coffre-fort et associez-le à la session via vault_ids. Seules les connexions MCP établies depuis OpenAI peuvent s’authentifier à l’aide d’un coffre-fort. Les identifiants sont sélectionnés en fonction de l’URL du serveur. Si plusieurs identifiants correspondent, utilisez credential_id pour en choisir un.
• Identifiants pour stdio. Définissez les valeurs dans l’environnement et indiquez les noms des variables correspondantes dans transport.env_vars. Le code exécuté dans l’environnement peut lire ces valeurs. Les sessions auto-hébergées n’acceptent pas les valeurs définies directement dans transport.env.

Par exemple, la configuration du transport HTTP peut inclure un jeton Bearer et un en-tête supplémentaire.

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

Pour Authorization, utilisez une seule source. Fournissez la valeur directement dans la configuration ou utilisez un identifiant du coffre-fort correspondant à l’URL du serveur. Vous pouvez ajouter d’autres en-têtes lorsque vous utilisez un coffre-fort pour l’authentification. Les connexions HTTP établies depuis l’environnement n’utilisent pas les identifiants du coffre-fort. Configurez l’authentification directement ou utilisez un proxy de confiance.

N’incluez aucun secret dans les définitions d’agents réutilisables, les archives de plugins ou les journaux. Pour que le code généré par l’agent ne puisse pas accéder aux identifiants, utilisez un proxy ou un serveur de confiance qui les fournit en dehors de l’environnement.

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

Renseignez allowed_tools pour limiter les outils que l’agent peut découvrir et appeler. Définissez required: true pour que le tour échoue si le serveur ne parvient pas à s’initialiser. Par défaut, l’initialisation est facultative.

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

Dépannage des connexions

Si un serveur requis ne parvient pas à s’initialiser, examinez l’erreur dans agent.session.turn.failed. Pour les serveurs utilisant 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 le serveur est accessible depuis son réseau.
• Identifiants. Vérifiez le jeton ou les en-têtes. Si vous utilisez un coffre-fort, vérifiez que l’identifiant 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. Si vous configurez stdio directement, indiquez dans cwd le chemin absolu d’un répertoire existant.

Guides associés

• Les plugins regroupent la configuration MCP et les skills pour que vous puissiez les réutiliser d’une session à l’autre.
• Le guide sur la recherche d’outils explique comment fonctionne la découverte automatique des outils MCP avec les modèles et les fournisseurs pris en charge.