> For the complete documentation index, see [llms.txt](https://docs.artific.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.artific.nl/en/for-administrators/assistants/connectors.md).

# Connectors

Connectors give an assistant access to actions on an external server, using the Model Context Protocol (MCP). Configured on the **Connectors** tab of an assistant.

This page is technical by necessity. If you are looking for the simpler options, see [Tools](/en/for-administrators/assistants/tools.md).

## What a connector is

A connector points at an MCP server. Once connected, the platform asks that server what it can do and gets back a list of **actions**. You then decide which of those actions the assistant is allowed to use.

The same idea appears in three places:

| Where                                           | Scope                                                                                                                                        |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| An assistant's **Connectors** tab               | Just that assistant.                                                                                                                         |
| An AI Toolbox element's **Connectors** tab      | Just that element.                                                                                                                           |
| **Organization management → Shared connectors** | Available to the whole organisation, so it can be reused. See [Shared connectors](/en/for-administrators/organization/shared-connectors.md). |

## Adding a connector

From the **Connectors** tab, choose **Add connector → Create custom**, or **Use existing** to pick one your organisation already shares.

| Field              | What to enter                                                                           |
| ------------------ | --------------------------------------------------------------------------------------- |
| **Name**           | A recognisable name, for example `Ticketing connector`.                                 |
| **Server URL**     | The MCP endpoint, for example `https://mcp.example.com/mcp`.                            |
| **Transport**      | **Streamable HTTP (recommended)** for current servers, **SSE (legacy)** for older ones. |
| **Authentication** | How the platform proves who it is. See below.                                           |

### Authentication options

#### None

For servers that need no credentials. Nothing further to fill in.

#### Bearer token

| Field                      | What to enter                                                                                                              |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Bearer token**           | The token itself. It is stored encrypted and masked after saving. When editing, leave it blank to keep the existing token. |
| **Auth header (optional)** | The header to send it in, for example `x-api-key`. Leave empty to use the standard `Authorization: Bearer` header.         |

#### OAuth: Org-wide

One shared credential for the whole organisation. Everyone using the assistant acts through the same account.

| Field              | What to enter                                                                               |
| ------------------ | ------------------------------------------------------------------------------------------- |
| **Token endpoint** | For example `https://auth.example.com/oauth/token`.                                         |
| **Client ID**      | From your OAuth application registration.                                                   |
| **Client secret**  | On edit, leave blank to keep the existing secret.                                           |
| **Scopes**         | Space-separated, for example `read write`. Leave blank if the server does not require them. |

#### OAuth: Per-user

Each person authorises their own account, so the assistant acts as them and sees only what they are allowed to see. Choose this whenever the external system has per-user permissions worth respecting.

**Auto-discover (MCP-native)** is the easy path: enter a name and URL, and the platform finds the endpoints and registers itself automatically. Use it for any standards- compliant remote MCP server.

Switch auto-discover off and you configure it by hand:

| Field                        | What to enter                                                                                     |
| ---------------------------- | ------------------------------------------------------------------------------------------------- |
| **Authorization endpoint**   | Where users are sent to authorise.                                                                |
| **Token endpoint**           | Where the platform exchanges the code.                                                            |
| **Client ID**                | The public client ID from your registration.                                                      |
| **Client secret (optional)** | Only for providers that require a confidential client. Leave blank for public clients using PKCE. |
| **Scopes**                   | Space-separated.                                                                                  |

After saving, each user connects their own account through a sign-in window the first time they need it. Until they do, the connector shows **Not connected** and the chat prompts them to connect.

## Testing before saving

**Test connection** probes the server and reports **Connected: N actions available**, or explains the failure. You can already allow or block individual actions from the test result before saving.

{% hint style="warning" %}
A successful test is required before you can save a new connector, and before saving any change that affects the connection itself: URL, transport, authentication type, header, endpoints, scopes or a new secret. Renaming alone does not need a re-test.
{% endhint %}

## Managing actions

**Manage actions** lists everything the server exposes, each with an **Allow** / **Block** switch. Blocked actions are hidden from the assistant entirely. It does not know they exist and cannot be talked into using them.

Start restrictive. Allow the actions the assistant genuinely needs for its job and block the rest, particularly anything that writes, deletes or sends.

If the connector is inherited from your organisation's shared connectors, the actions are managed centrally and cannot be changed here. Rows blocked centrally show **Blocked by your organization**.

Use **Refresh connector** after the external server changes, to pick up new actions.

## Connector states

| State                             | What it means                                                                         |
| --------------------------------- | ------------------------------------------------------------------------------------- |
| **Connected** / **Not connected** | For per-user OAuth: whether *you* have authorised your account.                       |
| **Unreachable**                   | The platform could not contact the server. Check the URL and credentials.             |
| **Not discovered yet**            | The connector is saved but its actions have not been read. Use **Refresh connector**. |
| **Inherited** / **Shared**        | The connector comes from the organisation level rather than this assistant.           |

## Removing a connector

**Delete** disconnects it from this assistant. The confirmation names the connector so you do not remove the wrong one.