Turn on AI clients

AI clients such as Claude Code connect to the platform over MCP at https://api.example.com/mcp and act as the person who signs in — see Connect an AI client. The interface is off until a platform administrator turns it on. Changing it needs kernel/mcpSettings/manage at the platform root, which Platform Owner and Platform Contributor hold.

Turn the interface on or off

Open Settings → Platform Settings and the AI clients tab, and use Enable the MCP interface for this platform. The change is saved at once.

Once it is on, anyone who can sign in to the portal can connect a client, with exactly their own permissions. Turning it off stops connected clients within about fifteen seconds; the server then answers every MCP request with 404 and mcp_disabled.

Until someone uses the switch, the tab says the value comes from the platform's configuration (Mcp:Enabled, off unless an operator sets it). Using the switch records a decision that the configuration no longer overrides.

Allow clients to register

Most AI clients cannot be given a client ID in advance, so they register one themselves when they first connect: Claude Code, opencode, the generic Config file configuration on the setup page, and Claude Desktop's custom connector. Only the bridge configurations — Codex, and Claude Desktop's configuration file — sign in with the ready-made client described under Installation settings and do not register.

A registration is refused unless every address it would return the user to is on a host in Hosts allowed to register a client. The list starts empty, so until you add hosts only the bridge configurations can sign in. Add:

• localhost and 127.0.0.1 for clients that run on the user's computer, such as Claude Code and opencode. They return the user to a local address, and which of the two they use depends on the client.
• claude.ai for Claude's hosted clients, such as the Claude Desktop connector.

A listed host lets any client that returns users to that host register, not only the one you had in mind.

Enter one host per line — a pasted URL is reduced to its host — and choose Save hosts. The list is kept in the platform's identity provider rather than in its database; writing it needs the platform's RBAC service to hold the manage-realm role there.

Installation settings

Setting	Default	Meaning
Mcp:Enabled	false	Whether the interface is on — only until someone uses the switch on the tab
Mcp:PublicBaseUrl	empty	The public address the server advertises to clients. Empty, it is taken from the proxy's forwarded headers; set it when your proxy does not send them
Mcp:SelfBaseUrl	http://localhost:8080	Where the server's tools call the platform API from inside the API process
Mcp:DocumentationUrl	set by the installer to https://portal.example.com/help/ai-clients	The setup page advertised to clients

Set them as environment variables of the platform API, for example Mcp__PublicBaseUrl.

The bridge configurations on the setup page — Codex, and Claude Desktop's configuration file — sign in with the Keycloak client stackship-mcp, which the installer creates when it sets up Keycloak on a new installation. The client accepts sign-in redirects to http://127.0.0.1 and http://localhost, plus the addresses in the installation setting platform.mcpRedirectUris.