Discovery

Cuatro documentos legibles por máquina describen el gateway a herramientas que tienen que configurarse solas. Los cuatro son públicos y se cachean cinco minutos; sólo el documento de recurso protegido depende de un workspace.

Se sirven tanto bajo el prefijo versionado como en la raíz del host del gateway:

GET https://gateway.praxsuite.com/openapi.json
GET https://gateway.praxsuite.com/api/v1/gateway/openapi.json

Cualquiera de los dos funciona.

openapi.json

Una descripción OpenAPI 3.1 del plano de datos — /{workspaceId}/schema y /{workspaceId}/query — con los dos esquemas de seguridad declarados: una cabecera de API key, y OAuth2 con los scopes gateway:read y gateway:write.

{
  "openapi": "3.1.0",
  "info": { "title": "Praxsuite DataEngine Gateway", "version": "1.0.0" },
  "servers": [{ "url": "https://gateway.praxsuite.com" }],
  "security": [{ "oauth2": ["gateway:read"] }, { "apiKey": [] }]
}

La entrada servers es la URL base autoritativa del despliegue desde el que lo descargaste — un despliegue dedicado devuelve aquí su propio host. Si estás generando un cliente y quieres un solo dato sobre el que construirlo, ese es el dato.

oauth-protected-resource

GET /.well-known/oauth-protected-resource/{workspaceId}/{resource}
GET /.well-known/oauth-protected-resource

Metadatos de recurso protegido según RFC 9728. Éste es el documento al que apunta el `401`, y por lo tanto el primero que descarga un cliente MCP:

WWW-Authenticate: Bearer realm="Praxsuite Gateway", resource_metadata="https://gateway.praxsuite.com/.well-known/oauth-protected-resource/{workspaceId}/mcp"

Describe el recurso que el cliente acaba de no poder alcanzar, y nombra al servidor de autorización que lo protege:

{
  "resource": "https://gateway.praxsuite.com/{workspaceId}/mcp",
  "authorization_servers": ["https://identity.praxsuite.com"],
  "scopes_supported": ["gateway:read", "gateway:write"],
  "bearer_methods_supported": ["header"]
}

El segmento {resource} es la ruta del plano de datos que el cliente estaba llamando: mcp, query, schema y las demás. Cualquier cosa fuera de ese conjunto es un 404, así que esto no sirve para fabricar un documento de metadatos de una ruta arbitraria. La forma raíz, sin workspace, describe al gateway entero y existe para los clientes que consultan antes de haber visto un 401.

oauth-authorization-server

GET /api/v1/gateway/oauth-authorization-server
GET /.well-known/oauth-authorization-server

Metadatos de servidor de autorización según RFC 8414: el segundo salto. El cliente llega aquí siguiendo el authorization_servers del documento anterior, no directamente desde el 401.

{
  "issuer": "…",
  "authorization_endpoint": "…/api/v1/oauth/authorize",
  "token_endpoint": "…/api/v1/oauth/token",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": ["gateway:read", "gateway:write"]
}

Authorization code con PKCE, sin client secret. El emisor es el servicio de identidad, no el gateway: el gateway es el servidor de recursos.

No hay registration_endpoint: no se ofrece registro dinámico de clientes. Un conector se registra en el workspace, así que un cliente no puede darse de alta solo.

ai-plugin.json

GET /api/v1/gateway/ai-plugin.json
GET /.well-known/ai-plugin.json

El manifiesto heredado de plugin de ChatGPT. Apunta a openapi.json para la superficie de la API y a los endpoints OAuth de arriba para la autenticación, y menciona el endpoint MCP en su descripción para el modelo.

Se mantiene para herramientas que todavía lo leen. Para algo nuevo, el camino es MCP.

Ver también

• MCP — el endpoint que estos documentos existen sobre todo para ayudar a encontrar

• Autenticación — la cabecera WWW-Authenticate que arranca la cadena de discovery