Managing Connectors

Before you can use a Connector in conversations or call its tools, you need to register it. This page walks through the full Connector lifecycle:

Create a Connector with the MCP server URL and visibility scope.
Authenticate (if the MCP server requires OAuth).
List tools to discover what the Connector exposes.
Use the Connector in conversations or via direct tool calls.
Update or delete when the Connector is no longer needed.

Create a Connector

private — only the creator can use it.
shared_workspace — anyone in the same Workspace.
shared_org — anyone in the organization. Only organization admins can create and manage these Connectors.

You can reference a Connector by its name or its UUID, because Connector names are unique within a Workspace.

The name accepts up to 64 characters, alphanumeric with underscores and dashes only.

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(
        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"Auth type:   {connector.auth_type}")
    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(
        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"Auth type:   {connector.auth_type}")
    print(f"Created at:  {connector.created_at}")
    print(f"Modified at: {connector.modified_at}")


asyncio.run(main())

The create endpoint also accepts these optional fields:

Field	Type	Description
`icon_url`	`string`	URL of the icon to associate with the Connector.
`headers`	`object`	HTTP headers sent with every request to the MCP server, for example static API keys.
`auth_data`	`object`	OAuth2 `client_id` and `client_secret` — required when the MCP server uses OAuth.
`system_prompt`	`string`	System prompt injected when the tools of this Connector are used.

Authenticate a Connector

If the MCP server requires OAuth, retrieve the authorization URL and redirect the user so they can grant access. After the user completes the auth flow, they are redirected to app_return_url.

caution

Passing tokens programmatically is not supported. Use AI Studio to authenticate Connectors instead.

The response includes two fields:

auth_url — the URL to redirect the user to.
ttl — how long the URL remains valid, in seconds.

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())

Retrieve Connectors

Get a single Connector

Retrieve a Connector by its name or UUID. The response includes a tools array with the MCP tools the Connector exposes, if already discovered. To explicitly list or refresh tools, see the list tools section.

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 UUID (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 UUID (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())

List all Connectors

List Connectors with cursor-based pagination. Use next_cursor to fetch subsequent pages.

Pass query_filters to filter results. For example, active: true returns only Connectors that are active for your user and Workspace.

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 active connectors only
    active_page = await client.beta.connectors.list_async(
        page_size=10,
        query_filters={"active": True},
    )
    print(f"Active connectors: {len(active_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 active connectors only
    active_page = await client.beta.connectors.list_async(
        page_size=10,
        query_filters={"active": True},
    )
    print(f"Active connectors: {len(active_page.items)}")


asyncio.run(main())

List tools

List the tools a Connector exposes. This helps verify available tool names before using them in conversations or calling them directly.

note

If the Connector requires authentication, the user must complete the auth flow before listing or calling its tools.

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())

The endpoint supports these query parameters:

Parameter	Default	Description
`page`	`1`	Page number (offset-based pagination).
`page_size`	`100`	Number of tools per page.
`refresh`	`false`	Re-fetch tools from the MCP server instead of using the cache.
`pretty`	`false`	Return a simplified payload with only `name`, `description`, `annotations`, and a compact `inputSchema`.

Update a Connector

Update one or more fields on a Connector. Only include the fields you want to change. The connector_id must be the UUID, not the name.

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,
        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,
        description="Updated: DeepWiki connector for code exploration",
    )
    print(f"New description: {updated.description}")


asyncio.run(main())

You can update these fields: name, description, server, icon_url, system_prompt, headers, and auth_data.

Delete a Connector

Delete a Connector permanently. Any Agents referencing it lose access to its tools.

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())