Gérer les Connecteurs

Avant d'utiliser un Connecteur dans des conversations ou d'appeler ses outils, enregistrez-le. Cette page couvre le cycle de vie complet d'un Connecteur :

Testez le serveur MCP dans le Débugueur de Connecteurs, si vous souhaitez le vérifier au préalable.
Créez un Connecteur avec l'URL du serveur MCP et la portée de visibilité.
Connectez-le avec des identifiants, ou avec OAuth si le serveur MCP l'exige.
Listez les outils pour découvrir ceux exposés par le Connecteur.
Utilisez le Connecteur dans des conversations ou avec des appels directs d'outils.
Mettez-le à jour, ou supprimez-le lorsque vous n'en avez plus besoin.

Créer un Connecteur

Pour enregistrer un Connecteur MCP, envoyez un nom, une description, l'URL du serveur MCP et une portée de visibilité :

private : vous seul pouvez l'utiliser.
shared_workspace : toute personne dans le même espace de travail peut l'utiliser.
shared_org : toute personne dans l'organisation peut l'utiliser. Seuls les administrateurs de l'organisation peuvent créer et gérer ces Connecteurs.

Le name accepte jusqu'à 64 caractères : lettres, chiffres, traits de soulignement et tirets. L'API peut enregistrer le nom avec un suffixe court, par exemple my_deepwiki_8f11, et avec les tirets remplacés par des traits de soulignement. Pour faire référence au Connecteur dans les appels suivants, utilisez le name ou l'id de la réponse. Les deux fonctionnent partout où un appel accepte un nom ou un ID de Connecteur.

Dans les SDK, définissez protocol sur mcp : le même appel permet également de créer des Connecteurs HTTP.

import asyncio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        request={
            "protocol": "mcp",
            "name": "my_deepwiki",
            "description": "DeepWiki MCP connector for code repository exploration",
            "server": "https://mcp.deepwiki.com/mcp",
            "visibility": "private",
        },
    )

    print(f"ID:          {connector.id}")
    print(f"Name:        {connector.name}")
    print(f"Description: {connector.description}")
    print(f"Server URL:  {connector.server}")
    print(f"Visibility:  {connector.visibility}")
    print(f"Created at:  {connector.created_at}")
    print(f"Modified at: {connector.modified_at}")


asyncio.run(main())

import asyncio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")


async def main() -> None:
    connector = await client.beta.connectors.create_async(
        request={
            "protocol": "mcp",
            "name": "my_deepwiki",
            "description": "DeepWiki MCP connector for code repository exploration",
            "server": "https://mcp.deepwiki.com/mcp",
            "visibility": "private",
        },
    )

    print(f"ID:          {connector.id}")
    print(f"Name:        {connector.name}")
    print(f"Description: {connector.description}")
    print(f"Server URL:  {connector.server}")
    print(f"Visibility:  {connector.visibility}")
    print(f"Created at:  {connector.created_at}")
    print(f"Modified at: {connector.modified_at}")


asyncio.run(main())

L’endpoint create accepte également les champs facultatifs suivants :'

Champ	Type	Description
`title`	`string`	Titre lisible du Connecteur.
`icon_url`	`string`	URL de l'icône à associer au Connecteur.
`headers`	`object`	En-têtes HTTP envoyés avec chaque requête au serveur MCP, par exemple une clé API statique.
`oauth2_server_metadata`	`object`	Métadonnées du serveur d'autorisation OAuth2, telles que `authorization_endpoint` et `token_endpoint`. Utilisez ce paramètre lorsque le serveur ne publie pas ces métadonnées à une URL `.well-known`.
`system_prompt`	`string`	Prompt système ajouté lorsque le modèle utilise les outils de ce Connecteur.

Pour la liste complète, consultez la référence API de création de Connecteur.

Connecter un Connecteur

Un nouveau Connecteur n'est pas encore connecté : connectez-le avant de lister ou d'appeler ses outils.

Lorsque le serveur MCP ne nécessite aucun identifiant, créez des identifiants vides pour votre utilisateur (consumer_scope défini sur user) et définissez-les comme identifiants par défaut :

