ChatGPT, Claude, and MCP

MCP is the hosted interface for agent surfaces that cannot run the OpenCloud CLI or call the API directly. Terminal-enabled Codex, Claude Code, and similar builders use CLI 3.10.3 even when an MCP connector is also installed.

For a step-by-step walkthrough that asks which assistant and device you use, open the interactive Connect OpenCloud guide. This page remains the complete protocol and recovery reference.

OpenCloud exposes two hosted, stateful MCP endpoints on mcp.<domain>:

Endpoint	Use
https://mcp.<domain>	Full lifecycle surface for ChatGPT, Claude, and other supported no-terminal connector clients.
https://mcp.<domain>/build	Focused native-agent surface for onboarding, assigned-app drafts, isolated development, promotion, and verification.

/mcp and /mcp/build remain compatibility aliases for existing clients; new connector configuration should use the canonical root or /build URL.

For production the canonical endpoints are https://mcp.opencloud.ai and https://mcp.opencloud.ai/build. Branch previews expose the same endpoints on their own MCP hosts. The former OPCL staging deployment is retired.

Once the appropriate endpoint is available, an agent can register the user, create the first app, write a server-side source draft, validate it, exercise an isolated development environment, and promote the exact verified revision to production. No local shell, filesystem, Node.js installation, or CLI is needed.

ChatGPT surface support

Pasting the homepage prompt does not install a connector. The chat must already have the OpenCloud MCP tools.

Surface	OpenCloud MCP path
ChatGPT Work on web	Install or enable the OpenCloud plugin/connector, then start a new chat.
ChatGPT Work in the desktop app	Install or enable the plugin, then use its tools in a new task.
Codex in the desktop app	Use CLI 3.10.3 when the task has terminal access; use the connector only for a no-terminal task.
ChatGPT mobile	Plugins and arbitrary MCP tools are not currently exposed directly in mobile chats. Use ChatGPT Remote to steer an already configured desktop task, or continue the same brief on Work web/desktop.
Other no-terminal or mobile agent	Use the hosted connector when that client exposes it; otherwise steer a configured desktop task.
Terminal-enabled agent	Use the checksum-verified public CLI. MCP is reserved for the no-terminal path.

This boundary comes from the current ChatGPT plugin availability documentation. See Remote connections for steering a configured desktop host from iOS or Android.

The canonical MIT-licensed plugin source is the public opencloud-ai/agent-plugins repository. Its connector points to the hosted endpoint above. Enabling a plugin is a one-time user or workspace administration step, not something a prompt may do silently.

Add its ChatGPT and Codex marketplace with:

codex plugin marketplace add opencloud-ai/agent-plugins

Claude surface support

OpenCloud uses one hosted MCP server and one shared workflow skill across the Claude package. The connector provides tools; the plugin adds the skill.

Surface	OpenCloud setup
Claude Code	Use CLI 3.10.3 for terminal work. The optional opencloud@opencloud-platform skill reinforces that boundary; do not complete MCP OAuth when the CLI/API path is usable.
Cowork	Use the CLI when its workspace exposes a terminal or direct API path; otherwise enable the plugin's hosted connector and workflow skill.
Claude.ai, Claude Desktop, or Claude mobile	Add or enable https://mcp.opencloud.ai under Customize > Connectors, then complete OAuth. These connector-only surfaces receive the tools, not the bundled plugin skill.

Claude deduplicates a plugin and connector that point to the same URL, so a user who has both should see one OpenCloud tool set. The plugin installs disabled by default because it connects to an external service; enabling it is the user's explicit opt-in.

From a checkout of opencloud-ai/agent-plugins, validate and load the package directly:

claude plugin validate ./plugins/opencloud --strict
claude --plugin-dir ./plugins/opencloud

To install from the public marketplace:

claude plugin marketplace add opencloud-ai/agent-plugins
claude plugin install opencloud@opencloud-platform
claude plugin enable opencloud@opencloud-platform

The Claude public plugin directory uses that public source. The remote connector has its own Connectors Directory submission.

Protocol and state model

OpenCloud uses MCP Streamable HTTP. The client initializes once, receives an opaque mcp-session-id, and sends that ID on later POST/GET/DELETE requests. A session is bound to the tool surface that created it; do not reuse a full root session on /build or the reverse. The legacy aliases map to those same two surfaces.

The session and application state have separate responsibilities:

