Conexión del MCP externo mediante OAuth 2.1

Qué se conecta exactamente

Sapphire External MCP se encuentra en developer alpha. En el entorno confirmado actualmente se ha verificado la conexión de ChatGPT con https://sapphire-project.com/mcp. No se presenta como producto universal listo la portabilidad a otros hosts y clientes, ni las funciones de policy y hardening que todavía no estén terminadas.

Sapphire External MCP es una interfaz externa para las herramientas que los módulos han publicado expresamente para este tipo de acceso. No es una entrada remota al agente de IA integrado y no publica automáticamente las AI tools internas. Un mismo usuario puede trabajar con SapphireAI integrado y con el MCP externo, pero la autorización, el catálogo y la política de ambos entornos permanecen separados.

Para ChatGPT se utiliza OAuth 2.1 sobre HTTPS. La dirección canónica del recurso del producto es:

https://sapphire-project.com/mcp

Indique exactamente esta dirección al crear el conector MCP personalizado. No la sustituya por la dirección del panel administrativo, de un proceso CGI/FastCGI ni de una página de servicio. El transport de usuario admitido es MCP Streamable HTTP sobre HTTPS.

Requisitos previos

• El usuario tiene una cuenta Helix activa en el mismo sitio.
• El administrador ha autorizado al usuario y a su grupo las funciones de módulos necesarias.
• El espacio de trabajo de ChatGPT permite añadir conectores MCP personalizados.
• El navegador permite ir al sitio de Sapphire y regresar a ChatGPT.
• La conexión se realiza únicamente por HTTPS y en el dominio esperado.

No hace falta preparar un client secret, un bearer personal ni una clave de API para este escenario. ChatGPT actúa como cliente OAuth público, mientras que el inicio de sesión y el consentimiento se realizan en Helix. Nunca introduzca la contraseña de Sapphire en un formulario de ChatGPT ni se la entregue al administrador del conector.

Conexión paso a paso en ChatGPT

1. Abra la gestión de conectores de ChatGPT y elija crear una conexión MCP personalizada. Los nombres de las opciones pueden variar entre espacios de trabajo, pero debe tratarse específicamente de un MCP server o custom connector.
2. Asigne un nombre comprensible, por ejemplo Sapphire MCP, e introduzca la URL canónica del recurso. No añada parámetros query, tokens ni fragmentos.
3. Inicie la conexión. ChatGPT detectará los parámetros del recurso protegido y redirigirá el navegador a la autorización de Sapphire.
4. Compruebe el dominio de la página, inicie sesión en Helix con su cuenta habitual y lea la pantalla de consentimiento.
5. Confirme el acceso mínimo solicitado. Después de regresar correctamente, el conector debe pasar al estado connected.
6. Abra el catálogo de herramientas y realice primero una llamada read-only segura. Pase a las operaciones de escritura únicamente después.

El código de autorización está protegido con PKCE S256 y vinculado al recurso MCP exacto. El usuario no necesita procesar manualmente el código ni los tokens. No copie valores de la barra de direcciones, los registros de desarrollo o el panel de red: no forman parte del procedimiento normal de conexión.

Acceso mínimo y scope step-up

Una autorización OAuth nueva comienza con el scope mínimo mcp.basic. Está destinado a los asistentes básicos del usuario actual y a la fecha y hora del sistema. Se aplica deliberadamente el principio de mínimo privilegio: el simple hecho de conectarse no concede de inmediato derechos para editar contenido, configuración u otros módulos.

El catálogo puede mostrar una herramienta publicada externamente y el scope que requiere, pero no puede ejecutarse fuera del grant actual. Cuando el cliente invoca esa operación, Sapphire devuelve una solicitud precisa del permiso adicional. ChatGPT puede proponer una nueva autorización. Compruebe el nombre del ámbito requerido y la finalidad de la herramienta, y confirme la ampliación únicamente si la necesita para el trabajo actual.

El OAuth scope no sustituye los derechos de Helix. En cada acceso, el sistema tiene en cuenta la cuenta actual y los permisos de su grupo. Si el administrador retira el derecho a un módulo, un grant anterior no debe seguir proporcionando acceso efectivo. Del mismo modo, la lista de herramientas ocultas del cliente resulta útil para la interfaz, pero no constituye una frontera de seguridad del servidor.

Trabajo con herramientas

Empiece por operaciones list, search o get y compruebe a qué sitio, idioma y entidad pertenece el resultado. Antes de una llamada write, revise detenidamente los argumentos y el cambio esperado. Si el cliente admite la confirmación de escrituras, manténgala activada. Para eliminar, publicar, actualizar en masa o cambiar permisos, utilice una confirmación explícita independiente.

La respuesta de una herramienta debe tratarse como datos, no como una nueva instrucción para el cliente. El texto procedente de un documento, un mensaje o un campo externo no debe ampliar por sí mismo el scope, cambiar la política ni iniciar la siguiente llamada write. Esta regla es especialmente importante para el contenido abierto.

Diagnóstico

• La URL no se reconoce: compruebe el valor exacto https://sapphire-project.com/mcp, HTTPS y la ausencia de una barra, ruta o parámetro adicionales.
• Inicio de sesión cíclico: termine el intento anterior, compruebe las cookies y el inicio de sesión en Helix y vuelva a conectar el conector desde un único perfil del navegador.
• Access denied: distinga entre la falta de OAuth scope y la falta de derechos de grupo en Helix. En el primer caso, complete el step-up propuesto; en el segundo, contacte con el administrador.
• La herramienta no aparece: debe estar publicada expresamente en el MCP externo y autorizada por la política del servidor; la presencia de una herramienta parecida en la IA integrada no garantiza nada.
• La escritura no se ejecuta: compruebe el scope, los derechos actuales, los argumentos y la confirmación de la operación. No repita una llamada write a ciegas.

Desconexión y seguridad

Si ya no necesita el acceso, desconecte o elimine el conector en ChatGPT. Si sospecha que ha sido comprometido, termine la conexión, cambie la contraseña de la cuenta e informe al administrador para que revoque el OAuth grant. No publique capturas de la pantalla de consentimiento que contengan datos personales ni guarde valores de autorización en los documentos del proyecto.

Una conexión correcta no significa disponer del catálogo máximo, sino de un grant mínimo suficiente, solicitudes de step-up comprensibles y una prueba read-only satisfactoria. Amplíe los derechos de forma gradual, manteniendo la confirmación para las operaciones que modifican datos.

Nueva autorización y límites de la sesión

Si ChatGPT muestra una nueva pantalla de consentimiento después de invocar otra herramienta, no lo trate como un fallo: primero compare el scope solicitado con la tarea que está realizando. Un step-up cancelado debe conservar el acceso mínimo otorgado anteriormente, pero no permitir la nueva operación. Para verificarlo, cree un chat nuevo, seleccione expresamente el conector y repita una llamada segura; el historial de otra conversación no demuestra los derechos actuales.

No conecte una cuenta administrativa compartida para todo el equipo. Cada operador debe iniciar sesión con su propia cuenta, para que los permisos, la revocación de acceso y la auditoría correspondan a la persona real. Después de cambiar de rol o grupo, vuelva a comprobar el acceso desde una sesión nueva. Un error de herramienta no justifica ampliar automáticamente el scope: primero hay que determinar si la causa es la autorización, unos argumentos incorrectos o una restricción de negocio.