import asyncio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")


async def main() -> None:
    await client.beta.connectors.create_credentials_async(
        connector_id_or_name="my_deepwiki",
        consumer_scope="user",
        name="deepwiki-default",
        credentials={"headers": {}},
        is_default=True,
    )


asyncio.run(main())

import asyncio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")


async def main() -> None:
    await client.beta.connectors.create_credentials_async(
        connector_id_or_name="my_deepwiki",
        consumer_scope="user",
        name="deepwiki-default",
        credentials={"headers": {}},
        is_default=True,
    )


asyncio.run(main())

Si le serveur MCP nécessite OAuth, récupérez l'URL d'autorisation et redirigez l'utilisateur vers celle-ci pour accorder l'accès. Une fois que l'utilisateur a terminé le flux, le navigateur revient sur app_return_url.

Avertissement

Vous ne pouvez pas transmettre de tokens OAuth à l'API. Pour connecter un Connecteur OAuth sans construire ce flux, utilisez Studio.

La réponse contient deux champs :

auth_url : l’URL vers laquelle rediriger l’utilisateur.
ttl : la durée de validité de l'URL, en secondes.

import asyncio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")


async def main() -> None:
    result = await client.beta.connectors.get_auth_url_async(
        connector_id_or_name="gmail",
        app_return_url="https://myapp.example.com/oauth/callback",
    )
    print(f"Auth URL: {result.auth_url}")
    print(f"TTL:      {result.ttl}s")


asyncio.run(main())

import asyncio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")


async def main() -> None:
    result = await client.beta.connectors.get_auth_url_async(
        connector_id_or_name="gmail",
        app_return_url="https://myapp.example.com/oauth/callback",
    )
    print(f"Auth URL: {result.auth_url}")
    print(f"TTL:      {result.ttl}s")


asyncio.run(main())

Récupérer les Connecteurs

Obtenir un Connecteur

Obtenez un Connecteur par son nom ou son ID. Lorsque les outils sont déjà découverts, la réponse les inclut dans un tableau tools. Pour lister ou actualiser les outils, consultez Lister les outils.

import asyncio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")


async def main() -> None:
    # By name
    connector_by_name = await client.beta.connectors.get_async(
        connector_id_or_name="my_deepwiki"
    )
    print(f"Name: {connector_by_name.name}")
    print(f"ID:   {connector_by_name.id}")

    # By ID (equivalent)
    connector_by_id = await client.beta.connectors.get_async(
        connector_id_or_name=str(connector_by_name.id)
    )
    print(f"Description: {connector_by_id.description}")


asyncio.run(main())

import asyncio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")


async def main() -> None:
    # By name
    connector_by_name = await client.beta.connectors.get_async(
        connector_id_or_name="my_deepwiki"
    )
    print(f"Name: {connector_by_name.name}")
    print(f"ID:   {connector_by_name.id}")

    # By ID (equivalent)
    connector_by_id = await client.beta.connectors.get_async(
        connector_id_or_name=str(connector_by_name.id)
    )
    print(f"Description: {connector_by_id.description}")


asyncio.run(main())

Lister les Connecteurs

La liste utilise la pagination par curseur : passez le next_cursor d'une page pour obtenir la suivante.

Pour filtrer les résultats, passez query_filters. Par exemple, supports_mcp: true renvoie uniquement les Connecteurs qui exposent des outils MCP.

import asyncio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")


async def main() -> None:
    # List all connectors (first page)
    page = await client.beta.connectors.list_async(page_size=10)
    all_connectors = list(page.items)

    for c in page.items:
        print(f"  - {c.name} ({c.id})")

    # Fetch remaining pages
    while page.pagination.next_cursor:
        page = await client.beta.connectors.list_async(
            page_size=10,
            cursor=page.pagination.next_cursor,
        )
        all_connectors.extend(page.items)

    print(f"Total: {len(all_connectors)} connectors")

    # Filter: MCP connectors only
    mcp_page = await client.beta.connectors.list_async(
        page_size=10,
        query_filters={"supports_mcp": True},
    )
    print(f"MCP connectors: {len(mcp_page.items)}")


