Tokens de agente para clientes

De una cuenta nueva a un agente de IA (Claude Code, Cursor o cualquier cliente MCP) que inspecciona tu esquema, aplica migraciones y despliega Edge Functions en un proyecto con un token acotado y con caducidad, en lugar de la clave service-role del proyecto. Un token con sql.execute o migration ejecuta SQL como dueño de la base de datos y puede leer todo lo que esa base guarda, incluidos los secretos del propio proyecto: dáselo solo a un agente al que confiarías esa clave. Todas las rutas de esta página están en el documento OpenAPI 3.1 que el servicio de identidad sirve en https://<host>/platform/identity/openapi.yaml.

Estos tokens los crea el cliente en la página con sesión. Los tokens que emite hoy la consola privada se describen en el inicio rápido para agentes. Cada paso indica su estado; los estados se definen en la página de datos. El operador activa las rutas de tokens con enroll-public-agents; hasta entonces responden 503. Qué protege hoy los datos del piloto: seguridad y estado.

1. Crea tu cuenta

Estado: Disponible en el piloto (access.signup)

Abre https://<host>/public-identity/ y elige Create account: correo, el código de 6 dígitos que enviamos (válido 15 minutos), una contraseña de 12 a 72 caracteres, una app autenticadora y, por último, guarda los códigos de recuperación. La página con sesión muestra tu organización, sus proyectos y, debajo, tus tokens de agente.

2. Crea un proyecto

Estado: Disponible en el piloto (access.self-service-project)

En la página con sesión, ponle nombre al proyecto y elige Create project. La fila muestra cada paso hasta que el proyecto está listo. El plan del piloto permite un proyecto por organización. Por script, con la sesión del navegador: POST /platform/api/dashboard/platform/organizations/{organization}/projects con {"name": "...", "idempotency_key": "<uuid>"} y luego consulta la operación que devuelve.

3. Crea un token de agente

Estado: En desarrollo (agents.tokens)

En la página con sesión: New token, ponle el nombre del agente, elige los proyectos, el acceso y la caducidad, y luego Create token. Copia el token o la configuración MCP lista y elige I stored this token. El token no se vuelve a mostrar; el servidor solo guarda su SHA-256.

Scope	Herramientas	Roles que pueden otorgarlo
`read` (siempre incluido)	`get_project`, `get_project_url`, `get_publishable_keys`, `get_agent_operation`, `list_migrations`, `list_edge_functions`, `get_edge_function`	todo rol del proyecto
`database.read`	`list_tables`, `get_policies`	todo rol del proyecto
`migration`	`apply_migration`	owner, admin
`sql.execute`	`execute_sql`	owner, admin
`deploy`	`deploy_edge_function`, `invoke_edge_function`	owner, admin

migration y sql.execute ejecutan SQL como dueño de la base de datos y pueden saltarse RLS; migration añade el registro de nombre y checksum. Otórgalos solo a agentes a los que dejarías administrar la base de datos.

Reglas que aplica el servidor:

Un token es tuyo, de una organización y de los proyectos que elegiste.
La caducidad es obligatoria: de 1 a 30 días por defecto; el operador fija el máximo, de 1 a 90 días. La página ofrece 1, 7, 30 y 90 días hasta ese máximo, y el propio máximo.
Como máximo 10 tokens activos y 10 creaciones por hora por cuenta.
Lo que puede hacer un token es su scope intersectado con tu rol en cada llamada: si tu rol baja a developer, desaparecen sus herramientas de SQL y despliegue, y vuelven si tu rol vuelve.
Si sales de la organización o pierdes el acceso a uno de los proyectos del token, el token queda revocado en ese momento y sigue revocado aunque te vuelvan a invitar o a dar el proyecto: crea uno nuevo.
Repetir una creación con el mismo idempotency_key devuelve el mismo token con "secret": null; revócalo y crea otro.

Por script, con la sesión del navegador (Origin, X-Plurabase-Request: 1 y el token CSRF de la sesión): POST /platform/api/dashboard/platform/agents/tokens con

json

{"organization": "<uuid>", "name": "Claude Code", "projects": ["<ref del proyecto>"],
 "scopes": ["read", "database.read", "migration"], "expires_in_days": 7,
 "idempotency_key": "<uuid>"}

La respuesta 201 trae secret una sola vez; GET .../agents/tokens lista los tokens sin él.

4. Conecta tu cliente MCP

Estado: En desarrollo (agents.tokens)

Endpoint, uno por proyecto: https://<host>/platform/api/dashboard/platform/agents/projects/<ref del proyecto>/mcp, con la cabecera Authorization: Bearer pbt_.... Guarda el token en el almacén de secretos del cliente o en una variable de entorno, nunca en un repositorio.

Claude Code:

claude mcp add --transport http plurabase-<ref> \
  https://<host>/platform/api/dashboard/platform/agents/projects/<ref>/mcp \
  --header "Authorization: Bearer $PLURABASE_MCP_TOKEN"

Clientes que se configuran con JSON (la página copia esto con tu token incluido):

json

{"mcpServers": {"plurabase-<ref>": {"type": "http",
  "url": "https://<host>/platform/api/dashboard/platform/agents/projects/<ref>/mcp",
  "headers": {"Authorization": "Bearer <token>"}}}}

