Connectors and MCP

The agent calls external services through connectors, services from Mistral's connector catalog that act as the user who runs the session, and through MCP servers that you reach with a credential you hold. Use a connector when the catalog has the service; use your own MCP server when it does not, or when the server takes a static credential, such as an API key.

Add a connector to the agent by name:

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")])

The agent can then call the connector's tools like any other tool. The connector must be:

• available on the organization of the user who runs a session against the agent. The user or an admin makes it available on Mistral Studio.
• connected by the user who runs the session: the user has followed the connection flow, which lets the platform act with their permissions in the third-party service.

If no connector has that name, or a connector fails to load when the session starts, the session starts without it. The model is told the connector is unavailable, and you get an agents.Notice, such as Connector 'Lienar' is unavailable: no connector has this name. Did you mean 'linear'?. Check its details["status"], not its message: "unsupported" means no retry fixes the connector in this session, and "unavailable" means it may recover.

agents.all_connectors() selects every connector available to the user who runs the session, when the session starts:

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

Two users of the same agent therefore get their own connectors. Name the connectors you know the agent needs, or drop the others with exclude=. See agents.all_connectors for its options.

A connector acts as the user who runs the session. When that user has not connected it, the turn waits on a sign-in until your app answers it: see Callbacks and Sign-ins.

Declare the server yourself in mcps= when it takes a static credential that you, the developer, hold:

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 key of mcps= names the server, and model_access sets how the model calls its tools, as for your own tools; see Tools.

auth_header_env_vars maps a header name to the name of an environment variable that holds the header's complete value:

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_..."
        )
    },
)

You pass the variable's name, never its value. The SDK reads the variable where the agent runs, on each request, so the credential never enters the session. A missing variable fails before any session starts. With agents deploy, bind it to a workspace secret: see Deploy.

A server that rejects the credential, cannot be reached or never answers does not stop the run. The session drops that server for the turn, tells the model why, and logs a warning naming the server and the cause. The session retries the server before later turns, with backoff after repeated failures. The session also gives you an agents.Notice for the server, whose source is the server's ID (its key in mcps unless you set id=) and whose details carry the reason. Continuing the example above, in an async function:

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

reason is one of credential_rejected (HTTP 401 or 403), credential_unavailable, unreachable, timeout, invalid_catalog or request_failed. A failure of another kind gives a notice without a reason.

Skills: give the agent long instructions that it loads only when it needs them.