waafir-dataroom reference

The waafir-dataroom server is the stable API surface of this release. It exposes nineteen tools for reading and managing your data rooms, grouped by what they do: six read tools, four folder tools, five file tools, and four permission tools.

Connection: https://app.waafir.io/api/mcp/waafir-dataroom — see Setup.

How access is enforced

Every tool runs as the token's owner and is bounded by the same rules the product UI enforces — there is no looser path through MCP. Two gates apply on every call:

• Scope. Each tool states a minimum scope: read tools require read, folder and file mutations require write, and the permission-granting tools require admin. A token below the required scope is rejected (403). Scope is cumulative — write includes read, admin includes both.
• Data room scoping. If the token is restricted to specific data rooms, any call referencing a data room outside its allow-list is rejected, and a scoped token cannot even list the data rooms it is not allowed to open. The check is keyed on the data room a resource belongs to, so a token scoped to data room A can never reach a file or folder in data room B — even within the same organization.

In addition, folder and file mutations require a deal-team role for the data room (investors cannot mutate), and the permission tools additionally require the token owner to be an organization admin or manager. Deleting a folder or file is always a soft delete — rows are marked deleted and preserved for retention and audit, never hard-removed. Every mutation is recorded as the same audit event the product UI writes, so an MCP action is indistinguishable from a UI one in the audit log.

Identifiers (dataroom_id, folder_id, file_id, user_id) are UUIDs.

Read tools

Require read scope.

list_datarooms

List the data rooms the caller can access. For a token scoped to specific data rooms, the result is filtered to that allow-list. Archived data rooms are excluded.

• Inputs: none.
• Output: { datarooms: [{ id, name, description, org_name, created_at }] }.

get_dataroom

Get a single data room by id. The caller must be authorized for it; a token scoped to other data rooms is rejected.

• Inputs: dataroom_id (required).
• Output: { dataroom: { id, name } | null }.

list_folders

List folders in a data room. Honors deal-team vs investor visibility — an investor only sees folders they may read. List one level under a parent, or pass all for the whole tree. Deleted folders are excluded.

• Inputs: dataroom_id (required); parent_folder_id (optional — omit for top-level folders); all (optional boolean — true returns every folder in the data room).
• Output: { folders: [{ id, name, parent_folder_id, created_at }] }.

list_files

List active (non-deleted) files in a data room, optionally within a folder. Investor callers only see files they are permitted to read. Paginated.

• Inputs: dataroom_id (required); folder_id (optional — omit for files at the data room root); limit (optional, 1–200, default 50); offset (optional, default 0); sort_dir (optional, asc | desc, default desc).
• Output: { files: [{ id, name, folder_id, size_bytes, mime_type, created_at, updated_at }], pagination: { limit, offset, count } }.

get_file_metadata

Get metadata for a single file: name, MIME type, size, folder path, version list, and AI summary/category if present. The file must belong to the named data room; a file in another data room (even the same org) returns null.

• Inputs: dataroom_id (required); file_id (required).
• Output: { file: { id, name, mime_type, size_bytes, folder_id, folder_path, created_at, updated_at } | null, versions: [{ id, version_number, is_current, created_at }], ai_metadata: { summary, key_points, category, is_redacted } | null }.

search_dataroom

Search files by name within a single authorized data room (case-insensitive substring match). Deleted files are excluded.

• Inputs: dataroom_id (required); query (required, filename substring); limit (optional, 1–100, default 25).
• Output: { files: [{ id, name, mime_type, size_bytes, created_at }] }.

Folder tools

Require write scope and a deal-team role for the data room.

create_folder

Create a folder in a data room. Nest it under a parent, or omit the parent for the data room root. Rejects a duplicate name under the same parent (409).

• Inputs: dataroom_id (required); name (required, 1–255 chars); parent_folder_id (optional — null/omitted for the data room root).
• Output: { folder: { id, name, parent_folder_id } }.

rename_folder

Rename a folder. The folder must belong to the caller's organization.

