HHostingByteSoftware
Ctrl K
ComunidadGuías…

docs/chatgpt-integration.md

Rama main · réplica de lectura del repositorio original.

Archivo original ↗Preguntar a KiBot
# ChatGPT integration

[Português (Brasil)](chatgpt-integration.pt-BR.md)

Checked: 2026-10-06.

## Target

~~~text
ChatGPT Web
   -> OAuth discovery + dynamic client registration
   -> HTTPS /mcp
   -> Gateway
   -> Broker
   -> VPS
   -> tamper-evident audit
~~~

The installation completion rule is deliberately stricter than "containers are healthy."

## ChatGPT product prerequisite

The supported product path includes write/modify tools, so compatibility is decided by the capabilities actually exposed by the target ChatGPT surface and verified end to end.

As checked on 2026-10-06, OpenAI's public help documentation describes full MCP write/modify support for **Business and Enterprise/Edu** workspaces. Separately, the operator's real **ChatGPT Plus** environment exposed Portico write-capable tools and completed a scoped write/read/delete proof through the Broker on 2026-10-06. The repository records that as empirical evidence for that environment, not as a universal Plus compatibility claim.

Before starting public setup:

1. confirm that the current ChatGPT Web account/workspace actually exposes Developer Mode / custom MCP app creation;
2. on managed workspaces, ensure an admin/owner has enabled Developer Mode / custom apps as required by the workspace;
3. confirm the account can create a custom app and provide the HTTPS `/mcp` endpoint;
4. confirm the effective MCP permissions by actually discovering and exercising the required Portico actions; do not infer write capability from the plan name alone;
5. compare the observed surface with current official OpenAI documentation and record any rollout/account-specific difference as environment evidence rather than a broad compatibility promise.

Official references checked for this release candidate:

- https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt
- https://developers.openai.com/plugins/build/app-quickstart

A read-only MCP connection can still be useful for diagnostics, but it must not be presented as completion of the write-capable product installation.

## Prerequisites

1. The target ChatGPT account/workspace actually exposes custom MCP app creation in Developer Mode / Plugins.
2. Local installation has already passed `bash scripts/verify.sh`.
3. A DNS hostname points to the VPS.
4. Integrated auth has passed:

~~~bash
bash scripts/setup-integrated-auth.sh
~~~

That command must finish with `INTEGRATED AUTH: READY`.

To rerun only the public boundary checks after any DNS, proxy or OAuth change:

~~~bash
bash scripts/verify-public.sh
~~~

## Connection

Run:

~~~bash
bash scripts/connect-chatgpt.sh
~~~

The script first reruns the public checks, prints the exact MCP endpoint and OAuth issuer, then shows the current ChatGPT connection steps. The public preflight validates HTTPS, RFC 9728 metadata, HTTPS authorization/token endpoints, DCR, PKCE S256, refresh-token support, token-endpoint authentication metadata, private audience-bound introspection, and the unauthenticated `WWW-Authenticate` discovery challenge.

The intended standards flow is:

1. ChatGPT reads RFC 9728 protected-resource metadata from the MCP host.
2. ChatGPT discovers the ZITADEL authorization server.
3. ChatGPT dynamically registers an OAuth public client.
4. The operator signs in with the dedicated OAuth operator account. VPS passwords and SSH keys are never entered into ChatGPT.
5. Authorization Code + PKCE completes.
6. ChatGPT discovers the MCP tools.
7. The operator invokes `system.info`.
8. The Gateway validates the access token against the integrated issuer.
9. The Broker matches the stable subject and applies policy.
10. The audit chain records the successful tool invocation.

The ChatGPT product UI is version-sensitive, so button names and workspace eligibility must be rechecked against current official OpenAI documentation at release/setup time.

## Credential boundary

ChatGPT receives the public MCP endpoint and completes the standards-based OAuth flow. It does not need the VPS login password, a private SSH key, root credentials, unrestricted remote shell access, or unrelated infrastructure secrets.

The dedicated OAuth operator password is entered only into the integrated identity provider login flow. The setup also shows the dedicated OAuth username (default `vps-operator`) because the login screen may ask for the username rather than the email address. These OAuth credentials are separate from Linux/SSH/root credentials. Development-only remote access used by maintainers to validate a build is not part of this supported connection procedure.

## Completion gate

`scripts/connect-chatgpt.sh` records a fixed audit baseline, then lets the interactive operator complete ChatGPT setup without a hidden countdown. After the operator presses Enter, it checks for a new authenticated `system.info` event from the expected subject after that baseline.

~~~text
tutorial shown
 != success

ChatGPT app connected
 + authenticated system.info
 + expected subject
 + Broker policy allow
 + successful VPS execution
 + matching audit record
 = INSTALLATION COMPLETE
~~~

If the event has not arrived yet, the interactive script remains incomplete, explains what to check and offers another Enter-to-verify attempt. Non-interactive/CI mode retains a bounded timeout.

## Transport

The MCP transport is Streamable HTTP over HTTPS at:

~~~text
https://<domain>/mcp
~~~

No custom WebSocket transport is introduced.

## Security boundary

ChatGPT confirmations and app permissions are additional UX controls. They never replace server-side authorization.

The Gateway authenticates. The Broker authorizes. The VPS owner chooses the policy.

## Operator approvals and fallback compatibility

A successful OAuth connection **does not authorize additional project roots**. The machine-local Broker is authoritative. MCP Apps and native elicitation are client-capability-dependent, not a guarantee for every ChatGPT plan/surface or device. In-chat approval UI alone is not proof of owner identity. Do not promise successful native desktop/mobile approval before the exact release is accepted on real client devices.

The existing Community `scripts/operator-approvals.py` provides an SSH/operator fallback for pending root and sensitive-file requests without MCP elicitation; see the [Quick Start instructions](quick-start.md) and the [Portuguese fallback reference](operator-approval-fallback.md). An authenticated HTTPS operator portal is a separate implementation candidate and must actually be integrated, configured and validated before use. A link or pending request ID conveys no permission. If the installed version lacks a compatible approval channel, the request remains pending, and the operator must not treat it as approved.

[Português (Brasil)](chatgpt-integration.pt-BR.md).