FileAgent
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@FileAgent upload report.pdf to the shared inbox"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
FileAgent
FTP for agents: a shared virtual filesystem, each file addressed and verified by SHA-256, with metadata extracted on upload.
Agents on the same FILEAGENT_DATA_DIR (stdio) or on the same HTTP server see the same collection. Nothing enters or leaves without a registered hash (ftp_register). That access_hash is the channel; the file's SHA-256 is the proof of integrity.
Model
Concept | What it is |
Access hash | Credential registered with |
Path | FTP path ( |
Blob | Immutable bytes. Address = |
Metadata | Extracted from content: mime, kind, title, language, headings, CSV columns, JSON keys, image dimensions, PDF hints. |
Document | Mutable pointer behind the path. Serves checkout/commit between agents. |
CAS |
|
agente A FileAgent agente B
|-- ftp_register() -----------> | |
|<-- access_hash ---------------| |
|---------------- compartilha access_hash --------------------->|
|-- ftp_put(/inbox/a.md, hash) >| sha256 + metadata |
| |<-- ftp_get(/inbox/a.md, hash)-|Two agents with the same secret in ftp_register get the same access_hash.
Related MCP server: sftp-mcp
FTP Tools
Tool | Usage |
| Registers the hash. Without it, put/get are refused. |
| Revokes or lists hashes from this agent. |
| Sends. Requires |
| Downloads. Requires the same |
| Lists this hash's channel (content + metadata). |
| Metadata only (path or hash). |
| Integrity audit. |
| Search by path, hash, title, kind, columns… |
| FTP-style navigation. |
doc_* continues for collaborative editing (lock + doc_commit) of the document linked to the path.
Resources: fileagent://fs, fileagent://docs, fileagent://blob/{hash}.
Extracted Metadata
On ftp_put / ftp_stat / ftp_ls:
always:
hash,size,mime,kind,filename,extensiontext / markdown: title, headings, lines, words, language (
pt/en)JSON: validity, type, keys
CSV: columns and number of rows
PNG / JPEG / GIF: width and height
PDF: version, title/author if present in the header
Admin and Password
Only the admin registers access_hash. The plaintext password stays only in the project's .venv (outside git):
hash:
.venv/fileagent_admin.hash(PBKDF2-SHA256)password:
.venv/fileagent_admin.password
uv run fileagent --init-admin # gera se ainda não existir
uv run fileagent --rotate-admin # nova senhaBrowser panel: open / and enter that password to see all files from all channels. Without login, the list does not appear.
# cadastrar um canal para clientes
curl -sS -X POST http://127.0.0.1:8765/v1/admin/register \
-H "Content-Type: application/json" \
-d '{"admin_password":"<senha>","label":"equipe-a"}'Clients do not register hashes. They use the access_hash returned in POST /v1/files or ftp_put.
Going Live
uv run fileagent --http --host 0.0.0.0 --port 8765Admin panel (login):
http://<host>:8765/MCP:
http://<host>:8765/mcpREST:
POST/GET /v1/fileswith headerX-Access-HashHealth:
GET /healthz
Skills
fileagent-send— agents that sendfileagent-receive— agents that list/download
Installation
cd /Users/naubergois/FileAgent
uv sync --extra devCursor (same store between agents)
{
"mcpServers": {
"fileagent": {
"command": "uv",
"args": ["--directory", "/Users/naubergois/FileAgent", "run", "fileagent"],
"env": {
"FILEAGENT_DATA_DIR": "/Users/naubergois/.fileagent",
"FILEAGENT_AGENT_ID": "cursor",
"FILEAGENT_OPEN_EDIT": "1"
}
}
}
}Each agent: same FILEAGENT_DATA_DIR, distinct FILEAGENT_AGENT_ID.
HTTP
uv run fileagent --http --port 8765Variables
Variable | Default | Function |
|
| SQLite + blobs. Same path = same FTP. |
|
| Who sent / edited. |
|
| Store agents edit |
|
|
|
private paths are only visible to the owner (and grants). agent_id is coordination, not strong authentication. Content security is the hash: if the bytes change, the read fails.
Current production (AWS): https://fileagent.54-204-243-102.sslip.io/ — panel with admin password.
Tests
uv run pytest -qAvailable Tools
31 toolsdoc_checkoutB
Adquire lock de edição e devolve content + hash + lock_token. Outro agente recebe code=locked.
Inputs: doc_id (required), agent_id, share_token, ttl_seconds. Returns: object
doc_claimB
Resgata um share_token e grava grant permanente para este agente.
Inputs: share_token (required), agent_id. Returns: object
doc_commitA
Grava a edição do checkout. Exige lock_token e expected_hash. Libera o lock salvo keep_lock=true.
Inputs: doc_id (required), lock_token (required), expected_hash (required), content, +4 more. Returns: object
doc_createB
Cria um documento editável. O doc_id padrão é o hash do conteúdo inicial — compartilhe esse id.
Inputs: title (required), mime, tags, doc_id, +4 more. Returns: object
doc_forkC
Cria um documento novo a partir de um doc_id ou de um hash imutável.
Inputs: hash, title, doc_id, agent_id, +1 more. Returns: object
doc_getA
Lê um snapshot imutável pelo hash (ou prefixo único). Não segue o ponteiro do documento.
Inputs: hash (required), agent_id. Returns: object
doc_historyC
Cadeia de versões (hash ← parent_hash) com o agente que commitou cada uma.
Inputs: doc_id (required), limit, agent_id. Returns: object
doc_infoB
Metadados do documento sem o conteúdo (hash atual, versão, lock, dono).
Inputs: doc_id (required), agent_id, share_token. Returns: object
doc_listB
Lista documentos visíveis para este agente. query filtra título, tags, hash e preview.
Inputs: limit, query, agent_id. Returns: object
doc_putB
Guarda um blob imutável e devolve o hash SHA-256. Mesmo conteúdo = mesmo hash.
Inputs: mime, content, agent_id, content_base64. Returns: object
doc_readB
Lê a versão atual de um documento (doc_id) ou um blob (hash). Aceita share_token.
Inputs: hash, doc_id, agent_id, share_token, +1 more. Returns: object
doc_releaseA
Libera o lock sem gravar (checkout abandonado).
Inputs: doc_id (required), lock_token (required), agent_id. Returns: object
doc_searchC
Busca documentos por título, tags, hash ou trecho do preview.
Inputs: query (required), limit, agent_id. Returns: object
doc_updateB
Atualiza com compare-and-swap. Falha com code=conflict se expected_hash não for o atual.
Inputs: doc_id (required), expected_hash (required), mime, title, +7 more. Returns: object
ftp_cpC
Copia arquivo dentro do mesmo access_hash.
Inputs: dst (required), src (required), access_hash (required), agent_id. Returns: object
ftp_findB
Busca arquivos deste access_hash por path, hash de conteúdo ou metadados.
Inputs: query (required), access_hash (required), limit, agent_id. Returns: object
ftp_getB
Baixa arquivo. Exige o mesmo access_hash cadastrado usado no put. Recalcula SHA-256.
Inputs: path (required), access_hash (required), agent_id, expected_hash, +1 more. Returns: object
ftp_hashesA
Lista hashes. Com senha admin lista todos; sem ela, só os criados por este agente.
Inputs: agent_id, admin_password. Returns: object
ftp_lsA
Lista o diretório deste access_hash. Cada arquivo vem com hash de conteúdo e metadados.
Inputs: access_hash (required), path, query, agent_id. Returns: object
ftp_metaB
Só metadados extraídos. Exige access_hash. Por path ou pelo hash do conteúdo.
Inputs: access_hash (required), hash, path, agent_id. Returns: object
ftp_mkdirC
Cria diretório neste hash cadastrado.
Inputs: path (required), access_hash (required), agent_id. Returns: object
ftp_mvC
Move/renomeia path dentro do mesmo access_hash.
Inputs: dst (required), src (required), access_hash (required), agent_id. Returns: object
ftp_putB
Envia arquivo. Exige access_hash cadastrado (ftp_register). Grava SHA-256, verifica disco e extrai metadados.
Inputs: path (required), access_hash (required), mime, content, +5 more. Returns: object
ftp_registerA
Admin: cadastra um access_hash. Exige senha do admin. Clientes usam o hash gerado em put/get.
Inputs: admin_password (required), hash, label, secret, +4 more. Returns: object
ftp_revokeA
Admin: revoga um hash cadastrado. put/get com ele passam a falhar.
Inputs: access_hash (required), admin_password (required), agent_id. Returns: object
ftp_rmA
Remove arquivo ou diretório neste hash. Pasta não vazia exige recursive=true.
Inputs: path (required), access_hash (required), agent_id, recursive. Returns: object
ftp_statB
Metadados de um path neste hash cadastrado, sem o conteúdo.
Inputs: path (required), access_hash (required), agent_id. Returns: object
ftp_verifyC
Recalcula SHA-256 no disco. Exige access_hash. Disco alterado → tampered.
Inputs: access_hash (required), hash, path, agent_id. Returns: object
healthB
Saúde do FTP: data_dir, arquivos, hashes cadastrados e identidade deste agente.
Inputs: agent_id. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 31 tools
Several tools have overlapping functionality, making it unclear which to use. For example, ftp_put and doc_put both store content and return a SHA-256 hash, ftp_get and doc_get both retrieve content by hash, and ftp_stat and ftp_meta both retrieve metadata. This redundancy increases the risk of misselection.
The naming mostly follows a consistent pattern of prefix (ftp_ or doc_) plus a verb (put, get, ls, stat, etc.), with only a few exceptions like ftp_hashes and ftp_register. Overall, the naming is predictable and semantically aligned with the action.
With 31 tools, the server is on the higher end but not excessive. However, the count is inflated by redundant operations (e.g., ftp_stat vs. ftp_meta, ftp_ls vs. doc_list) and a clear split between file management and document management, which could be streamlined without loss of functionality.
The toolset covers CRUD for files and documents, versioning, locking, sharing, and admin functions. However, there is no explicit document deletion tool (doc_delete), and the distinction between immutable blobs and editable documents is not fully addressed (e.g., doc_update exists but no corresponding ftp_update). This leaves minor gaps in lifecycle management.
Maintenance
Related MCP Connectors
Persistent file storage for AI agents via MCP and curl. Upload, download, and version files.
Persistent file storage for AI agents. Save files over MCP, get a link a human can open.
A real-time, multiplayer filesystem for agents and humans: shared files, live edits, history.
Searchable storage for AI agents: store, find, read and trust artifacts shared between agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that provides AI agents with a persistent, PostgreSQL-backed virtual filesystem, supporting session-isolated file operations, cross-session shared stores, and glob/grep search.1161 npm3MIT
- AlicenseNot gradedqualityDmaintenanceProvides a browsable, mutable SFTP filesystem for AI agents, supporting file operations like listing, uploading, downloading, moving, and deleting.MIT
- AlicenseNot gradedqualityCmaintenanceAn MCP server that gives AI agents file system access: read, write, search, hash, directory trees — 12 tools, zero dependencies, pure Python stdlib.MIT
- FlicenseNot gradedqualityDmaintenanceProvides versioned file storage for AI agents with immutable writes, auditing, and rollback capabilities.1-