asyncio.run(main())

import asyncio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")


async def main() -> None:
    # List all connectors (first page)
    page = await client.beta.connectors.list_async(page_size=10)
    all_connectors = list(page.items)

    for c in page.items:
        print(f"  - {c.name} ({c.id})")

    # Fetch remaining pages
    while page.pagination.next_cursor:
        page = await client.beta.connectors.list_async(
            page_size=10,
            cursor=page.pagination.next_cursor,
        )
        all_connectors.extend(page.items)

    print(f"Total: {len(all_connectors)} connectors")

    # Filter: MCP connectors only
    mcp_page = await client.beta.connectors.list_async(
        page_size=10,
        query_filters={"supports_mcp": True},
    )
    print(f"MCP connectors: {len(mcp_page.items)}")


asyncio.run(main())

Lister les outils

Listez les outils d'un Connecteur pour vérifier leurs noms exacts avant de les utiliser dans des conversations ou de les appeler directement.

Information

Connectez le Connecteur avant de lister ou d'appeler ses outils.

import asyncio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")


async def main() -> None:
    tools = await client.beta.connectors.list_tools_async(
        connector_id_or_name="my_deepwiki",
    )
    for tool in tools:
        print(f"  - {tool.name}: {tool.description}")


asyncio.run(main())

import asyncio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")


async def main() -> None:
    tools = await client.beta.connectors.list_tools_async(
        connector_id_or_name="my_deepwiki",
    )
    for tool in tools:
        print(f"  - {tool.name}: {tool.description}")


asyncio.run(main())

L’endpoint prend en charge les paramètres de requête suivants :

Paramètre	Valeur par défaut	Description
`page_size`	`100`	Nombre d’outils par page.
`refresh`	`false`	Récupère à nouveau les outils depuis le serveur MCP au lieu d'utiliser le cache.
`pretty`	`false`	Retourne une charge utile simplifiée avec uniquement `name`, `description`, `annotations` et un `inputSchema` compact.
`credentials_name`	Identifiants par défaut	Nom des identifiants à utiliser.

Mettre à jour un Connecteur

Envoyez uniquement les champs que vous souhaitez modifier. Le connector_id doit être l'ID, pas le nom. Dans les SDK, définissez également protocol sur mcp.

import asyncio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")


async def main() -> None:
    connector_id = "a1b2c3d4-5678-90ab-cdef-1234567890ab"

    updated = await client.beta.connectors.update_async(
        connector_id=connector_id,
        request_body={
            "protocol": "mcp",
            "description": "Updated: DeepWiki connector for code exploration",
        },
    )
    print(f"New description: {updated.description}")


asyncio.run(main())

import asyncio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")


async def main() -> None:
    connector_id = "a1b2c3d4-5678-90ab-cdef-1234567890ab"

    updated = await client.beta.connectors.update_async(
        connector_id=connector_id,
        request_body={
            "protocol": "mcp",
            "description": "Updated: DeepWiki connector for code exploration",
        },
    )
    print(f"New description: {updated.description}")


asyncio.run(main())

Vous pouvez mettre à jour ces champs : title, description, server, icon_url, system_prompt et auth_methods. Vous ne pouvez modifier server que sur les Connecteurs privés. Vous ne pouvez pas changer le nom d'un Connecteur.

Supprimer un Connecteur

La suppression d'un Connecteur est définitive. Les agents qui y font référence perdent l'accès à ses outils.

import asyncio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")


async def main() -> None:
    connector_id = "a1b2c3d4-5678-90ab-cdef-1234567890ab"

    result = await client.beta.connectors.delete_async(
        connector_id=connector_id,
    )
    print(f"Delete response: {result.message}")


asyncio.run(main())

import asyncio
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")


async def main() -> None:
    connector_id = "a1b2c3d4-5678-90ab-cdef-1234567890ab"

    result = await client.beta.connectors.delete_async(
        connector_id=connector_id,
    )
    print(f"Delete response: {result.message}")


asyncio.run(main())