Autenticación

El servidor MCP de Platica acepta dos credenciales Bearer. Las dos viajan en el mismo header; lo que cambia es quién las emite y qué autoridad cargan.

Authorization: Bearer <credencial>

Credencial	Prefijo	Quién la usa	Autoridad
OAuth 2.1	`pl_at_`	Cursor, Claude, VS Code y cualquier cliente MCP que sepa el spec	Tu usuario: los workspaces que autorizaste y los permisos de tu rol
API Key	`pl_key_`	Scripts, CI, Postman y clientes sin OAuth	El workspace de la key, con acceso completo a sus módulos

Cada herramienta MCP hace internamente la misma llamada autenticada que harías al endpoint REST correspondiente. Rate limits, validaciones y errores son idénticos. No hay un "modo MCP" separado.

Consejo

Para Cursor, Claude o VS Code, usa OAuth. No hace falta generar ni pegar una API Key: el cliente abre el inicio de sesión de Platica y tú eliges los workspaces.

OAuth 2.1

Es el método que recomienda el spec de autorización MCP . Platica es a la vez el resource server (POST /mcp) y el authorization server que emite los tokens.

Cómo se conecta

Pegas la URL — En tu cliente MCP configuras https://api.platica.mx/mcp sin header Authorization. Ver Configuración .
El cliente descubre solo — La primera llamada a /mcp responde 401 con un WWW-Authenticate que apunta a los documentos de discovery. El cliente lee el authorization server, se registra (Dynamic Client Registration) y abre el navegador.
Inicias sesión en Platica — Autorizas con la misma cuenta que usas en el dashboard. Si ya tienes sesión, no vuelves a escribir la contraseña.
Eliges workspaces — Marcas a cuáles puede entrar esta conexión. El cliente guarda los tokens y los refresca solo.

No registras una OAuth App a mano. El cliente se registra solo la primera vez; un client_id no otorga acceso hasta que una persona aprueba la conexión.

Scopes

Scope	Qué permite
`platica:read`	Lecturas (`GET`). Es el mínimo para entrar.
`platica:write`	Altas, cambios y borrados. Sin él, esas tools responden `403` con un challenge `insufficient_scope` para que el cliente pida un step-up.
`offline_access`	Refresh token. El cliente lo usa para renovar el access token sin volver a pedirte consentimiento.

Si el cliente no pide scope, Platica otorga platica:read y platica:write. Los clientes MCP modernos suelen pedir también offline_access.

Permisos del rol

Los scopes abren la puerta; tu rol en el workspace decide qué hay detrás. Un operador que conecta Claude no se convierte en admin: si en el producto no puede gestionar integraciones, connect_mcp_server le devolverá el mismo 403.

Esa lectura es en vivo. Si te sacan de un workspace el lunes, el token deja de alcanzarlo en la siguiente llamada — no hay que revocar nada a mano.

Una API Key es distinta: es una credencial de servicio que un admin emitió a propósito, y sigue dando acceso completo a los módulos de su workspace mientras el dueño siga siendo miembro.

Workspaces

En el consentimiento eliges uno o varios workspaces. El modelo no conoce esos IDs: la primera tool que debe llamar es list_workspaces .

Un solo workspace: las demás tools infieren el ID. No hace falta pasar workspace.
Varios workspaces: las tools de escritura exigen workspace: "<id>". Si lo omites, responden 400 Must specify a valid workspace... para que el modelo corrija.

El mismo argumento workspace existe en REST como ?workspace=.

Tokens

Token	Prefijo	Vida
Access token	`pl_at_`	1 hora
Refresh token	`pl_rt_`	60 días de inactividad; cada uso la extiende

El cliente los guarda y los rota. No los copies a un config ni los pegues en un header a mano: si el access token caduca, el cliente lo refresca; si pegas uno viejo, recibes 401.

El access token también funciona como Bearer en la API REST (/v1/*). Sigue cargando tu rol y tus scopes, no el acceso total de una API Key.

Cómo se corta el acceso

Desconecta el servidor en el cliente MCP. Los clientes que siguen el spec llaman a POST /oauth/revoke.
Salir de un workspace en Platica corta ese workspace en la siguiente request.
Un token de sólo lectura no puede escribir: el cliente debe volver a autorizar pidiendo platica:write.

La gestión de API Keys (crear / revocar) no se expone como tool MCP. Un modelo no puede canjear una sesión OAuth por una key permanente.

Discovery, según RFC 9728 y RFC 8414. Los clientes prueban las dos grafías del path:

GET https://api.platica.mx/.well-known/oauth-protected-resource
GET https://api.platica.mx/.well-known/oauth-protected-resource/mcp
GET https://api.platica.mx/.well-known/oauth-authorization-server
GET https://api.platica.mx/.well-known/oauth-authorization-server/mcp

El recurso canónico — el valor de resource en authorize/token — es https://api.platica.mx/mcp. También se acepta el origin pelado (https://api.platica.mx). Cualquier otra audiencia se rechaza.

Endpoint	Uso
`GET /oauth/authorize`	Authorization Code + PKCE `S256`. `response_type` distinto de `code` no está soportado.
`POST /oauth/token`	`authorization_code` y `refresh_token`. Acepta form-urlencoded o JSON.
`POST /oauth/register`	Dynamic Client Registration (RFC 7591). Abierto: el `client_id` no otorga acceso.
`POST /oauth/revoke`	Revocación (RFC 7009). Responde `200` aunque el token no exista.

PKCE es obligatorio y sólo S256 (plain no se anuncia: OAuth 2.1 lo prohíbe). Los clientes MCP son públicos (token_endpoint_auth_method: none); si registraste un secret, hay que presentarlo.

El 401 de /mcp sin credencial trae el challenge que arranca el flujo:

WWW-Authenticate: Bearer resource_metadata="https://api.platica.mx/.well-known/oauth-protected-resource/mcp", scope="platica:read platica:write"

Redirect URIs permitidos al registrar: https, loopback (http://127.0.0.1, localhost, [::1]) o un scheme privado (cursor://…). Se rechazan http en hosts públicos y cualquier URI con fragment.

API Key

Sigue siendo válida. Es la opción para cron, CI, curl y cualquier cliente que no sepa OAuth.

Las API Keys se crean desde el dashboard, no desde el servidor MCP:

Abre la configuración — En el dashboard, Configuración → API Keys.
Crea una Key — Ponle un nombre descriptivo (ej. cursor-personal o ci-prod).
Cópiala — Formato pl_key_KEY_ID_SECRETO. Se muestra una sola vez.
Pégala en el cliente — Authorization: Bearer pl_key_... en el config. Ver Configuración .

Advertencia

La API Key no se rota sola. Si sospechas que se filtró, revócala en el dashboard. Crear o revocar keys no es una tool MCP.

La key cubre el workspace en el que se creó (o los que tenga asignados, si es multi-workspace) con acceso a todos los módulos. No hereda el rol de quien la creó.

Multi-workspace

Credencial	Cómo se elige el workspace
OAuth con un workspace	Se infiere. No pases `workspace`.
OAuth con varios	Llama `list_workspaces` y pasa `workspace` en cada tool de escritura.
API Key de un workspace	Se infiere.
API Key multi-workspace	Igual: si omites `workspace` en una escritura, `400 Must specify a valid workspace...`.

list_workspaces también te dice si la credencial es oauth o apiKey, qué scopes tiene y a qué módulos alcanza tu rol en cada workspace. Úsala como primera llamada cuando el cliente acaba de conectar.

Anterior Configuración Siguiente Catálogo de herramientas