Almacenamiento privado
El almacenamiento privado permite que personas y agentes guarden archivos sin exponer rutas del almacén de objetos. Puedes consultar el uso, listar archivos, cargar o escribir contenido, descargarlo mientras estás autenticado y eliminar los archivos que te pertenecen.
Ruta rápida
- Abre el panel Storage para consultar Storage usage y cargar un archivo.
- Usa una ruta relativa como
imports/order-9182.jsonpara organizar los archivos. - Descarga o elimina archivos desde la cuenta autenticada que los cargó.
- Concede a una clave de API MCP el permiso
mcp:readomcp:writecuando un cliente MCP necesite acceder al almacenamiento.
Límites y propiedad
| Límite o regla | Valor |
|---|---|
| Cuota predeterminada de la cuenta | 1 GiB, según la configuración de la cuenta |
| Carga de archivos REST | 25 MiB por archivo |
| Carga útil de lectura o escritura MCP | 1 MiB por operación |
| Límite de listado REST | Hasta 200 archivos por solicitud |
| Propiedad | Los archivos son privados de la persona autenticada, no recursos públicos del espacio de trabajo |
Las rutas de almacenamiento deben ser rutas POSIX relativas. Se rechazan las rutas absolutas, las barras invertidas, los segmentos . o .. y los caracteres de control.
API REST
Todos los endpoints de Storage requieren una sesión autenticada. Las respuestas y descargas se marcan como privadas y las cachés compartidas no pueden almacenarlas.
| Operación | Endpoint |
|---|---|
| Uso | GET /api/storage/usage |
| Listado | GET /api/storage/files?prefix=<path>&search=<text>&limit=<n> |
| Carga | POST /api/storage/files como datos de formulario multipart con file y path opcional |
| Descarga | GET /api/storage/files/:id |
| Eliminación | DELETE /api/storage/files/:id |
Una carga de más de 25 MiB o que excede la cuota devuelve 413. La ausencia del servicio de almacenamiento devuelve 503. Un archivo de otra persona no está disponible mediante estos endpoints.
Herramientas MCP
El servidor MCP de Almirant expone estas herramientas con alcance de cuenta:
| Herramienta | Permiso | Uso |
|---|---|---|
storage_usage | mcp:read | Consulta el uso de cuota de bytes y objetos. |
storage_list | mcp:read | Lista archivos privados sin revelar claves sin procesar del almacén de objetos. |
storage_read | mcp:read | Lee texto UTF-8 o contenido base64 de hasta 1 MiB. |
storage_write | mcp:write | Crea o reemplaza una ruta relativa con texto o contenido base64 de hasta 1 MiB. |
storage_delete | mcp:write | Elimina por ID un archivo propio. |
storage_write requiere exactamente uno de content o base64. Usa el endpoint REST autenticado de descarga para un archivo que supere el límite de lectura MCP.
Seguridad
- No uses nunca el almacenamiento privado como host de descarga pública.
- Guarda los secretos en el mecanismo de secretos del servicio que los necesita, no en archivos que el agente pueda leer salvo que esa exposición sea intencional.
- Un token MCP con almacenamiento debe corresponder a una persona autenticada e incluir el permiso de lectura o escritura necesario.