• The MCP session retains pending onboarding metadata, the private completion material for an existing-account confirmation, and a bounded provisional grant for a new identity. These values never become tool output. A valid retained provisional grant remains authoritative for that session even when the client sends a stale bearer; a successful connect_opencloud call explicitly replaces it with the OAuth connection.
• OAuth access tokens are read from each HTTP request and remain request-scoped.
• Source files live in server-side drafts. They are not mirrored to a local workspace by the protocol.
• Tool results are structured JSON and are the authoritative evidence. The opencloud-skill resource provides additional guidance, but clients do not necessarily read resources automatically.

Draft writes use optimistic concurrency. expectedRevision protects the whole draft; baseSha256 protects each file. If either conflicts, read the current draft/files and rebase only the intended change. Do not increment a revision or fabricate a hash.

validate_draft distinguishes author inputs from packaged output:

• sourceManifest is the manifest actually read from the draft;
• sourceFiles are server-side author files;
• artifactFiles are files in the immutable deployment archive;
• diagnostics[].path and suggestedFix identify the smallest repair; and
• nextAction describes the valid transition from that result.

Development sessions materialize one validated revision into isolated data. Each later source change must be validated and applied again. A successful verify_dev_session receipt binds the active revision, artifact digest, and migration digest. Any edit or stale production base invalidates it.

Promotion and production verification are durable operations. Correlate the returned operation.id with get_operation until succeeded, failed, or cancelled. Then correlate the verification ID with get_verification_run. Never infer completion from elapsed time or a preview.

First registration without a CLI

The agent should first call get_opencloud_session. When no credential is present, this public status tool reports connected: false without forcing an OAuth detour.

• A returning user calls connect_opencloud and completes the OAuth connection UI surfaced by the active client.
• For a first project, the agent asks once for the user's email and calls start_onboarding with the project name and visibility.
• A new email receives organisation_setup_required, a retained request and the owner launch URL, with no app or credential. The owner confirms their email and explicitly sets up their company or accepts its invitation.
• If a new account returns provisional_ready with verification.emailSent: false, continue building the connected app without retrying onboarding and tell the owner that confirmation delivery is delayed.
• start_onboarding returns a non-secret launchUrl. Give that URL to the owner as the primary link while confirmation or deployment is pending. It waits for both states and opens the project in the confirmed browser.
• An existing email also receives an ownership-confirmation message. After confirmation and company setup, the agent calls complete_onboarding with the public onboarding ID returned by the first call. The private completion token remains inside the MCP session.
• While company setup is pending, wait for the owner and retain the same request. No app is created before assignment. Earlier provisional apps still pause if confirmation expires and retain their source, data, files and backups.

The confirmation message identifies the project and explains that approval is required to continue using it. Its explicit review form prevents email-link prefetch from confirming the request; submission also starts the owner's browser session and returns to launchUrl.

OpenCloud's OAuth server supports dynamic client registration, authorization code flow with PKCE S256, protected-resource discovery, and the mcp:tools scope. Access tokens are audience-bound to the MCP resource and checked on every tool invocation. The consent form always posts back to OpenCloud. After the server validates the exact registered callback, a no-store handoff page returns the browser to the client without expanding the consent page's Content Security Policy for every downstream redirect in that client's flow.

Source to isolated development

Use the MCP tools in this order:

1. get_opencloud_session, then resolve the assigned app from onboarding or get_app.
2. get_app_starter with the assigned app ID and all required capability IDs, including email for an app that sends or receives mail and notifications for Web Push. Implement every resolved checklist entry.
3. create_draft, followed by list_files and read_files. Preserve intentional existing work.
4. apply_file_changes with the current expectedRevision and per-file hashes. The first batch must contain opencloud.yaml and a non-empty configured frontend.
5. validate_draft and read source/artifact lists plus every diagnostic.
6. start_dev_session. When the owner wants to inspect the current revision without deployment, give them its browserPreviewUrl; it requires an owner or builder login and opens a clearly marked Not live preview window with Full size, Tablet, Mobile, and Reload tools around isolated synthetic-user-A state, without replacing their normal OpenCloud browser session. If they explicitly said not to deploy, stop at review and do not call promote_dev_revision.
7. apply_dev_revision after each later validated revision
8. request_dev_app and, where needed, high-level mutate_dev_data actions (create, createMany, updateById, or deleteById) against a named table. The tool uses synthetic user A; do not pass REST paths or credentials.
9. Exercise every declared Function through its intended path, then call list_dev_invocations: use invoke_dev_function for ordinary Functions, enqueue through a producer Function for queue consumers, and use synthetic injection for inbound-email handlers.
10. For email-capable apps, call list_dev_email_captures and get_dev_email_capture, and inject one reserved .test message into each receive-capable alias with inject_dev_email.
11. For Web Push apps, invoke the sending Function and inspect list_dev_notification_captures for its visible payload, resolved icon, and click path. On iOS and iPadOS, expect the installed app icon because those platforms currently ignore payload icon overrides.
12. verify_dev_session

