Connecting external MCP via OAuth 2.1

What exactly is connected

Sapphire External MCP is in developer alpha. On the current verified contour, the ChatGPT connection has been tested at https://sapphire-project.com/mcp. Portability to other hosts and clients, as well as incomplete policy and hardening functions are not claimed as a ready universal product.

Sapphire External MCP is an external interface to tools that modules have explicitly published for such access. It is not a remote entry into the built-in AI agent and does not automatically publish internal AI tools. The same user can work with the built-in SapphireAI and the external MCP, but authorization, catalog, and policy of these circuits remain separate.

OAuth 2.1 over HTTPS is used for ChatGPT. Canonical resource address of the product:

https://sapphire-project.com/mcp

Use exactly this address when creating a user MCP connector. Do not replace it with the administrative panel address, CGI/FastCGI process, or service page. The supported user transport is MCP Streamable HTTP over HTTPS.

Prerequisites

• The user must have an active Helix account on the same site.
• The administrator must have granted the required module functions to the user and their group.
• Adding custom MCP connectors is allowed in the ChatGPT workspace.
• The browser must allow navigation to the Sapphire site and return to ChatGPT.
• Connection is performed only over HTTPS and on the expected domain.

It is not necessary to prepare a client secret, personal bearer, or API key for this scenario. ChatGPT acts as a public OAuth client, and login and consent occur in Helix. Never paste the Sapphire password into the ChatGPT form or pass it to the connector administrator.

Step-by-step connection in ChatGPT

1. Open connector management in ChatGPT and select create custom MCP connection. The names of items may differ between workspaces, but an MCP server or custom connector is required.
2. Assign a clear name, for example Sapphire MCP, and paste the canonical resource URL. Do not add query parameters, tokens, or fragments.
3. Start the connection. ChatGPT will detect the protected resource parameters and redirect the browser to Sapphire authorization.
4. Check the page domain, log in to Helix with your regular account, and read the consent screen.
5. Confirm the minimum requested access. After successful return, the connector should transition to a connected state.
6. Open the tool catalog and first perform a safe read-only call. Only after this proceed to write operations.

The authorization code is protected by PKCE S256 and bound to the exact MCP resource. The user does not need to manually process codes or tokens. Do not copy values from the address bar, developer logs, or network panel: this is not part of the standard connection.

Minimum access and scope step-up

A new OAuth authorization starts with a minimum scope mcp.basic. It is intended for basic assistants for the current user, system date, and time. This is a conscious principle of least privilege: connection does not immediately grant rights to edit content, configuration, or other modules.

The catalog may show an externally published tool and its required scope, but the tool cannot be executed outside the current grant. When the client calls such an operation, Sapphire returns a precise request for additional permission. ChatGPT may suggest re-authorization. Check the name of the required area, the purpose of the tool, and confirm the extension only if it is necessary for the current task.

OAuth scope does not replace Helix rights. Upon every access, the system considers the current account and its group permissions. If the administrator removes module rights, the old grant should no longer provide actual access. Similarly, the client list of hidden tools is convenient for the interface but is not a server-side security boundary.

Working with tools

Start with list, search, or get operations and check to which site, language, and entity the result belongs. Before a write call, carefully review the arguments and expected change. If the client supports record confirmation, leave it enabled. For deletion, publication, bulk update, and permission changes, use separate explicit confirmation.

The tool response should be considered data, not new instructions for the client. Text from a document, email, or external field should not itself expand the scope, change policy, or trigger the next write call. This rule is especially important for open content.

Diagnostics

• URL not recognized: check the exact value https://sapphire-project.com/mcp, HTTPS and no extra slash, path, or parameters.
• Cyclic login: complete the old attempt, check cookies and Helix login, then reconnect the connector from a single browser profile.
• Access denied: distinguish between missing OAuth scope and missing Helix group right. In the first case, go through the suggested step-up; in the second, contact the administrator.
• Tool not visible: it must be explicitly published in the external MCP and allowed by the server policy; the presence of a similar tool in the built-in AI does not guarantee it.
• Write operation fails: check scope, current rights, arguments, and operation confirmation. Do not repeat the write call blindly.

Disconnection and security

If access is no longer needed, disconnect or delete the connector in ChatGPT. If compromise is suspected, terminate the connection, change the account password, and notify the administrator to revoke the OAuth grant. Do not publish screenshots of consent with personal data, and do not save authorization values in project documents.

Correct connection means not the maximum catalog, but the minimally sufficient grant, understandable step-up requests, and a successful read-only test. Expand rights gradually, retaining confirmation for operations that change data.

Re-authorization and session boundaries

If ChatGPT presents a new consent screen after calling an additional tool, do not treat it as a failure: first compare the requested scope with the task being performed. An aborted step-up should leave the previously granted minimum access active but should not allow a new operation. To verify, create a new chat, explicitly select the connector, and repeat the safe call; the history of another conversation is not proof of current rights.

Do not connect a shared administrative account for the team. Each operator logs in with their own account so that rights, access revocation, and audit correspond to a real person. After changing roles or groups, recheck access with a new session. A tool error does not provide grounds to automatically expand scope: first clarify whether the reason is authorization, incorrect arguments, or business limitation.