Connect Hosted MCP

Configure one hosted MCP connection to reach the Aiola projects available to your account. Service behavior and the tool catalog are documented in Hosted MCP.

Hosted versus workspace MCP

Connector	Use
Hosted MCP	Add Aiola to an external client through one remote URL
Workspace MCP Servers	Configure local, per-workspace stdio or HTTP servers inside Aiola Desktop

Connection

Field	Value
Access	Active Pro subscription or trial
GUI Lifetime	Hosted connector not included
Server URL	`https://aiola.app/api/mcp`
Transport	Streamable HTTP
Authentication	OAuth 2.1 discovered from the endpoint’s protected-resource metadata; the client opens browser sign-in and consent, then sends the resulting bearer token

Do not add an API key or a static Authorization header. The MCP client must support OAuth for a remote Streamable HTTP server.

Claude Code

Add the hosted server with the exact remote-HTTP command:

claude mcp add --transport http aiola https://aiola.app/api/mcp

Then run /mcp in Claude Code and follow the browser login flow for aiola. See Claude Code’s MCP documentation for its current server and authentication controls.

ChatGPT

ChatGPT owns this setup flow; this repository does not define its configuration-file format. Follow OpenAI’s current custom MCP app instructions, use the server URL above as the endpoint, choose OAuth when asked for authentication, scan the tools, and complete the Aiola browser consent.

Cursor

Cursor owns its hosted-server UI and configuration schema; this repository does not establish a remote-URL JSON shape. Add the URL above as a remote MCP server by following Cursor’s current MCP documentation, then complete the browser OAuth flow.

Grok and Grok bot

Grok owns this setup flow; this repository does not define its configuration-file format. Follow xAI’s custom MCP connector instructions, enter the server URL above, and complete the required authentication. For a managed Grok team, an administrator may need to provision the connector first.

Repository-generated local bridge

Aiola Desktop also generates a workspace-local stdio bridge at <workspace>/.aiola/mcp-server.mjs. It is not a bridge to the hosted URL and is not needed for the clients above. Workspace Settings → MCP Servers → Install Aiola generates the script and client entries; when other MCP servers already exist, the action is Install Aiola MCP Server. In production, Aiola writes this shape to <workspace>/.mcp.json for Claude Code; for Cursor, it writes the same entry to <workspace>/.cursor/mcp.json and approves it with cursor-agent mcp enable aiola:

{
  "mcpServers": {
    "aiola": {
      "command": "<Aiola Desktop executable; node in development>",
      "args": ["<workspace>/.aiola/mcp-server.mjs"],
      "env": {
        "ELECTRON_RUN_AS_NODE": "1",
        "AIOLA_PORT": "<current desktop server port>",
        "AIOLA_SESSION_FILE": "<Aiola data directory>/mcp-session.json",
        "AIOLA_WORKSPACE_ID": "<workspace ID>",
        "AIOLA_PROJECT_NAME": "<workspace name>"
      }
    }
  }
}

The production command is Aiola Desktop’s own Electron executable with ELECTRON_RUN_AS_NODE=1; it is not a bare node command. Aiola writes the absolute executable, script, and session-file paths and refreshes the entry on launch. Do not copy the placeholders literally. Codex receives the same command, argument, and environment in its generated [mcp_servers.aiola] TOML entry inside a per-workspace CODEX_HOME.

Verify the connection

Confirm authentication

Return to the client after Aiola sign-in and consent. The aiola server must report connected or authenticated rather than requesting sign-in.

Confirm discovery

Open the server’s discovered tools and confirm that list_projects is present.

Call a tool

Run list_projects. A working connector returns the Aiola projects available to the signed-in account.

OAuth behavior

The endpoint publishes OAuth protected-resource metadata at https://aiola.app/.well-known/oauth-protected-resource/api/mcp. Unauthenticated requests receive HTTP 401 with a WWW-Authenticate: Bearer challenge that identifies that metadata URL.

Project selection

Tools accept a project selector where applicable. A request can resolve the only available project automatically; with multiple projects, use the exact project returned by list_projects.

Troubleshooting

Problem	Resolution
Browser sign-in does not open	Confirm the client supports OAuth for remote Streamable HTTP MCP servers
Subscription error	Use an account with an active Pro subscription or trial; GUI Lifetime excludes hosted MCP
Project not found	Run `list_projects` and pass the exact returned name
Server cannot be reached	Confirm the URL is exactly `https://aiola.app/api/mcp`
Local workspace server changed unexpectedly	You are on Workspace Settings → MCP Servers; hosted MCP is configured in the external client

Getting Started

Workspaces & Central

Chat & AI

Project Operations

Monitoring

Connections

Settings

Setup Guides

Reference

Connect Hosted MCP

Hosted versus workspace MCP

Connection

Claude Code

ChatGPT

Cursor

Grok and Grok bot

Repository-generated local bridge

Verify the connection

OAuth behavior

Project selection

Troubleshooting

​Hosted versus workspace MCP

​Connection

​Claude Code

​ChatGPT

​Cursor

​Grok and Grok bot

​Repository-generated local bridge

​Verify the connection

​OAuth behavior

​Project selection

​Troubleshooting

Hosted versus workspace MCP

Connection

Claude Code

ChatGPT

Cursor

Grok and Grok bot

Repository-generated local bridge

Verify the connection

OAuth behavior

Project selection

Troubleshooting