Connecting clients

Every client connects to the same address, https://<your-ai-os>/mcp, and signs in with your company account. The console shows the steps with your installation’s address and client ids filled in: click Connect your AI assistant at the top right (on a narrow screen Connect AI). The examples here use ai-os as the connection’s name and https://ai.example.com/mcp as the address.

The dialog asks Which assistant do you use? It offers Claude (claude.ai and the Claude apps) and Copilot or another app first, and the tools for developers under For developers. Which of these your installation lists is set by its operators (keycloak.agentClients); by default Claude Code, Codex, Cursor, claude.ai, Hermes and AI OS Workbench.

Claude Code

If your installation offers the Claude Code plugin, the dialog shows it first. It brings the connection, AI OS’s own skills and the commands share, new-server and new-skill in one go:

claude plugin marketplace add https://ai.example.com/api/claude/marketplace.json
claude plugin install <name>@<name>

Without the plugin, add the connection once:

claude mcp add --transport http --scope user --client-id claude-code ai-os https://ai.example.com/mcp

Then sign in: type /mcp in Claude Code, pick the connection and choose Sign in, or run:

claude mcp login ai-os

Codex

codex mcp add ai-os --url https://ai.example.com/mcp --oauth-client-id codex
codex mcp login ai-os

Cursor

Put the address into ~/.cursor/mcp.json (or .cursor/mcp.json for one project):

{ "mcpServers": { "ai-os": { "url": "https://ai.example.com/mcp" } } }

Cursor registers itself, so it needs no client id. Then open Cursor’s Settings → MCP and click Needs login.

Claude (claude.ai and the Claude apps)

1. In Claude, open Settings, then Connectors, and click Add custom connector.
2. Enter a name and the address.
3. Under Advanced settings, paste the client id from the dialog into OAuth Client ID and leave OAuth Client Secret empty.
4. Click Add, then Connect.

AI OS Workbench

AI OS Workbench is AI OS’s own command line (ADR 0074). It needs Node.js 22.19 or newer:

npm config set @labtagon:registry https://npm.labtagon.cloud/
npm install -g @labtagon/workbench
wb setup --url https://ai.example.com
wb

Another app

Copilot or another app shows the address to send to your IT team: they connect it for you. Any other MCP client works with the address and the client id the dialog shows (Copy client ID), with the secret left empty. Clients that are not listed sign in at https://<your-ai-os>/mcp/direct.

Details for your IT team in the dialog says what the gateway speaks: MCP over Streamable HTTP, OAuth with PKCE, and the protected-resource metadata of RFC 9728.

Choosing the profile

When the client signs in and you have more than one profile, AI OS asks which one it uses. It gets only what is in that profile. See Profiles.

How long a sign-in lasts

When AI OS issues the clients’ tokens itself (ADR 0059):

• The access token lasts 10 minutes; the client renews it by itself.
• The refresh token lasts 30 days and is replaced at every use. After 30 days without use you sign in again.
• A sign-in lasts at most 90 days.

Under Connections in Studio you see each connected client and can end its sign-in.

Clients that register themselves

Besides the listed clients, a client can identify itself by a client id metadata document or register itself (dynamic client registration). Such a client waits until a person or an administrator approves it; administrators find them under Control Panel → Clients.

When something does not work

Something not working? See common fixes in the dialog lists what usually helps. Tools are named <server>__<tool>, for example files__upload (How tools are named).