Connect an AI assistant to TholusOS with MCP

The TholusOS MCP service lets a compatible AI assistant read and edit your guided experience projects through your Tholus Account. It supports structured authoring and project workflows, including cloud work while a Mac is offline. Native checks and previews require a registered, available Mac.

What MCP provides

Model Context Protocol is an open standard that connects AI applications to external tools and data. In TholusOS, it exposes operations such as reading a project, preparing a change and attaching a material. The capabilities come from the service and project, rather than from the wording of a prompt. MCP introduction.

Three components are involved: the AI client, the remote TholusOS service and, for native operations, your Mac. A cloud editing operation can succeed while the Mac is offline. A request for native inspection remains a separate operation with its own result.

Requirements and connection details

You need a Tholus Account, access to your projects, and an AI client or workspace that allows the integration. For native operations, sign in on the intended TholusOS Mac and keep the application available.

Use the following endpoint for a custom remote connection:

https://tholusos-mcp.tholusdome.com/mcp

Setting	Value or requirement
Authentication	OAuth through Tholus Account
Authorization issuer	https://www.tholusdome.com/studio
Editorial permissions	studio:read and studio:write
Token authentication	Public OAuth client; no client secret
Authorization flow	Authorization code with PKCE S256
Custom OAuth client	Use the registered client ID and callback supplied for that integration

The service publishes its authentication requirements through OAuth resource discovery. Its authorization metadata does not advertise automatic client registration. Use the supplied registered client ID and callback for your integration. If these are missing, contact the usual neXt team with the AI client and callback URL displayed in its setup screen; the administrator must register that combination first.

Use an existing configured TholusOS connection when one is available in your workspace. The native Mac uses its own device authorization; studio:sync belongs to that workflow and is not an extra permission to add to an editorial chat connection.

Connect from ChatGPT

In the current ChatGPT Plugins interface, add the remote MCP server as a plugin, configure OAuth and sign in to Tholus Account. Workspace permissions determine whether you can create the connection yourself. OpenAI connection guide.

1. Open Plugins in ChatGPT on the web.
2. Select + → Add custom MCP server.
3. Name it TholusOS MCP and enter the HTTPS endpoint above.
4. Configure OAuth using the client registration provided for ChatGPT. Leave the client secret empty for this public-client setup.
5. Review the connection details, create the plugin and complete the Tholus Account sign-in when requested.
6. Install the resulting plugin and select it in a conversation using @.

The current Plugins flow does not require enabling Developer Mode first. Older custom-app interfaces use a different setup path. If creation is unavailable, ask your workspace administrator about Create plugins with MCPs; account and workspace policies still apply. Use the current OpenAI help page for the applicable interface. Keep an existing working connection.

Connect from Claude

Add a remote connector in Claude, then authenticate with Tholus Account. Organization administrators add it through Organization settings → Connectors; members connect to the configured integration individually. Claude connector guide.

1. Open Customize → Connectors. Choose Connect on an existing TholusOS integration, or Add custom connector when creating a permitted personal connection.
2. Enter TholusOS MCP and the endpoint above.
3. Choose OAuth sign-in. When using the supplied static registration, select Use your own OAuth client and enter that registration’s client ID.
4. Keep the client secret and additional fixed authentication headers empty for the public-client setup.
5. Complete Tholus Account sign-in, then enable the connector through the conversation’s + → Connectors menu.

A remote connector connects from Claude’s infrastructure. It differs from a local MCP server on your computer: the remote service must be reachable from Claude, even when your own browser can open it. Claude network requirements.

Verify access without changing a project

Start with a project list and a capability read. This checks authentication, ownership and what the selected project exposes before asking the assistant to edit anything.

Try this prompt:

Use TholusOS MCP to list my projects. Read the capabilities of the project I select and summarize its supported authoring operations and registered Mac availability. Do not create or modify a project or queue a device operation.

The assistant should use list_projects, then get_project_context with view: "capabilities". A project list contains projects accessible to the authenticated owner; an empty list can mean that you are signed into a different account or have not created an account project yet.

Check the selected title, available operations and device state. A device’s recorded capabilities do not mean it is currently online. When access works, continue with MCP authoring workflows.

Resolve connection and discovery problems

Match the remedy to the failure: authentication, client registration, project ownership, tool discovery and Mac availability are different parts of the workflow.

Symptom	What to check
OAuth rejects the client or callback	Confirm that the integration’s client ID and exact callback are registered; changing the project will not fix registration.
Add custom MCP server or connector creation is absent	Check account eligibility and workspace permissions. In a managed workspace, use the integration your administrator supplies.
Sign-in succeeds but the expected project is absent	Check the Tholus Account identity and whether the project is an account project.
A documented tool is missing	Refresh the connection’s discovered tool definitions where the AI client supports it; workspace approval may be needed.
A tool rejects an unsupported field	Read that project’s capabilities and command descriptors; projects can expose different supported operations.
Native work remains queued	Check the selected Mac’s account, application state and availability.

For ChatGPT, the plugin’s details page can refresh tools and descriptions. Read the result of the refresh before retrying a request. OpenAI tool-management guidance.

When reporting a problem, include the client, time, tool name, error code and operation ID if one was returned. Keep passwords, access tokens and temporary file-download URLs out of support messages.