--- title: "Tokens de agente para clientes" description: "De una cuenta con sesión a un cliente MCP en un proyecto con un token acotado y con caducidad: alcances, límites, revocación y cada rechazo." slug: "agents" locale: "es" group: "agents" order: 2 last_reviewed: 2026-10-26 --- # 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:///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](/es/docs/agent-quickstart/). Cada paso indica su estado; los estados se definen en la [página de datos](/es/docs/facts/#estados). 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](/es/docs/security-status/). ## 1. Crea tu cuenta > Estado: Disponible en el piloto (access.signup) Abre `https:///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": ""}` 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": "", "name": "Claude Code", "projects": [""], "scopes": ["read", "database.read", "migration"], "expires_in_days": 7, "idempotency_key": ""} ``` 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:///platform/api/dashboard/platform/agents/projects//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: ```sh claude mcp add --transport http plurabase- \ https:///platform/api/dashboard/platform/agents/projects//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-": {"type": "http", "url": "https:///platform/api/dashboard/platform/agents/projects//mcp", "headers": {"Authorization": "Bearer "}}}} ``` 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 ``, 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](/es/docs/migration/) 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](/es/docs/hosting-sites/)). ## 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": ""}`. | 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.