Connectors & MCP | Mistral Docs

Connectors

Coming soon

Connectors expose external systems to the agent over MCP (Model Context Protocol) using Mistral's Connectors primitive. The agent can call them like any other tool. They are added to the Harness with:

from mistralai.agents import agents

harness = agents.Harness(connectors=[agents.connector("deepwiki")])

from mistralai.agents import agents

harness = agents.Harness(connectors=[agents.connector("deepwiki")])

It requires such a connector to be :

made available on the organization of the user who will run a session against the agent (by the user or an admin) on Mistral Studio
connected by the user who runs a session against the agent: the users must have followed the connection flow, allowing the platform to use their own permission on the 3rd party application.

Information

For some connectors (depending on the part of OAuth2 protocol the 3rd party implements), this connection flow might be replayed periodically by the user.

Connectors and your deployment

A connector calls the third party as the user running the session, not as whoever started the worker. So the deployment your worker registers on has to be hardened, or anyone could register a worker there and act on your users' behalf.

Hardening is a flag on the deployment: once it is on, registration is closed. Pins are the principals — users or service accounts — allowed to register a worker on it anyway, and a hardened deployment with no pin admits nobody. Workflows covers the full model in hardened deployments.

Adding a connector is what triggers this. An agent without one is unaffected.

In the run modes that use a worker:

agents serve hardens the deployment the first time it registers and pins it to you. You pass nothing.
agents deploy hardens the deployment for you: an agent that acts on behalf of the session user is deployed hardened unless you pass --no-hardened. Without hardening the worker cannot register, and the deployment never comes up.

Both pin a single principal, so a teammate who serves the same agent name is refused. Give each person their own agent name with agents serve --name. If registration is refused for any other reason, the error carries a link to authorize the principal that was turned away.

Every connector a user has

agents.connector(...) names one connector when you write the agent. agents.all_connectors() names none. It selects the connectors of the user who runs the session:

from mistralai.agents import agents

harness = agents.Harness(connectors=[agents.all_connectors()])

from mistralai.agents import agents

harness = agents.Harness(connectors=[agents.all_connectors()])

A connector is in that set when all three are true:

It is active for the user's organization and workspace.
It exposes an MCP tool interface. A connector without one can not become agent tools.
The connector is connected for this user, meaning the user has completed the connection flow, which is an OAuth2 consent flow, or the user or admin has provided static credentials. A connection whose credential has expired counts as not connected.

The set is resolved when the session starts, under the session user's identity. Two users of the same agent therefore get their own connectors. Connectors the user has not connected yet stay out of the set, and no authorization flow starts at session start. The agent can still find them and ask the user to connect one, which is the only path that starts a flow.

Parameters

Parameter	Type	Description
`exclude`	`Sequence[str]`	Connector names to drop from the set. Defaults to none.
`max_connectors`	`int \| None`	Cap on the number of discovered connectors the agent mounts. Only connectors the user can actually use count against it, and a connector you name yourself is never capped away. The connectors kept are the first by name, so the cap is reproducible. Defaults to no cap.
`auto_auth`	`bool`	Whether the agent may ask the user to connect a connector it found unconnected. Defaults to `True`.
`allow_mcp_ui`	`bool`	Whether to surface MCP app resources for every discovered connector. Defaults to `False`.

all_connectors() always runs on behalf of the session user. It can not be combined with run_as="deployment" connectors, and the SDK refuses that combination when it compiles the harness. agents deploy hardens an agent using only all_connectors() by default, including with auto_auth=False. An explicit --no-hardened still overrides this default.

Connector tools do not enter the agent's context up front. The agent gets one search tool, search_tool_functions, and loads the declaration of a connector tool only when the task needs it. This is progressive tool discovery, and it is always on. Each connector costs one line of the system prompt, so a hundred connectors add a few thousand characters, not their tool lists.

Warning

A large set still has a cost: each search runs over more tools, so the agent can pick a tool from an unrelated connector. When you know which connectors the agent needs, name them with agents.connector(...), or drop the others with exclude: the agent then gets a set you chose. max_connectors is a safety limit, not a way to choose. It keeps the first connectors by name, which says nothing about which ones the task needs.

Give one connector its own options

all_connectors() applies the same options to every connector it finds. To treat one connector differently, name it in the same list. The named declaration wins for that connector, and the selection covers the rest:

from mistralai.agents import agents

harness = agents.Harness(
    connectors=[
        agents.all_connectors(exclude=["jira"], max_connectors=10),
        agents.connector("notion", credentials_name="team", allow_mcp_ui=True),
    ]
)

from mistralai.agents import agents

harness = agents.Harness(
    connectors=[
        agents.all_connectors(exclude=["jira"], max_connectors=10),
        agents.connector("notion", credentials_name="team", allow_mcp_ui=True),
    ]
)

This agent gets:

Notion with the team credential and MCP apps enabled, because the named declaration sets both.
Every other active, MCP-capable, connected connector of the session user, except Jira, with the default options and no MCP apps. max_connectors=10 keeps at most ten of them: the first ten by name, ignoring case. Notion does not count against the cap, because you named it.

Use this when one connector needs a credential the others do not use, or when only one connector has an MCP app worth showing. Setting allow_mcp_ui on the selection instead enables MCP apps for every discovered connector, which shows a side app after each matching tool call across the whole set.

A named connector does not have to be in the discovered set. Name a connector the user has not connected, and the agent can still ask for it.

Credential resolution and identity modes

Work in progress

Bring your own MCP server

Note

Note that Connectors support any custom MCP server, not just Mistral's built-in catalog. Use this when the authentication is made with a static credentials - that Connectors can not support for now.

Most servers need a credential. auth_header_env_vars maps a header name to the name of an environment variable holding that header's complete value:

from mistralai.agents import agents

harness = agents.Harness(
  mcps={
      "github_copilot": agents.RemoteMCP(
          url="https://api.githubcopilot.com/mcp/",
          auth_header_env_vars={"Authorization": "GITHUB_MCP_TOKEN"},
      )
  }
)

from mistralai.agents import agents

harness = agents.Harness(
  mcps={
      "github_copilot": agents.RemoteMCP(
          url="https://api.githubcopilot.com/mcp/",
          auth_header_env_vars={"Authorization": "GITHUB_MCP_TOKEN"},
      )
  }
)

Here the agent sends Authorization: <value of GITHUB_MCP_TOKEN> on every request to that server, so the variable holds the whole header value - Bearer ghp_..., scheme included, not just the token. Any header works the same way, so a server wanting X-API-Key is {"X-API-Key": "MY_SERVER_KEY"}.

You pass the variable's name, never its value. The credential is read where the agent runs, at the moment the request is made, so it is never written into session state and never travels with a resumed session. It does mean the variable has to exist wherever the agent runs - your shell for a local run, the worker's environment for a served or deployed one. If it is unset or empty the session fails with a message naming the variable:

MCP source 'github_copilot' declares environment variable(s) GITHUB_MCP_TOKEN, which are unset or empty here

MCP source 'github_copilot' declares environment variable(s) GITHUB_MCP_TOKEN, which are unset or empty here