Skip to content

Connectors (MCP servers)

A connector brings the actions of an outside service into your organisation: a ticket system, a knowledge base or any other application that offers an MCP server. MCP (Model Context Protocol) is a standard by which a program offers actions an AI model can call. This page shows how to add a connector, allow its address, choose which actions the AI may use and make tools of them that people and assistants use.

Who manages connectors

Whoever may set up the organisation's tools adds, changes and refreshes connectors: the organisation's administrators (org-admin) and a custom role with write on toolbox. Deleting a connector takes delete on toolbox. Only an administrator allows the address of a new connector (below).

Open Engine room and choose the Connectors tab. From the AI Toolbox you get there too, with Connectors in the bar at the top. You see a table with each connector's Name, Server URL, Authentication and Actions: All · 12 when the AI may use every action, 8 of 12 when you chose some of them, or Not discovered yet and Unreachable while OS does not know the actions. When a connector offers no actions because an address is not allowed, it says so above the table and beside the connector's name (below). A connector a subscription installed can only be viewed here.

Add a connector

  1. Choose Add connector.
  2. Fill in:
    • Name: lower-case letters, digits, - and _, at most 32 characters. It is fixed once the connector exists.
    • Title and Description: what the connector is called in OS.
    • Server URL: the address of the MCP server, for example https://mcp.example.com/mcp.
    • Region (optional): where the server runs, such as eu or nl.

  3. Under Credential, at Sign in with, choose how the connector signs in at the server:

    Choice When
    None The server asks for no sign-in.
    Bearer token The server gives you a fixed token. Fill in the token and, if the server expects it in a header other than Authorization, the name of that header.
    OAuth — Org-wide The connector fetches a token itself with a client ID and a client secret, for the whole organisation. Fill in the Token endpoint, the Client ID, the Client secret and, where needed, the Scopes and Audience (optional).
    OAuth — Per-user Each person signs in at the service with their own account, and the actions work with that account (below).

  4. Add Headers sent with every call if needed, and Install values: fixed values for this organisation. An install value you mark as Secret is never shown again. In a header, {$name} stands for the install value of that name.

  5. Choose Add connector.

Secrets are write-only. A token, a client secret and a secret install value are stored encrypted and never shown to anyone again, you included. When editing (Edit on the connector's page) you leave such a field empty to keep what is there (Stored; leave blank to keep), or choose Replace credential to enter new ones. If you choose another way of signing in, you enter its secret again as well. Save a change with Save changes.

OS refuses a header that would bypass or leak the sign-in: Cookie, Proxy-Authorization, Authorization beside a credential, or the header the credential itself uses. A secret in the server URL is refused too. The message names the field, never the value.

Allow the address

Your organisation's AI features call no outside address the organisation has not allowed. That holds for a connector too: as long as the server's address, or the token endpoint of an OAuth sign-in, is not allowed, the connector offers no action at all.

The connector's page lists every address it uses under Hosts, marked Not allowed or Blocked by the deployment where that is so. An administrator allows an address in the rules document:

  1. Choose To the rules on the connector's page, or open User management and choose Rules document.
  2. Choose Add rule. Give the rule a name under Name, for example ticket-system, leave Effect on permit: allows and choose egress_host under Kind.
  3. Under Conditions, choose the cell Every thing, every person. Under Names, fill in the address, for example mcp.example.com, or *.example.com for every address below it: one address a line. Choose Done.
  4. Choose Save rules document.

If you cannot change rules yourself, ask an administrator: allowing an address decides where the organisation's data goes.

The address applies after a few seconds. Then choose Refresh connector on the connector's page. Blocked by the deployment is not something you can fix: the deployment's operator allows that address for no organisation.

Read the actions

After adding and after every change, OS reads the list of actions from the server, usually within a minute, and every hour after that. The connector's page shows at Actions where that stands:

State Meaning
Not discovered yet The list has not been read yet.
Being read… You asked for a new read; it is running.
Read: 12 actions The list has been read.
Reading failed The server did not answer properly. The message below says why. Often the address is not allowed or the sign-in is wrong.

Choose Refresh connector to read the list again straight away. While reading fails, the connector offers no action.

Choose which actions the AI may use

A new connector offers nothing yet: you choose first. Under Manage actions you see every action the server offers, with its description. Choose at the top:

  • Choose: only the actions you switch on. An action the server adds later joins only when you switch it on. That way a connector does not gain a capability unnoticed.
  • Everything, also what comes later: every action, including the ones the server adds later.

Choose Save. An action that is switched on is available: an assistant can be given it and you can make a tool of it. An action that is off cannot be used by anyone in the organisation. An action that is on but that the server no longer offers stays listed with Not found by the last read; switch it off to remove it.

Test versions of the actions

Under the actions is the Test versions card. Each action the connector offers can get a test version: a fixed answer or another tool, which answers instead of the action in an evaluation's runs and in trials. A conversation always uses the real action. Choose for each action what answers and choose Save test versions; that is a new version of the connector. A connector a subscription installed shows the test versions greyed.

Put an action in the toolbox

An available action is not yet a tool in the AI Toolbox. Choose Add to the toolbox beside the action. The Create new tool screen opens with Preset already chosen, over that action:

  1. Under Who is it for?, choose For people or For assistants only, and choose Continue.
  2. The Name is proposed, and the Description is the server's description. Fill in a Title and change the rest where you like.
  3. Choose Create tool.

The action then shows Tool: name, with a link to the tool.

The form someone runs the tool from follows the server: when the server changes an action's input, the form changes with it. When the server removes the action, the tool is no longer available.

Set up per-user sign-in

With OAuth — Per-user, every action works with the account of the person who uses it. First register OS as an application at the service (the provider), and fill in in OS:

  • the provider's Authorization endpoint and Token endpoint;
  • the Client ID and, if the provider asks for one, the Client secret (optional). A public client uses no secret;
  • the Scopes, separated by spaces, and the Audience (optional) if needed.

The form shows the Redirect URI. Copy it with Copy and register it at the provider: that is where a person comes back after signing in. Also allow the address of the token endpoint (above).

After that, each person connects their own account on the My connections page. Until someone has done so, a tool over such an action asks that person to sign in first. When you remove someone from the organisation, OS forgets their connection by itself.

An AI app a member connects to a group of the AI Toolbox cannot use such an action: the app works with a key, not with the person's account (Connect an AI app to a group).

Versions and restoring

Every change of the address, the headers, the install values or the chosen actions is a new version. They are listed under Versions, newest first, with the time, the address, the header names and the actions. Every change applies at once; there are no drafts.

Choose Restore at an older version to make its address, headers, install values and actions the latest. Secret install values keep what the latest version holds: if a secret was different then, you type it again. The connector's sign-in belongs to the connector itself, not to a version, and stays as it is when you restore.

Delete a connector

Choose Delete beside the connector in the table and confirm. OS refuses as long as:

  • a tool stands for one of its actions. Delete those tools first;
  • an assistant uses one of its actions. Take the action out of that assistant first.

After deleting, nobody can use the connector's actions any more.

Through the API

Everything on this page can also be done through OS's API, under /api/v1/organisations/{id}/toolbox/mcp-servers. An administrator can also allow an address with POST /api/v1/organisations/{id}/allowed-hosts and {"host": "mcp.example.com"}; that adds the rule to the rules document (The rules document).