The development database is isolated and contains only dummy fixtures. It cannot access production data or owner-configured secrets. Synthetic Auth, managed Files, Functions, and background jobs use isolated development state; Realtime, runtime telemetry, and cron are unavailable. An agent must not work around those boundaries by calling production.

The focused /build endpoint includes only the three dev-mailbox tools; they cannot contact MailPace. The full host-root endpoint additionally exposes read-only list_app_email_messages, get_app_email_message, list_app_web_push_messages, get_app_web_push_message, list_background_jobs, and get_background_job for authorized production diagnostics. Web Push history is retained for 30 days, identifies recipients only by userId, and returns anonymous attempt outcomes without subscription IDs or provider endpoints. Provider acceptance is not evidence of device receipt, display, open, or read. Job listing returns retained totals, per-queue depth and policy, and a filtered cursor page. Pass inclusive ISO 8601 from and to creation times to bound the totals, queue rollups, and history together, then pass nextCursor as cursor for the next page. Job responses never contain payloads, idempotency keys, or enqueuing user identifiers and provide no cancel or redrive action. Email listing returns address allocation and a filtered cursor page of metadata. Fetching one explicit email may return retained normalized text/HTML, safe headers, and attachment metadata, but never raw MIME or attachment bytes.

Verified promotion to production

verify_dev_session issues a short-lived receipt bound to one exact draft revision, artifact digest, and migration digest. Production promotion is:

1. promote_dev_revision
2. Poll get_operation until the durable deployment succeeds or fails.
3. Call verify_app.
4. Follow its operation and get_verification_run until all required gates are terminal.
5. Call get_app and report its canonical HTTPS URL only when the promoted deployment is active and production verification passed.
6. Stop the dev session only after production succeeds.

Never treat a preview URL, a queued deployment, or a partial verification run as completion.

Failure recovery

Failure	Recovery
Revision or file-hash conflict	Re-read get_draft/list_files/read_files and reapply only the intended change.
Missing/invalid manifest or SDK warning	Use get_app_starter and the reported diagnostic path; do not rewrite unrelated files.
Development migration failure	Repair the named migration and SQLSTATE, validate a new revision, then apply it.
Chromium certificate failure	Repair the environment TLS route. Certificate validation stays enabled.
Stale/expired receipt	Apply and verify the exact current revision again.
Durable operation failure	Preserve its terminal diagnostic and report failure; do not claim deployment.
Background job failed	Inspect the safe job detail and Agent Feed event; repair the consumer and enqueue a new idempotent job. There is no redrive mutation.

Authentication recovery

Onboarding tools advertise anonymous access, connect_opencloud advertises OAuth, and workflow tools accept either a bounded onboarding session or OAuth. When a valid connection is missing, the MCP HTTP endpoint responds with HTTP 401 Unauthorized; when a valid credential lacks MCP authority, it responds with HTTP 403 Forbidden. Both responses carry a WWW-Authenticate: Bearer challenge with the protected-resource metadata URL, mcp:tools scope, OAuth error, and a safe description. The authentication gate runs before the MCP tool handler so Claude and other supported clients can surface account linking or scope upgrade and retry the same call after authorization.

Bearer credentials are read from each MCP HTTP request. They are not copied into long-lived MCP session state. Only a provisional grant created by start_onboarding is retained server-side for that bounded onboarding session.

Bearer-only clients

When an MCP client supports a static Bearer token but cannot complete OAuth, the confirmed user can open Integrations > MCP Token in the OpenCloud dashboard and generate an account-level token. The token is audience-bound to the hosted MCP resource and carries only mcp:tools. The user chooses 1, 14, or 365 days, or Unlimited; 365 days is the default, and an Unlimited token remains active until it is revoked. The token follows the user's current owner and builder memberships, including apps added later, while normal per-app membership and owner-only checks still apply.

OpenCloud displays the token once and stores only its hash. Put it in the client's protected secret field and send it on every MCP request as Authorization: Bearer <token>. The token is not a direct control-plane API credential. Review its prefix, last-used date, and expiry—or revoke it immediately—from the MCP Token integration page. Never paste the token into chat, source code, logs, or an app secret that the connected MCP client does not own.