Manage connectors

Before you use a connector in conversations or call its tools, register it. This page covers the full lifecycle of a connector:

Test the MCP server in the Connectors Debugger, if you want to check it first.
Create a connector with the MCP server URL and visibility scope.
Connect it with credentials, or with OAuth if the MCP server requires it.
List tools to discover what the connector exposes.
Use the connector in conversations or with direct tool calls.
Update it, or delete it when you no longer need it.

Create a connector

To register an MCP connector, send a name, a description, the MCP server URL, and a visibility scope:

private: only you can use it.
shared_workspace: anyone in the same workspace can use it.
shared_org: anyone in the organization can use it. Only organization admins can create and manage these connectors.

The name accepts up to 64 characters: letters, digits, underscores, and dashes. The API can store the name with a short suffix, for example my_deepwiki_8f11, and with dashes replaced by underscores. To reference the connector in the next calls, use the name or id from the response. Both work wherever a call accepts a connector name or ID.

In the SDKs, set protocol to mcp: the same call also creates HTTP connectors.

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

The create endpoint also accepts these optional fields:

Field	Type	Description
`title`	`string`	Human-readable title of the connector.
`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 a static API key.
`oauth2_server_metadata`	`object`	OAuth2 authorization server metadata, such as `authorization_endpoint` and `token_endpoint`. Use it when the server doesn't publish this metadata at a `.well-known` URL.
`system_prompt`	`string`	System prompt added when the model uses the tools of this connector.

For the full list, see the create connector API reference.

Connect a connector

A new connector isn't connected yet: connect it before you list or call its tools.

When the MCP server needs no credentials, create empty credentials for your user (consumer_scope set to user) and make them the default:

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

If the MCP server requires OAuth, get the authorization URL and redirect the user to it to grant access. After the user completes the flow, the browser returns to app_return_url.

Warning

You can't pass OAuth tokens to the API. To connect an OAuth connector without building this flow, use Studio.

The response contains two fields:

auth_url: the URL to redirect the user to.
ttl: how long the URL stays 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 connector

Get a connector by its name or ID. When the tools are already discovered, the response includes them in a tools array. To list or refresh the tools, see List tools.

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

List connectors

The list uses cursor-based pagination: pass the next_cursor of a page to get the next one.

To filter the results, pass query_filters. For example, supports_mcp: true returns only the connectors that expose MCP tools.

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

List tools

List the tools of a connector to check their exact names before you use them in conversations or call them directly.

Information

Connect the connector before you list or call 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_size`	`100`	Number of tools per page.
`refresh`	`false`	Fetch the tools from the MCP server again instead of using the cache.
`pretty`	`false`	Return a simplified payload with only `name`, `description`, `annotations`, and a compact `inputSchema`.
`credentials_name`	Default credentials	Name of the credentials to use.

Update a connector

Send only the fields that you want to change. The connector_id must be the ID, not the name. In the SDKs, also set protocol to 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())

You can update these fields: title, description, server, icon_url, system_prompt, and auth_methods. You can change server on private connectors only. You can't change the name of a connector.

Delete a connector

Deleting a connector is permanent. Agents that reference 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())