Armazenamento privado
O armazenamento privado permite que pessoas e agentes guardem arquivos sem expor caminhos do armazenamento de objetos. Você pode consultar o uso, listar arquivos, carregar ou gravar conteúdo, fazer download enquanto estiver autenticado e excluir arquivos que pertencem a você.
Caminho rápido
- Abra o painel Storage para consultar Storage usage e carregar um arquivo.
- Use um caminho relativo, como
imports/order-9182.json, para organizar os arquivos. - Baixe ou exclua arquivos usando a conta autenticada que os carregou.
- Conceda a uma chave de API MCP a permissão
mcp:readoumcp:writequando um cliente MCP precisar acessar o armazenamento.
Limites e propriedade
| Limite ou regra | Valor |
|---|---|
| Cota padrão da conta | 1 GiB, conforme a configuração da conta |
| Upload de arquivos REST | 25 MiB por arquivo |
| Carga útil de leitura ou gravação MCP | 1 MiB por operação |
| Limite de listagem REST | Até 200 arquivos por solicitação |
| Propriedade | Os arquivos são privados da pessoa autenticada, não recursos públicos do espaço de trabalho |
Os caminhos de armazenamento devem ser caminhos POSIX relativos. Caminhos absolutos, barras invertidas, segmentos . ou .. e caracteres de controle são rejeitados.
API REST
Todos os endpoints de Storage exigem uma sessão autenticada. As respostas e os downloads são marcados como privados, e caches compartilhados não podem armazená-los.
| Operação | Endpoint |
|---|---|
| Uso | GET /api/storage/usage |
| Listagem | GET /api/storage/files?prefix=<path>&search=<text>&limit=<n> |
| Upload | POST /api/storage/files como dados de formulário multipart com file e path opcional |
| Download | GET /api/storage/files/:id |
| Exclusão | DELETE /api/storage/files/:id |
Um upload com mais de 25 MiB ou que exceda a cota retorna 413. A ausência do serviço de armazenamento retorna 503. Um arquivo de outra pessoa não fica disponível por esses endpoints.
Ferramentas MCP
O servidor MCP do Almirant expõe estas ferramentas com escopo de conta:
| Ferramenta | Permissão | Uso |
|---|---|---|
storage_usage | mcp:read | Consulta o uso da cota de bytes e objetos. |
storage_list | mcp:read | Lista arquivos privados sem revelar chaves brutas do armazenamento de objetos. |
storage_read | mcp:read | Lê texto UTF-8 ou conteúdo base64 de até 1 MiB. |
storage_write | mcp:write | Cria ou substitui um caminho relativo por texto ou conteúdo base64 de até 1 MiB. |
storage_delete | mcp:write | Exclui por ID um arquivo da própria pessoa. |
storage_write exige exatamente um entre content e base64. Use o endpoint REST autenticado de download para um arquivo que exceda o limite de leitura MCP.
Segurança
- Nunca use o armazenamento privado como host de download público.
- Armazene os segredos no mecanismo de segredos do serviço que precisa deles, não em arquivos que o agente possa ler, a menos que essa exposição seja intencional.
- Um token MCP com armazenamento deve corresponder a uma pessoa autenticada e incluir a permissão de leitura ou gravação necessária.