Your connections¶

OS has three kinds of connection you make yourself:

• Your own account at an outside service. Some tools in the AI Toolbox work with your own account at a service, such as a ticket system. You connect that account once, and after that the tools use it when you run them.
• An AI app you connect to a group of the AI Toolbox. An AI app on your own computer, such as Claude Code or Cursor, can use the tools of a group. Each connection has a key of its own.
• An AI app that works in OS itself. An AI app such as Claude Code, Claude Desktop or Cursor can work in your organisations with your rights: look up members, make an assistant, change a group. You sign in from the app; there is no key.

You see and manage only your own connections. The first two are on the My connections page and are open to everyone who may use the AI Toolbox, in an organisation whose service includes the AI Toolbox. The third is on the Work from an AI app page and works in every organisation that allows AI apps.

Open My connections¶

Open AI Toolbox and choose My connections in the bar at the top. After signing in at a service you also come back here by yourself.

Connect your own account¶

Under My connections you see every service for which one of your tools asks for a login of your own, marked Connected or Not connected. If it says None of your tools asks for a login of your own., there is nothing to connect.

1. Choose Connect beside the service.
2. Your browser goes to the service's sign-in page. Sign in and give permission.
3. You come back to My connections, with the message Connected to "name". If you declined, the message says the connection was declined.

From then on the service's tools work with your account, when you run them in the toolbox and when an assistant uses them for you. While you are not connected, such a tool in the toolbox says you must connect your own account first. An assistant can then give you a link to sign in; afterwards you see here whether it worked.

Disconnect. Choose Disconnect and confirm. OS forgets your login; the service itself is not told. If you also want to revoke the access there, do so at the service.

If a service shows Not connected again although you had connected, your login at the service has expired or been revoked. Choose Connect again.

Connect an AI app to a group¶

You connect an AI app to one group of the AI Toolbox. The app gets the tools of that group you may use at that moment. A tool added to the group later reaches the app only with a new connection.

1. Open the group in the AI Toolbox and choose Connect an AI app in the bar at the top.
2. Fill in a Name you recognise the connection by, for example Laptop, Claude Code.
3. Choose Valid until: 30 days ahead by default, at most 90 days. After that the connection stops working and you make a new one.
4. Choose Make the key.

The screen then shows, only now:

• the connection's Address;
• the Key. Keep it like a password: whoever has it uses the group's tools as you. OS never shows it again;
• a command for Claude Code and a block for Cursor, with the address and the key filled in.

Under Not in this connection the screen names every tool of the group the app does not get, and why. An AI app cannot use a tool that works with your own account at a service, nor a tool that needs more than itself, such as knowledge or a model. A datastore shared with you the app can only read.

If it says This group is not linked to a toolset yet, the group cannot be connected to an AI app yet. Ask an administrator to link the group to a toolset first.

Claude Code¶

Copy the command under Claude Code and run it in a terminal. It looks like this, with your connection's address and key:

claude mcp add --transport http customer-service \
    https://<address>/api/v1/mcp/toolsets/customer-service \
    --header "Authorization: Bearer ack_..."

After that, claude mcp list shows the connection, and Claude Code can use the group's tools.

Cursor¶

Copy the block under Cursor into Cursor's MCP file (.cursor/mcp.json in your project, or ~/.cursor/mcp.json for all your projects). If it already lists servers, add only this connection's entry to mcpServers:

{
  "mcpServers": {
    "customer-service": {
      "url": "https://<address>/api/v1/mcp/toolsets/customer-service",
      "headers": { "Authorization": "Bearer ack_..." }
    }
  }
}

Claude Desktop¶

Claude Desktop cannot use a connection to a group: its custom connectors sign in with OAuth and have no field for the key. With Claude Desktop you can work in OS itself.

A new secret, or ending the connection¶

Under AI apps on My connections you see every AI app you connected to a group, with the group, the start of the key and when the connection expires.

• New secret. If you lost the key, or someone else may have seen it, choose New secret. The old key stops working at once; the new one is shown once, and the connection expires on the same day as before. Put the new key in your AI app.
• End. Choose End and confirm. The AI app can no longer use the group's tools afterwards.

Whoever sets up your organisation's AI Toolbox can end your connections too.

When you may no longer use the toolbox¶

OS ends your connections to groups by itself when you may no longer use the AI Toolbox: when your membership is deactivated or removed, when you lose the right to the AI Toolbox, or when the organisation's service no longer includes the AI Toolbox. When you are removed from the organisation, OS also forgets the logins of your own accounts at outside services.

Use OS from an AI app¶

An AI app can also work in OS itself, with your rights: look up members, make an assistant, change a group. You connect the app once and it then works in every organisation you belong to that allows AI apps. What you may not do, the app may not do either.

Open the Work from an AI app page from the menu under your name, or with the Work from an AI app button on My connections. Both are there as soon as one of your organisations allows AI apps.

Under Where it works you see per organisation what an administrator chose:

If every organisation is Off, the page says none of your organisations allows AI apps. An administrator of your organisation can turn it on (Organisation settings).

Connect the app¶

1. Under Connect an AI app, copy the Address. If the app only needs to do one thing, first pick an Area, such as Members, Groups, AI assistants or Settings: with fewer tools the app chooses better.
2. Choose your app's tab and follow what it says:
   • Claude Code: run the command in a terminal, start Claude Code and type /mcp.
   • Claude Desktop: in Claude, open Settings › Connectors, choose Add custom connector, fill in Artific OS as the name and the address as the URL, and choose Connect.
   • Cursor: put the block in your project's .cursor/mcp.json, or in ~/.cursor/mcp.json for all your projects.
   • Other app: any app that supports MCP over HTTP with sign-in (OAuth) can connect with the address. An app that can only send a fixed key in a header cannot connect.
3. The app opens your browser. Sign in to OS as usual and choose Give access. The app's name on that page is the one the app gives itself: only give access if you just started the app yourself.

For Claude Code the command looks like this:

claude mcp add --transport http artific-os https://<address>/api/v1/mcp

What the app changes is in the organisation's audit log with your name and the app's. The app's provider, such as Anthropic or Cursor, sees what the app reads, just as it sees what you paste into it yourself.

Disconnect an app¶

Under Connected apps you see every app that worked in your organisations with your account, after its first call: when you first and last used it and in which organisations. Choose Disconnect and confirm. The app can then do nothing more in your organisations, starting now. To use it again, sign in again from the app.

An administrator can disconnect an app of yours too, but only in the organisation they manage; in your other organisations the app keeps working.

Through the API¶

Your own logins: GET /api/v1/organisations/{id}/toolbox/connections lists them, and POST, GET and DELETE …/toolbox/mcp-servers/{name}/authorization begin, read and forget one. Your AI apps connected to a group: POST …/toolbox/mcp-connections with group, label and expires_at makes a connection and returns the key once; GET …/toolbox/mcp-connections lists them, POST …/mcp-connections/{id}/rotate makes a new secret and DELETE …/mcp-connections/{id} ends one. The AI apps that work in OS: GET /api/v1/me/mcp-clients lists them and DELETE /api/v1/me/mcp-clients/{client_id} disconnects one.