Inicio de sesión con OAuth

Un asistente de IA inicia sesión en Setherion con OAuth en lugar de una clave de API: la persona pulsa Allow en una página de Setherion, y el asistente recibe un token. Esta página es el contrato para construir tu propio cliente. Si solo quieres conectar Claude, ChatGPT, Cursor o VS Code, sigue MCP: conecta un asistente de IA.

El flujo es OAuth 2.1 tal como lo pide la especificación de autorización de MCP (2025-06-18):

• el flujo de código de autorización, con PKCE (S256) siempre obligatorio;
• solo clientes públicos, sin secreto de cliente;
• registro dinámico de clientes (RFC 7591), para que nadie tenga que pegar un id de cliente en ningún sitio;
• tokens ligados a un solo recurso, el endpoint MCP (RFC 8707).

Los tokens funcionan en el Servidor MCP y en ningún otro sitio. Los endpoints REST de esta referencia usan una clave de API.

1. Descubre

Envía una petición al endpoint MCP sin ninguna credencial. El 401 apunta a los metadatos del recurso (RFC 9728) en su cabecera WWW-Authenticate:

curl https://www.setherion.com/.well-known/oauth-protected-resource/api/mcp

{
  "resource": "https://www.setherion.com/api/mcp",
  "authorization_servers": ["https://www.setherion.com"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["mcp"],
  "resource_name": "Setherion"
}

El mismo documento está en /.well-known/oauth-protected-resource. Después lee los metadatos del servidor de autorización (RFC 8414):

curl https://www.setherion.com/.well-known/oauth-authorization-server

{
  "issuer": "https://www.setherion.com",
  "authorization_endpoint": "https://www.setherion.com/oauth/authorize",
  "token_endpoint": "https://www.setherion.com/api/oauth/token",
  "registration_endpoint": "https://www.setherion.com/api/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": ["mcp"]
}

Ambos documentos, el registro y el endpoint de tokens responden a cualquier origen (Access-Control-Allow-Origin: *), así que un cliente en una página del navegador puede llamarlos.

2. Regístrate

Regístrate una vez por instalación. Registrarse no concede nada por sí solo: una persona todavía tiene que pulsar Allow, y el código se devuelve solo a las direcciones exactas registradas aquí.

curl -X POST https://www.setherion.com/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{ "client_name": "My assistant", "redirect_uris": ["http://localhost:8787/callback"] }'

Una dirección de redirección debe ser https, o http de vuelta a esta máquina (localhost, 127.0.0.1 o [::1]). No puede tener un fragmento ni un nombre de usuario. La única dirección que no es https ni http es cursor://anysphere.cursor-mcp/oauth/callback, para las aplicaciones antiguas de Cursor.

Sea cual sea el método de autenticación que pida un cliente, se registra como cliente público sin secreto, y la respuesta lo dice:

{
  "client_id": "5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30",
  "client_id_issued_at": 1790000000,
  "client_name": "My assistant",
  "redirect_uris": ["http://localhost:8787/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

El estado es 201. Los registros están limitados a 20 por hora y por dirección de red.

3. Pregunta a la persona

Abre el endpoint de autorización en el navegador de la persona. Es una página, no una API: la persona inicia sesión en Setherion si aún no lo ha hecho, ve el nombre que registraste y adónde se la enviará de vuelta, y pulsa Allow o Cancel.

https://www.setherion.com/oauth/authorize
  ?response_type=code
  &client_id=5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30
  &redirect_uri=http%3A%2F%2Flocalhost%3A8787%2Fcallback
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &state=af0ifjsldkj
  &resource=https%3A%2F%2Fwww.setherion.com%2Fapi%2Fmcp

Haz el verifier de 43 a 128 caracteres de A-Z a-z 0-9 - . _ ~, y consérvalo hasta el paso 4.

La persona vuelve a tu redirect_uri con:

• al pulsar Allow: code, state e iss (el issuer);
• al pulsar Cancel: error=access_denied, error_description=The request was declined., state e iss;
• ante un problema con la petición, una vez que se sabe que el cliente y la dirección son genuinos: error, error_description, state e iss. El error es unsupported_response_type, invalid_request (falta PKCE, o el método no es S256) o invalid_target (el recurso no es el endpoint MCP).

Si el cliente es desconocido, o la dirección no es una de las que registró, la página se lo dice a la persona y no envía a nadie a ninguna parte, así que esta página nunca puede usarse para redirigir a alguien a una dirección que no registraste.

4. Intercambia el código

Envía campos codificados como formulario, como especifica OAuth. También se acepta JSON con los mismos nombres.

curl -X POST https://www.setherion.com/api/oauth/token \
  -d grant_type=authorization_code \
  -d code=stc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -d client_id=5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30 \
  -d redirect_uri=http://localhost:8787/callback \
  -d code_verifier=YOUR_VERIFIER

{
  "access_token": "sto_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "str_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "scope": "mcp"
}

Envía el access token al Servidor MCP como Authorization: Bearer sto_.... Los tokens nunca se guardan en caché: la respuesta lleva Cache-Control: no-store.

5. Renueva

Un access token dura una hora. Antes de que termine, o cuando el servidor MCP responda 401, intercambia el refresh token:

curl -X POST https://www.setherion.com/api/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=str_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -d client_id=5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30

La respuesta es la misma que en el paso 4, con un refresh token nuevo. El anterior deja de funcionar, así que guarda el nuevo cada vez.

Errores

Cada error del endpoint de tokens tiene el estado 400, salvo server_error, y el cuerpo { "error": "...", "error_description": "..." }.

Poner fin a una conexión

La persona puede desconectar un asistente en Settings y luego AI assistants and MCP. Todos los tokens de esa conexión, de acceso y de renovación, dejan de funcionar en su siguiente petición, no cuando se acaba la hora. Listar y poner fin a las conexiones solo es posible desde una sesión de Setherion iniciada, así que nada de lo que tiene un asistente puede hacerlo.

Usar una clave de API en su lugar

Un cliente que solo puede enviar una cabecera fija puede saltarse todo esto y enviar una clave de API al servidor MCP. Consulta Autenticación.