Clientes que solo arrancan servidores stdio locales: ejecuta el conector de agents/simplybase-mcp (npm ci --ignore-scripts una vez) como node connector.mjs, con PLURABASE_MCP_URL, PLURABASE_MCP_TOKEN y PLURABASE_MCP_HOSTS (tu <host>, separados por comas si son varios) en su entorno. Envía el token solo por HTTPS, a la ruta MCP de un proyecto, en un host que PLURABASE_MCP_HOSTS incluya. Muchos clientes arrancan los servidores stdio casi solo con el bloque env del servidor, así que define las tres ahí, en tu configuración MCP de usuario, nunca en un archivo dentro de un repositorio.

La lista de hosts detecta una URL mal escrita o un host parecido. No protege tu token de una configuración MCP que no escribiste tú. El archivo MCP de un repositorio puede fijar PLURABASE_MCP_URL y PLURABASE_MCP_HOSTS en su propio host, y su bloque env tiene prioridad sobre el entorno que pasa tu cliente, así que un token que esté en el entorno de tu shell termina allí. Cualquier comando que arranque puede además leer tus archivos y tu entorno, guardes donde guardes el token. Aprueba servidores MCP de proyecto solo en repositorios en los que confíes.

Empieza cada sesión con tools/list y get_project: la lista de herramientas es exactamente lo que este token puede hacer ahora. Límites: 60 llamadas por minuto por token, 600 cada 10 minutos por red, 2 llamadas en curso por servidor; un 429 trae Retry-After. El endpoint responde solo JSON (sin SSE) y rechaza peticiones de navegadores desde otros orígenes.

5. Migra tu esquema

Estado: En desarrollo (agents.tokens)

Pide al agente que aplique cada cambio con apply_migration (name, query, operation_id). Corre en una transacción y registra nombre y checksum: el mismo nombre y contenido otra vez es una repetición segura; otro contenido con el mismo nombre se rechaza. list_migrations muestra las últimas 200 migraciones que aplicaste con agentes en este proyecto, de la más antigua a la más reciente.

Cada llamada que modifica algo necesita un operation_id UUID nuevo. Tras un timeout, llama a get_agent_operation con el mismo id; nunca reenvíes la mutación con otro id. Un resultado unknown bloquea más mutaciones en ese proyecto hasta que el operador lo concilie.

Estado: En desarrollo (ops.migration)

Traer filas, usuarios de Auth y objetos de Storage desde un proyecto de Supabase es un trabajo de migración aparte, no una herramienta de agente; migración lo describe y explica cómo se mueve hoy un proyecto.

6. Despliega

Estado: En desarrollo (agents.tokens)

Edge Functions: deploy_edge_function con los archivos fuente, el entrypoint, verify_jwt y expected_revision (absent para una función nueva; si no, la revisión que da list_edge_functions), y luego invoke_edge_function con la clave pública o sin clave. Todavía sin verificar contra el runtime de proyectos del piloto.

Estado: En desarrollo (sites.git)

Los frontends no se despliegan con tokens: se publican desde Git a Sites (hosting de frontend).

7. Revoca

En la página con sesión, Revoke y luego Revoke token, o POST /platform/api/dashboard/platform/agents/tokens/{token_id}/revoke con {}. La siguiente petición del token se rechaza; una llamada que ya está en curso termina. Cerrar sesión o cambiar la contraseña no revoca tokens: después de recuperar tu cuenta, revisa la lista.

Rechazos

Las respuestas son {"error": "PUBLIC_AGENT_REJECTED", "reason": "<reason>"}.

Estado	Reason	Qué hacer
400	`rejected`	Corrige la petición (campos, caducidad sobre el máximo, MCP-Protocol-Version)
401	`unauthorized`	Token desconocido, caducado o revocado, o sesión cerrada: crea un token o inicia sesión
403	`forbidden`	Tu rol no permite ese scope en un proyecto elegido, o falló una comprobación de cabeceras
403	`step_up_required`	Vuelve a iniciar sesión con tu autenticador
404	`not_found`	No es tu token, o el proyecto no está en este token o ya no es tuyo
409	`token_limit`	Revoca un token primero
409	`conflict`	Mismo `idempotency_key` con otro contenido
409	`unsupported`	El runtime de este proyecto no ofrece herramientas de agente
413	`too_large`	Cuerpo MCP de más de 512 KiB
429	`try_later`	Espera los segundos de `Retry-After`
503	`unavailable`	El servicio de agentes aún no corre aquí, o no respondió

Los rechazos de una herramienta dentro de MCP (por ejemplo AGENT_SCOPE_DENIED o PROJECT_NOT_READY) llegan como resultado de la herramienta con isError: true.

OPERATION_HISTORY_LIMIT significa que el registro de operaciones de este proyecto está lleno: 10.000 operaciones, sin contar las migraciones aplicadas. MIGRATION_HISTORY_LIMIT significa que guarda 1.000 migraciones aplicadas; entonces solo se detiene apply_migration. Las entradas terminadas de más de 90 días dejan sitio solas; antes de eso, pide al operador que limpie el registro del proyecto. Los demás proyectos no se ven afectados.

Tokens de agente para clientes

1. Crea tu cuenta#

2. Crea un proyecto#

3. Crea un token de agente#

4. Conecta tu cliente MCP#

5. Migra tu esquema#

6. Despliega#

7. Revoca#

Rechazos#

1. Crea tu cuenta

2. Crea un proyecto

3. Crea un token de agente

4. Conecta tu cliente MCP

5. Migra tu esquema

6. Despliega

7. Revoca

Rechazos