Autorización OAuth
El flujo OAuth 2.1 del servidor MCP de punta a punta, para quien escribe su propio cliente.
Esta página es para quien implementa un cliente MCP propio. Si usas Claude, Claude Code, Cursor o el Inspector, el cliente hace todo esto solo: ve a Conectar un cliente.
Reclee implementa la autorización de MCP: OAuth 2.1 con descubrimiento (RFC 9728 y RFC 8414), registro dinámico de clientes (RFC 7591) y PKCE S256 obligatorio. Solo hay clientes públicos (sin client_secret) y un único grant: authorization_code. Todos los paths de esta página son relativos a https://app.reclee.com.
El token que se obtiene es una API key rcl_… del workspace que la persona eligió: no expira, no hay refresh_token y vive hasta que alguien la revoca.
El flujo completo
Descubrir. El cliente llama a POST /api/mcp sin credencial y recibe 401 con el header WWW-Authenticate, que apunta al documento del recurso protegido.
Leer los metadatos. GET /.well-known/oauth-protected-resource dice cuál es el servidor de autorización; GET /.well-known/oauth-authorization-server dice sus endpoints.
Registrarse. POST /oauth/register con el nombre y las redirect_uris devuelve un client_id.
Autorizar. El cliente abre el navegador en /oauth/authorize con su code_challenge. La persona inicia sesión, elige un workspace y acepta. Reclee redirige a la redirect_uri con un code.
Canjear. POST /oauth/token con el code y el code_verifier devuelve el access_token.
Usar. Cada POST /api/mcp lleva Authorization: Bearer rcl_….
Todos estos endpoints, salvo la página /oauth/authorize, contestan OPTIONS y mandan Access-Control-Allow-Origin: *: ninguno usa cookies, así que un cliente que corre en el navegador puede llamarlos.
1. El 401 que inicia el descubrimiento
/api/mcpSin Authorization, o con una key inválida, revocada o de alguien que ya no tiene asiento:
HTTP/1.1 401 Unauthorized
Content-Type: application/json
WWW-Authenticate: Bearer resource_metadata="https://app.reclee.com/.well-known/oauth-protected-resource"
{ "error": "UNAUTHENTICATED" }El cuerpo es el mismo que el de la API REST: no distingue entre una key que falta, una mal escrita o una revocada.
2. Los metadatos
/.well-known/oauth-protected-resourceTambién responde en /.well-known/oauth-protected-resource/api/mcp (la forma con sufijo de RFC 9728).
{
"resource": "https://app.reclee.com/api/mcp",
"authorization_servers": ["https://app.reclee.com"],
"bearer_methods_supported": ["header"],
"resource_name": "Reclee"
}/.well-known/oauth-authorization-server{
"issuer": "https://app.reclee.com",
"authorization_endpoint": "https://app.reclee.com/oauth/authorize",
"token_endpoint": "https://app.reclee.com/oauth/token",
"registration_endpoint": "https://app.reclee.com/oauth/register",
"response_types_supported": ["code"],
"grant_types_supported": ["authorization_code"],
"code_challenge_methods_supported": ["S256"],
"token_endpoint_auth_methods_supported": ["none"]
}Los documentos se arman con el origen del request: el issuer coincide con la URL que usó el cliente.
3. Registrar el cliente
/oauth/registerCuerpo JSON:
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| redirect_uris | string[] | Sí | De 1 a 10 direcciones, cada una de hasta 2000 caracteres. https con cualquier host; http solo en loopback (localhost, 127.0.0.1 o [::1]), con cualquier puerto. Sin fragmento (#), sin usuario en la URL y sin esquemas propios (miapp://). |
| client_name | string | Opcional | De 1 a 80 caracteres. Es lo que ve la persona en la pantalla de consentimiento y el nombre de la API key que se crea. Sin él, «MCP client». |
Cualquier otro metadato de RFC 7591 (grant_types, token_endpoint_auth_method, scope…) se acepta y se ignora.
curl -s https://app.reclee.com/oauth/register \
-H "Content-Type: application/json" \
-d '{
"client_name": "Acme Recruiting Agent",
"redirect_uris": ["http://127.0.0.1:53682/callback"]
}'Respuesta 201 Created:
{
"client_id": "6f1c2b9e-4d3a-4e8b-9a17-2c5d8e0f3b41",
"client_name": "Acme Recruiting Agent",
"redirect_uris": ["http://127.0.0.1:53682/callback"],
"token_endpoint_auth_method": "none",
"grant_types": ["authorization_code"],
"response_types": ["code"],
"client_id_issued_at": 1792857600
}| Error | Status | Cuándo |
|---|---|---|
invalid_redirect_uri | 400 | Falta redirect_uris, está vacía o alguna dirección no cumple las reglas. |
invalid_client_metadata | 400 | El cuerpo no es JSON, o client_name no cumple. |
server_error | 500 | Se superó el tope de registros por minuto (por dirección de origen y global), o falló algo del lado de Reclee. Espera un minuto y reintenta. |
Registra cuando vayas a autorizar
El registro es abierto y tiene tope por minuto. Un cliente que pasa más de un día sin canjear ningún código puede borrarse: registra justo antes de autorizar y guarda el client_id después de canjear el primer token.
4. Autorizar en el navegador
/oauth/authorizeEl cliente abre esta URL en el navegador de la persona. No es una API: es la pantalla de consentimiento de Reclee.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| response_type | string | Sí | Siempre code. |
| client_id | uuid | Sí | El que devolvió el registro. |
| redirect_uri | string | Sí | Una de las registradas, exactamente igual. |
| code_challenge | string | Sí | BASE64URL(SHA-256(code_verifier)), sin relleno: 43 caracteres. |
| code_challenge_method | string | Sí | Siempre S256. plain no se acepta. |
| state | string | Opcional | Hasta 2000 caracteres. Vuelve tal cual en la redirección; úsalo contra CSRF. |
scope y resource se aceptan y se ignoran: no hay scopes, la key hereda el rol de la persona. Un parámetro repetido cuenta como inválido.
https://app.reclee.com/oauth/authorize?response_type=code
&client_id=6f1c2b9e-4d3a-4e8b-9a17-2c5d8e0f3b41
&redirect_uri=http%3A%2F%2F127.0.0.1%3A53682%2Fcallback
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256
&state=af0ifjsldkjLa pantalla de consentimiento
Si la persona no tiene sesión iniciada, Reclee la lleva a iniciar sesión y la devuelve a esta pantalla. Ahí ve:
- El nombre del cliente, con la advertencia de que Reclee no lo verifica.
- A qué dirección vuelve al aceptar: el host de la
redirect_uri, o «una app en esta computadora» si es loopback. - Sus workspaces, con su rol en cada uno. Solo puede elegir uno donde tiene asiento (
OWNERoRECRUITER); los demás aparecen deshabilitados con el motivo. Si no tiene asiento en ninguno, solo puede cancelar.
Cómo vuelve al cliente
| Qué pasó | Redirección |
|---|---|
| La persona acepta | redirect_uri?code=…&state=… |
| La persona cancela | redirect_uri?error=access_denied&state=… |
response_type distinto de code | redirect_uri?error=unsupported_response_type&state=… |
Falta o es inválido code_challenge, el método no es S256, state es demasiado largo o hay un parámetro repetido | redirect_uri?error=invalid_request |
client_id desconocido o redirect_uri no registrada | No redirige. Muestra un error en pantalla, porque la dirección no es de confianza. |
Si la redirect_uri ya traía query propia, Reclee agrega code y state a continuación sin tocarla.
El code vale 60 segundos y se usa una sola vez.
5. Canjear el código
/oauth/tokenAcepta application/x-www-form-urlencoded (lo que pide RFC 6749) o application/json.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| grant_type | string | Sí | Siempre authorization_code. |
| code | string | Sí | El que llegó a la redirect_uri. |
| redirect_uri | string | Sí | La misma que se usó en /oauth/authorize. |
| client_id | uuid | Sí | El del registro. |
| code_verifier | string | Sí | De 43 a 128 caracteres de [A-Za-z0-9._~-]. |
curl -s https://app.reclee.com/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d grant_type=authorization_code \
-d code=SplxlOBeZQQYbYS6WxSbIA2nqzJr8Vq4tRk3mX9wYcE \
-d redirect_uri=http://127.0.0.1:53682/callback \
-d client_id=6f1c2b9e-4d3a-4e8b-9a17-2c5d8e0f3b41 \
-d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXkRespuesta 200, con Cache-Control: no-store:
{
"access_token": "rcl_Qm9vdHN0cmFwLWV4YW1wbGUta2V5LW5vdC1yZWFsLTAx",
"token_type": "Bearer"
}No hay expires_in, refresh_token ni scope. En la app, la key aparece en Configuración → Developers con el nombre del cliente seguido de «(MCP)».
| Error | Status | Cuándo |
|---|---|---|
invalid_request | 400 | Falta un campo, tiene mal formato, viene repetido, o el cuerpo no es form ni JSON. |
unsupported_grant_type | 400 | grant_type no es authorization_code (por ejemplo, refresh_token). |
invalid_client | 401 | client_id falta o no es un UUID. |
invalid_grant | 400 | El código no existe, ya se usó, venció, no corresponde a ese client_id o redirect_uri, el code_verifier no coincide con el code_challenge, o la persona perdió el asiento o el acceso al workspace entre la autorización y el canje. |
server_error | 500 | Falló algo del lado de Reclee. |
Los errores siguen RFC 6749 §5.2: { "error": "invalid_grant" }.
Un código presentado dos veces revoca su key
Si un código ya canjeado vuelve a llegar a /oauth/token, la respuesta es invalid_grant y además se revoca la API key que ese código había emitido. Es la defensa de RFC 6749 contra un código robado: canjea cada código una sola vez.
Generar el PKCE
code_verifier=$(openssl rand 32 | base64 | tr '+/' '-_' | tr -d '=\n')
code_challenge=$(printf '%s' "$code_verifier" | openssl dgst -sha256 -binary | base64 | tr '+/' '-_' | tr -d '=\n')
echo "$code_verifier $code_challenge"Usar el token
curl -s https://app.reclee.com/api/mcp \
-H "Authorization: Bearer rcl_Qm9vdHN0cmFwLWV4YW1wbGUta2V5LW5vdC1yZWFsLTAx" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'El mismo token sirve para la API REST: es una API key como cualquier otra.
Cuándo deja de funcionar
El token no expira por tiempo. Deja de funcionar, y el servidor contesta 401 con el WWW-Authenticate del paso 1, cuando:
- alguien lo revoca;
- la persona pierde el asiento (pasa a Colaborador o Lector) o deja de ser miembro activo del workspace;
- el workspace se desactiva o tiene la baja programada.
Si a la persona le devuelven el asiento, la misma key vuelve a funcionar. Ante un 401, tu cliente tiene que repetir la autorización: no hay refresh.
Desconectar un cliente
Desconectar es revocar su API key:
- En la app: Configuración → Developers, la key con el nombre del cliente seguido de «(MCP)» → revocar. Cada persona revoca las suyas; un Dueño puede revocar cualquiera del workspace.
- Por API:
POST /api/v1/account/api-keys/{apiKeyId}/revoke(el id sale deGET /api/v1/account/api-keys).
La key deja de funcionar en el próximo request. Queda en la lista marcada como revocada, para saber quién tuvo acceso y hasta cuándo, y no se puede reactivar.