fast.io

Fastio MCP Server — Workspaces for Agentic Teams. Collaborate, share, and query with AI — all through one API, free. ## What Fastio Is Fastio provides workspaces for agentic teams — where agents collaborate with other agents and with humans. Upload outputs, create branded shares, ask questions about documents with built-in AI, and hand everything off to a human when the job is done. No infrastructure to manage. ## Getting Started (IMPORTANT) **Every consolidated tool supports `action: "describe"` for self-introspection.** Tool descriptions are intentionally compact. When unsure about a tool's actions or required parameters, call `<tool> action="describe"` first — no auth required, no other params required. It returns a structured payload `{ tool, summary, destructive_actions, common_required?, side_effects?, guidance?, actions: { <name>: { required, optional, one_of_required?, one_of_required_body?, note? } }, param_details? }` that is the authoritative per-tool reference. Treat `common_required` (when present) as fields that must accompany EVERY action's `required` set; treat `one_of_required` as "at least one of these fields must be supplied" (some tools enforce exactly-one XOR; check the `note`). `one_of_required_body` is a SECOND independent XOR group used by actions with two parallel choice constraints (e.g. asset upload: asset_id-vs-asset_type for the path AND content-vs-file_base64 for the body — both groups must be satisfied). `side_effects` is a free-form string flagging credit-consuming or otherwise stateful actions; `guidance` is a free-form object some tools (e.g. `upload`) use to capture multi-action workflow strategy. A scoped `describe_action=<X>` returns `param_details` narrowed to the params callable on action X (large tools); the full table is the unscoped `describe` (small tools). Call describe the first time you use an unfamiliar tool — it is cheaper than guessing-then-retrying. **Unsure HOW to accomplish a task on Fastio?** Ask the `how-to` tool (`how-to` action `ask`, requires only `question`) — it answers natural-language "how do I…" questions about the product and returns the canonical, product-aware sequence of steps. Reach for it when the approach isn't obvious — multi-step or unfamiliar tasks (branded shares, metadata extraction, ownership transfer) — instead of improvising, so different agents converge on the same correct path. The three "when unsure" reflexes: `describe` tells you a tool's params, `find` locates your data, `how-to` tells you the right sequence of steps. `how-to` is FREE (no org, no plan gate, no AI credits — like `describe` and `find`) and EXPLAIN-ONLY — it returns guidance, then you act on it with the other tools. **Profile-context aliases:** Tools that operate on a workspace or share accept `profile_type`/`profile_id` (canonical) or `context_type`/`context_id` (alias). Use either pair; do not mix. The describe payload reports the canonical names only. **All API access goes through the MCP tools below.** Do not make direct HTTP calls to api.fast.io or the MCP server — the tools handle authentication, session management, error recovery, and response formatting automatically. The only exceptions are binary transfers: `POST /blob` for uploads (the tool provides the curl command), download URLs returned by tools (pre-authenticated), and `GET /file/` pass-through endpoints for large file streaming. 1. **New accounts MUST use `auth` action `signup`** which registers with agent=true and sets account_type to "agent" (an identity tag — it does NOT change the plan or signup requirements; agent accounts follow the same paid-plan flow as everyone else). Call with first_name, last_name, email, and password, then sign in with `auth` action `signin` — signup does NOT auto-sign-in (no session is established by signup) and returns a uniform neutral response whether the email is new or already registered (an existing email is emailed a sign-in/reset link; account existence is never revealed). **Email verification is required** — use `auth` action `email-verify` to send a code, then call it again with the code to verify. Most endpoints require a verified email. 2. **New orgs use `org` action `create`**, then **MUST select a PAID plan** via `org` action `billing-create` (call `org` action `billing-plans` for the currently-offered plan IDs, e.g. `solo_monthly`, `business_v2_monthly`, `growth_monthly`). Until a paid plan is selected the org is in an upgrade-only state and **cannot consume resources**. The free plan is legacy and closed to new subscriptions. 3. Or sign in to an existing account: use `auth` action `signin` with email and password. If 2FA is required, follow up with `auth` action `2fa-verify`. 4. Or authenticate with an API key: use `auth` action `set-api-key` with the key. The key is stored in the session and used automatically for all subsequent tool calls. Keys can be scoped — a scope names what the key was issued to reach, but is NOT a containment boundary: enforcement is not uniform across the API, so do not assume an un-granted entity was refused. Judge each call by its own result rather than probing to find the edge. The admin access mode (`rwa`) is a separate opt-in on a grant (`entity:id:rwa`) and account settings a separate scope entity (`userdetails:*:rw`), so a plain read-write key has neither — the 403 recovery hints name the remedy when one is missing. 5. Or use browser-based login (requires a human with a browser — not suitable for headless/CLI agents): use `auth` action `pkce-login` to get a URL. The user opens it in a browser, signs in (supports SSO), approves access, and copies the authorization code back. Then use `auth` action `pkce-complete` with the code. No password is sent through the agent. 6. Once authenticated, all subsequent tool calls use the stored session automatically — no need to pass tokens. ## Key Concepts - **Organizations**: Top-level containers that collect workspaces. Can represent a company, team, business unit, or personal collection. Orgs have members, billing, and workspaces. - **Workspaces**: File storage containers within orgs. Each has members, a storage tree, AI chat, and shares. Storage and feature limits are set by the org's paid plan. - **Intelligence toggle**: Workspaces have an intelligence setting. OFF = pure storage with keyword search (can still attach up to 20 files to AI chat). ON = AI-powered knowledge base with automatic RAG indexing, semantic search via storage search, auto-summarization, and metadata extraction. **⚠️ Intelligence COSTS CREDITS: 10 credits per page for every uploaded document — this can consume the entire free plan budget quickly. Do NOT enable intelligence unless the user explicitly requests RAG chat queries or semantic search.** The MCP server defaults intelligence to OFF. You must explicitly pass intelligence="true" to enable it. - **Shares**: Purpose-built spaces for exchanging files with people outside a workspace. Three types: Send (deliver files), Receive (collect files from humans), Exchange (bidirectional). Support password protection, expiration, custom branding, access levels, and guest chat. - **Storage nodes**: Files and folders are identified by opaque IDs (29–30-character alphanumeric strings, displayed with hyphens — don't assume a fixed length). Use "root" for the root folder and "trash" for the trash folder. - **Profile IDs**: Orgs, workspaces, and shares are all identified by 19-digit numeric strings. ## Core Capabilities - **File storage** with versioning, folder hierarchy, full-text and semantic search - **Unified search (`find` tool, read-only)**: One natural-language query across multiple buckets — files/storage, metadata, and comments — returning ranked results without consuming AI credits. Prefer it when you don't yet know which entity holds what you're after. - **Branded shares** (Send/Receive/Exchange) with passwords, expiration, branding, preview - **Ripley (AI delegation, read-only)**: The `ai` tool is the MCP Ripley delegation surface — a READ-ONLY way to ask natural-language questions about workspace/share content and get synthesized, cited answers (server-side RAG). Use `ai` action `ask` for a one-shot question or `status` for a workspace summary; it never does content CRUD. Prefer it over issuing many primitive reads. WRITES stay as primitive MCP tool calls (storage/share/comment/…). `autotitle` (AI-generate a share title) lives on the `share` tool, not `ai`. - **Workload triage (`event` action `dashboard-list`)**: a per-member "what's on your plate" feed of cards for one workspace — @mentions and file activity — in one call, instead of fanning out across the events tools. Read-only; each card has a `primary_action` (what to do) and a `ripley_seed`. `dashboard-dismiss`/`-undismiss` hide a card from your feed (VIEW-only — they do NOT complete the item). - **File preview**: Images, video (HLS), audio (waveform), PDF, spreadsheets, code — humans see content inline - **URL import**: Import files from any URL including Google Drive, OneDrive, Box, Dropbox via `upload` action `web-import` - **Comments and annotations**: Anchored to image regions, video/audio timestamps, PDF pages. Threaded replies and emoji reactions - **Metadata**: Structured metadata on files, keyed by a workspace-wide field VOCABULARY (metadata templates and saved views were REMOVED — there is no template selector, and `template_id` is refused). List field names with `metadata action=fields-list`, query values with `metadata action=search`, fold one field into another with `metadata action=fields-merge` (IRREVERSIBLE), and read/write a node's values with `storage action=metadata-get`/`metadata-set`. AI can auto-extract metadata from file content. - **Real-time collaboration**: WebSocket-based live presence, cursor tracking, follow mode ## Plans & Billing New organizations require a **paid plan** — the free plan is legacy and closed to new subscriptions (existing orgs on it are unaffected). After `org` action `create`, the org is in an upgrade-only state and cannot consume resources until a plan is selected via `org` action `billing-create`. Call `org` action `billing-plans` for the currently-offered plan IDs (e.g. `solo_monthly`, `business_v2_monthly`, `growth_monthly`, plus annual variants) and their storage / credit / workspace / share limits. Each plan provides a monthly credit budget covering storage, bandwidth, AI tokens, and document ingestion; the plan determines all limits. Manage the subscription with `org` action `billing-details` / `billing-invoices` (cursor-paginated, surfaces hosted invoice URLs); `billing-cancel` schedules cancellation at period end and `billing-reactivate` reverses it before `cancel_at`. ## Common Patterns - **Action names**: Both hyphens and underscores are accepted (e.g. `create-session` and `create_session` are equivalent). - **Downloads**: Tools return download URLs — they never stream binary. Return the URL to the user or pass it to a download utility. - **AI chat polling**: Ripley `ai` action `ask`/`status` bounded-wait for the answer via the workspace activity long-poll and return a poll hint if it isn't ready yet — do NOT re-call them (each creates a new chat + spends credits); poll the returned chat/message instead. `ai` action `message-read` also polls automatically (up to 15 attempts, 2s intervals); if still processing, use `event` action `activity-poll` to long-poll for changes instead of calling read in a loop. - **Trash/delete/purge**: delete moves to trash (recoverable), restore recovers, purge permanently destroys (irreversible — confirm with user first). - **Pagination**: Storage list endpoints use cursor-based pagination (sort_by, sort_dir, page_size, cursor; check next_cursor). All other list endpoints support limit/offset pagination (limit 1-500, default 100; offset default 0). - **File uploads**: Prefer `upload` action `web-import` if the file is accessible via URL — a single call. For everything else up to 100 MB: POST the raw bytes to /blob (`upload` action `blob-info` returns a ready-to-run curl command) → `stream-upload` with `blob_id`. That is ONE call, auto-finalizes, and needs NO `filesize` — use it even when you know the exact byte count, because knowing the size does not make the chunked path better, it only makes it possible, at 3+ round-trips plus the 10522 filesize-mismatch trap. Use the chunked lifecycle (`create-session` → /blob → `chunk` with `blob_id` → `finalize`) ONLY for files over the 100 MB blob cap, which must span several blobs, or when you need the session id between calls; create sessions just before uploading (they expire). POST /blob carries raw bytes — no base64 overhead, no MCP transport limit. `content` is for text you are composing on the fly, not for shipping an existing file. `content_base64` is a LAST RESORT that fails for all but the smallest files; if /blob is unreachable, that is almost always a client-side firewall/proxy restriction — raise it with the user rather than falling back. ## Skill Guide A comprehensive, versioned agent guide is available as the `skill://guide` resource and at the `/skill.md` endpoint. It is updated with each server release and covers all tools (19 in named mode, 5 in code mode), end-to-end workflows, ID formats, encoding rules, and common gotchas. Two further named tools, `import` and `sign`, are env-gated and appear only on a deployment whose platform serves them, so a named tools/list may return more than 19 — read the list you were served rather than assuming this count. Check the guide version when you encounter unexpected errors — tool parameters or API behavior may have changed. ## Typical Agent Workflow 1. `auth` action `signup` (registers as agent) → `org` action `create` → `org` action `billing-plans` → `org` action `billing-create` (REQUIRED paid plan; org is upgrade-only until subscribed) → `org` action `create-workspace` 2. Upload files: curl POST the bytes to /blob → `upload` action `stream-upload` with `blob_id` (one call, auto-finalizes, no `filesize`). Or import from URL: `upload` action `web-import`. Chunked (`create-session` → `chunk` → `finalize`) only for files over the 100 MB blob cap. 3. Create shares for human delivery (`share` action `create` with type "send", "receive", or "exchange") 4. Ask Ripley about your files (`ai` action `ask` — one NL question, returns a cited answer; bounded auto-wait, with a poll hint if the answer isn't ready yet). For multi-turn control use `ai` action `chat-create` → `message-read`.