• Inputs: folder_id (required); name (required, 1–255 chars).
• Output: { folder: { id, name } }.

delete_folder

Soft-delete a folder and its entire subtree (sub-folders and files). Rows are marked deleted, never hard-removed.

• Inputs: folder_id (required).
• Output: { deleted: true, folder_id }.

move_folder

Reparent a folder within the same data room. Nest it under another folder, or move it to the data room root. Rejects moving a folder into itself or a descendant (cycle), into a different data room, or where a sibling with the same name already exists.

• Inputs: folder_id (required); new_parent_folder_id (optional — null/omitted for the data room root).
• Output: { folder: { id, name, parent_folder_id } }.

File tools

File mutations require write scope; get_file_download_url requires only read. Uploading a file is a two-step flow — request a URL, PUT the bytes, then register the file.

request_file_upload

Request a presigned upload URL for a new file in a data room. Returns the URL and headers to PUT the bytes to, plus the file id. If a same-name active file already exists in the target folder, is_new_version is true and the returned id and version target that existing file.

• Scope: write.
• Inputs: dataroom_id (required); file_name (required, with extension); file_size (required, exact bytes, positive integer); mime_type (required); folder_id (optional — omit for the data room root).
• Output: { upload_url, headers, file_id, s3_key, is_new_version, version_number, mode? } (mode is "local" in development when no object store is configured).

register_file

Finalise a pending upload after PUTting the bytes from request_file_upload: marks the file active, increments org storage, and records version 1. When size_bytes is omitted it is derived from the uploaded object.

• Scope: write.
• Inputs: file_id (required, the pending id from request_file_upload); s3_key (required, the key returned by request_file_upload); size_bytes (optional).
• Output: { file_id, status: "active", version_number: 1 }.

rename_file

Rename a file — metadata only. This does not create a new version; versioning is for content replacement, not relabelling.

• Scope: write.
• Inputs: file_id (required); name (required).
• Output: { file_id, name }.

delete_file

Soft-delete a file: sets deleted_at and decrements org storage. The file row and its stored object/versions are preserved for retention and audit — never a hard delete.

• Scope: write.
• Inputs: file_id (required).
• Output: { file_id, status: "deleted" }.

get_file_download_url

Get a short-lived presigned download URL for a file. The caller must be authorized for the file (read scope plus the per-file read/download permission). The URL expires after a few minutes and returns the raw file (no watermark burn-in).

• Scope: read.
• Inputs: file_id (required).
• Output: { download_url, expires_in_seconds }.

Permission tools

These mutate who can see what. get_file_permissions requires only read; the three granting/revoking tools require admin scope and a token owner who is an organization admin or manager.

get_file_permissions

List the permission grants on a file (direct and folder-inherited). Mirrors the UI's file-permissions view.

• Scope: read.
• Inputs: dataroom_id (required); file_id (required).
• Output: { permissions: [{ user_id, can_read, can_download, access_revoked, expires_at, granted_by, created_at, source, source_folder_name?, source_folder_id? }] } (source is "direct" or "inherited").

set_file_permissions

Grant or update a user's read/download permission on a file. A read/write token, or an owner who is not an org admin or manager, is rejected.

• Scope: admin.
• Inputs: dataroom_id (required); file_id (required); user_id (required); can_read (required boolean); can_download (required boolean); expires_at (optional ISO timestamp, must be in the future).
• Output: { success: true, grant_count }.

invite_user_to_dataroom

Grant a known user data-room-level access at a given permission level — a direct access grant (not an email invite). Idempotent (upsert).

• Scope: admin.
• Inputs: dataroom_id (required); user_id (required); permission (required — one of viewer, downloader, contributor, manager); expires_at (optional ISO timestamp, must be in the future).
• Output: { success: true, grant_id }.

remove_user_from_dataroom

Revoke a user's data-room-level access (soft-revoke: sets revoked_at, preserving the audit trail). Returns revoked: false if the user had no active grant.

• Scope: admin.
• Inputs: dataroom_id (required); user_id (required).
• Output: { success: true, revoked }.