Connecteurs et MCP

L'agent appelle des services externes via des connecteurs, des services issus du catalogue de connecteurs de Mistral qui agissent en tant que l'utilisateur qui exécute la session, et via des serveurs MCP auxquels vous accédez avec un identifiant en votre possession. Utilisez un connecteur lorsque le catalogue propose le service ; utilisez votre propre serveur MCP lorsqu'il ne le propose pas, ou lorsque le serveur requiert un identifiant statique, comme une clé API.

Ajoutez un connecteur à l'agent en indiquant son nom :

from mistralai import agents

agent = agents.Agent(model="mistral-large-4", connectors=[agents.connector("github")])

from mistralai import agents

agent = agents.Agent(model="mistral-large-4", connectors=[agents.connector("github")])

L'agent peut ensuite appeler les outils du connecteur comme n'importe quel autre outil. Le connecteur doit être :

• disponible au niveau de l'organisation de l'utilisateur qui exécute une session sur l'agent. L'utilisateur ou un administrateur le rend disponible sur Mistral Studio.
• connecté par l'utilisateur qui exécute la session : l'utilisateur a suivi le flux de connexion, qui permet à la plateforme d'agir avec ses autorisations dans le service tiers.

Si aucun connecteur ne porte ce nom, ou si un connecteur ne se charge pas au démarrage de la session, la session démarre sans lui. Le modèle est informé que le connecteur est indisponible, et vous recevez une agents.Notice, par exemple Connector 'Lienar' is unavailable: no connector has this name. Did you mean 'linear'?. Consultez son details["status"], pas son message : "unsupported" signifie qu'aucune nouvelle tentative ne corrige le connecteur dans cette session, et "unavailable" signifie qu'il peut redevenir disponible.

agents.all_connectors() sélectionne, au démarrage de la session, tous les connecteurs disponibles pour l'utilisateur qui l'exécute :

from mistralai import agents

agent = agents.Agent(model="mistral-large-4", connectors=[agents.all_connectors()])

from mistralai import agents

agent = agents.Agent(model="mistral-large-4", connectors=[agents.all_connectors()])

Deux utilisateurs d'un même agent ont donc chacun leurs propres connecteurs. Nommez les connecteurs que vous savez nécessaires à l'agent, ou retirez les autres avec exclude=. Consultez agents.all_connectors pour connaître ses options.

Un connecteur agit en tant que l'utilisateur qui exécute la session. Lorsque cet utilisateur ne l'a pas connecté, le tour reste en attente d'une connexion jusqu'à ce que votre application y réponde : voir Connexions.

Déclarez vous-même le serveur dans mcps= lorsqu'il requiert un identifiant statique que vous, en tant que développeur, détenez :

import asyncio

from mistralai import agents

agent = agents.Agent(
    model="mistral-large-4",
    mcps={"deepwiki": agents.RemoteMCP(url="https://mcp.deepwiki.com/mcp", model_access="direct")},
)


async def main() -> None:
    result = await agent.run("In one sentence, what is the GitHub repository facebook/react about? Use deepwiki.")
    if isinstance(result, agents.Completed):
        print(result.text)
        print([call.name for call in result.tool_calls])


asyncio.run(main())

import asyncio

from mistralai import agents

agent = agents.Agent(
    model="mistral-large-4",
    mcps={"deepwiki": agents.RemoteMCP(url="https://mcp.deepwiki.com/mcp", model_access="direct")},
)


async def main() -> None:
    result = await agent.run("In one sentence, what is the GitHub repository facebook/react about? Use deepwiki.")
    if isinstance(result, agents.Completed):
        print(result.text)
        print([call.name for call in result.tool_calls])


asyncio.run(main())

The facebook/react repository is the open-source codebase for React, Meta's JavaScript library for building declarative, component-based user interfaces, containing the core `react` package along with renderers like `react-dom`, the React Compiler, and the build/test/release tooling for the monorepo.
['deepwiki.deepwiki_ask_wiki_question']

The facebook/react repository is the open-source codebase for React, Meta's JavaScript library for building declarative, component-based user interfaces, containing the core `react` package along with renderers like `react-dom`, the React Compiler, and the build/test/release tooling for the monorepo.
['deepwiki.deepwiki_ask_wiki_question']

La clé de mcps= nomme le serveur, et model_access définit la manière dont le modèle appelle ses outils, comme pour vos propres outils ; voir Outils.

auth_header_env_vars associe un nom d'en-tête au nom d'une variable d'environnement qui contient la valeur complète de l'en-tête :

from mistralai import agents

agent = agents.Agent(
    model="mistral-large-4",
    mcps={
        "github_copilot": agents.RemoteMCP(
            url="https://api.githubcopilot.com/mcp/",
            auth_header_env_vars={"Authorization": "GITHUB_MCP_TOKEN"},  # GITHUB_MCP_TOKEN="Bearer ghp_..."
        )
    },
)

from mistralai import agents

agent = agents.Agent(
    model="mistral-large-4",
    mcps={
        "github_copilot": agents.RemoteMCP(
            url="https://api.githubcopilot.com/mcp/",
            auth_header_env_vars={"Authorization": "GITHUB_MCP_TOKEN"},  # GITHUB_MCP_TOKEN="Bearer ghp_..."
        )
    },
)

Vous transmettez le nom de la variable, jamais sa valeur. Le SDK lit la variable là où l'agent s'exécute, à chaque requête, si bien que l'identifiant n'entre jamais dans la session. Une variable manquante entraîne un échec avant le démarrage de la session. Avec agents deploy, liez-la à un secret de l'espace de travail : voir Déployer.

Un serveur qui rejette l'identifiant, qui est injoignable ou qui ne répond jamais n'interrompt pas l'exécution. La session abandonne ce serveur pour ce tour, indique la raison au modèle et consigne dans les logs un avertissement précisant le serveur et la cause. La session réessaie le serveur avant les tours suivants, avec un backoff après des échecs répétés. La session vous donne également une agents.Notice pour le serveur, dont source est l'ID du serveur (sa clé dans mcps, sauf si vous définissez id=) et dont details contient reason. En poursuivant l'exemple ci-dessus, dans une fonction asynchrone :

session = await agent.start_session()
await session.run("Find my open pull requests.")

async for event in session.iter_events():
    if isinstance(event, agents.Notice) and event.source == "github_copilot":
        print(event.details["reason"], event.message)
    if isinstance(event, agents.TurnEnded):
        break
await session.cancel()

session = await agent.start_session()
await session.run("Find my open pull requests.")

async for event in session.iter_events():
    if isinstance(event, agents.Notice) and event.source == "github_copilot":
        print(event.details["reason"], event.message)
    if isinstance(event, agents.TurnEnded):
        break
await session.cancel()

credential_rejected github_copilot tools are unavailable because the server rejected the credential (MCP request failed: HTTP 401 Unauthorized).

credential_rejected github_copilot tools are unavailable because the server rejected the credential (MCP request failed: HTTP 401 Unauthorized).

reason peut valoir credential_rejected (HTTP 401 ou 403), credential_unavailable, unreachable, timeout, invalid_catalog ou request_failed. Un échec d'un autre type donne une notice sans reason.

Skills : donnez à l'agent de longues instructions qu'il ne charge que lorsqu'il en a besoin.