For AI agents

AQUA agent guide

AQUA is founder-first application infrastructure for answer reuse. It is local-first: a user’s private answers live in an encrypted vault in their browser and, if they choose, in an encrypted companion workspace on their own computer. They are never stored on AQUA’s servers. An agent helps by running the AQUA companion on the user’s machine: a command-line tool and stdio MCP server with 43 tools over one consented workspace plus the public catalog.

Markdown: /agents.md · /llms.txt · /llms-full.txt · manifest /.well-known/mcp

1. Install

Primary: aqua-mcp-server from npm (Node.js 22 or newer). It includes the companion and serves the same tools.

npx -y aqua-mcp-server --help

Fallback: the companion also ships as a versioned tarball from this site (no dependencies):

npx --yes https://aquaidp.xyz/companion/aqua-companion-0.2.5.tgz --help

sha256 b3a686c1a7cd6ca0b663aced6a6562e2bf1abf0d8761f5724331820d1ab31aef (also at aqua-companion-0.2.5.tgz.sha256; latest.json lists the current version).

  • From a downloaded, verified copy: npx --yes --package <path>/aqua-companion-0.2.5.tgz aqua-companion --help (pass the file with --package; npx treats a bare absolute .tgz path as a program and fails).
  • npm: aqua-companion is also published on npm. aqua-mcp-server on npm includes it and is the primary install, so use that; the tarball above is the fallback.
  • aqua-mcp-server is published on npm and is the primary install: `npx -y aqua-mcp-server`. It includes the companion and serves the same tools. Versions below 2.0 are legacy and must not be used.
  • Self-check: npx --yes https://aquaidp.xyz/companion/aqua-companion-0.2.5.tgz doctor

2. Connect it to the agent

claude mcp add aqua -- npx -y aqua-mcp-server --keychain

Tarball fallback: claude mcp add aqua -- npx --yes https://aquaidp.xyz/companion/aqua-companion-0.2.5.tgz mcp --keychain

The server starts even when no workspace exists yet; workspace tools then return workspace_not_initialized with next steps. init --path <folder> creates <folder>/AQUA; the server and the CLI find a workspace only through --workspace, AQUA_WORKSPACE, or the folder they run in (or a parent). After init, re-add the server with the workspace and restart the client:

claude mcp add aqua -- npx -y aqua-mcp-server --workspace <folder>/AQUA --keychain

--keychain reads the passphrase from a macOS Keychain item the user creates once after init: security add-generic-password -s aqua-companion -a <workspace id> -w (the workspace id is in aqua-companion status). Without that item, drop --keychain and give the server AQUA_PASSPHRASE in its own environment instead.

3. Workspace setup and consent

  • locate_workspace reports where a workspace is, or would be created.
  • init_workspace uses MCP elicitation when the client supports it: the user confirms the folder and consent in the client UI, outside the model. Otherwise it returns requires_human with the exact command, for example aqua-companion init --path <folder>.
  • The passphrase is typed by the user (terminal prompt, macOS Keychain or the server environment). It never travels through the model or a tool argument.
  • The agent reads files only from the workspace inbox/ folder.

4. Tiers

Every tool declares a tier, and the server enforces it in code.

  • read (22): Always allowed. Only reads the workspace or the public catalog cache.
  • private_write (15): Stages private records in the user's local workspace (drafts, imports, evidence). Refused in --read-only mode. Never approves anything.
  • human_consent (1): Acts only after the human confirms in the MCP client UI (elicitation). Without that capability it returns requires_human with the exact command for the user to run.
  • human_only (5): Never acts. Returns requires_human with the steps the user takes in the AQUA browser app (approve, sign, freeze/export, submit, attest).

5. Submitted history

The user copies past submitted applications into a folder inside inbox/ (for example inbox/history/); import_history { folder: "history" } stages each answer with its exact question, program, source hash and submission date (unknown dates are flagged, never guessed). After aqua-companion export-backup and Restore, the user confirms them at /history. Confirmed answers count as approved as of their submission date. Answers with unfilled placeholders can never be confirmed; the vault refuses them.

6. The human approves in the browser

  1. The user runs aqua-companion export-backup <file> --workspace <folder>/AQUA.
  2. In the browser: AQUA Local, Restore backup, then review and approve each answer on the review board. Approval binds the exact version hash.
  3. The user exports a browser backup into the workspace inbox/.
  4. The agent runs sync_from_vault_export; read_review_status then shows the approvals.
  5. prepare_packet reports readiness; the user freezes and exports in the browser; verify_packet checks the export. The agent never submits anything.

7. Public catalog configuration

/.well-known/aqua-catalog.json returns {version, supabase_url, publishable_key, tables, notes}. The key is the public publishable/anon key the web app already ships to every browser. Clients must use the publishable/anon key only; they refuse any other role and fetch the configuration only from https://aquaidp.xyz (or a local override file).

The companion keeps a public catalog cache: discover_applications, get_application_details and match_canonical_questions refresh an empty or stale cache (older than 24 hours; AQUA_CATALOG_MAX_AGE_HOURS changes it, 0 turns it off) with the same public read-only request as refresh_catalog. Offline or unconfigured, they answer from the cache and return catalog_empty: run refresh_catalog when there is nothing cached.

8. Hosted read-only MCP

https://aquaidp.xyz/mcp: live (public catalog tools for everyone; personal workspace tools for signed-in users (Bearer OAuth, caller-JWT RLS); rate-limited).

9. Intentionally absent

  • publish_catalog_entry: Catalog publication needs reviewer authorization and source verification in the AQUA service; the agent can only prepare a candidate.
  • run_migration: Database migrations change production permissions and require explicit owner authorization.
  • admin_platform: Platform administration (users, roles, billing, teams) is not a user capability.
  • configure_security: Security configuration (RLS, keys, service-role access) is owner-only and never handled by agents.
  • read_hosted_answers: Private answers live in the browser vault and this workspace; the agent never gets database or service-role access.
  • TRANSPORT=http (self-hosted HTTP): 1.x served unauthenticated write-capable HTTP. 2.0 has stdio locally and the read-only hosted endpoint only.
  • No service-role key exists anywhere in the agent path. Hosted workspace tools require the user's own Bearer session; every call runs under caller-JWT row-level security.

Tools (43)

ToolTierWhat it does
add_questionprivate_writeManually index one question in an application with its exact source wording — for fields the extractor missed or fields added after a later capture.
approve_answerhuman_onlyNever executes.
assemble_applicationprivate_writeBuild a Markdown application from explicitly chosen APPROVED answer versions plus the unresolved fields and provenance.
attach_evidenceprivate_writeStage an evidence record for a file — from inbox/, or uploaded as file_name + content_base64, or identified by file_sha256 alone (only the hash is recorded) — and optionally link it to a version.
attest_submissionhuman_onlyNever executes.
create_draft_versionprivate_writeStage a NEW, unapproved draft version of an answer in this workspace (method recorded as an agent draft).
discover_applicationsreadSearch the cached public AQUA catalog (approved programs) and list the applications in this workspace.
doctorreadSelf-check: Node and companion version, the public catalog configuration (source, origin, key role: only anon/publishable is accepted), connectivity and a canonical-only catalog read (counts only), workspace and macOS…
export_packethuman_onlyNever executes.
get_application_detailsreadFull template of one application: exact question wording, parsed requirements (limits, required, time context, qualifiers), deadline and time zone, and where the data came from and how it was verified.
hub_find_similar_questionsreadFind canonical questions in the approved catalog that ask about the same thing as the given text (lexical similarity over question wording and its recorded variants; no embeddings, nothing stored).
hub_get_acceptance_statsreadPublic acceptance figures for one approved canonical program: acceptance rate and application count where public, and counts of verified applicant-reported outcomes by cohort (counts only, never who reported).
hub_get_heat_scoresreadApproved canonical programs ranked by heat score (current applicant interest and deadline pressure).
hub_get_program_by_slugreadOne approved canonical program by slug with its public stats and theme weights (DNA) in a single call.
hub_get_program_detailreadFull public detail for one approved canonical program by program_id or slug: deadlines, cycles, rolling/cohort, value and acceptance figures where public.
hub_get_program_questionsreadThe application questions of one approved canonical program in display order: exact wording (in untrusted_content), word and character limits, required flag, theme, and how many approved programs ask the same canonica…
hub_get_program_rankingsreadApproved canonical programs ranked by program value score (what you get versus what you give up, relative to application effort).
hub_get_program_themesreadTheme weight breakdown of one approved canonical program (what it emphasizes, from its questions), by program_id or slug.
hub_get_question_significancereadHow much one canonical question matters across approved programs: how many ask it and what share of approved programs that is, typical limits, theme, and which programs ask it.
hub_get_universal_questionsreadCanonical questions asked by most approved programs: the ones to answer first.
hub_search_programsreadSearch approved canonical AQUA programs (accelerators, grants, fellowships, VC and other programs) by words, type, status, equity, cash, rolling and deadline window.
import_historyprivate_writeBatch-stage applications the user ALREADY SUBMITTED (a folder inside the workspace inbox/, .md .txt .docx .html .json .csv) as history records: exact question wording, the submitted answer, program, source file sha256…
import_local_applicationprivate_writeStage a private local application from a file the user placed in the workspace inbox/ folder (.txt, .md, .html, .csv, .json, .docx).
init_workspacehuman_consentCreate an encrypted AQUA workspace ONLY after the user confirms the folder and consent in the MCP client UI (elicitation).
inspect_extracted_questionsreadShow how the questions of a workspace application were extracted: exact wording, parsed requirements, source location, and items the parser was unsure about.
link_answerprivate_writeMark an approved answer version as a direct-reuse candidate for a later question.
link_historyprivate_writeRecord a relevance link between an imported history answer (a submitted, unconfirmed record) and a workspace question.
locate_workspacereadWhere the AQUA workspace is (or would be created): whether this server has one open, the configured path, the folders searched, and the exact init command.
mark_questionprivate_writeMark a question not_applicable (hidden by an observed branch), skipped (known optional field deliberately left blank), or clear it back to open — always with a reason.
match_canonical_questionsreadMatch an application's questions (or given question texts) against canonical questions in the cached public catalog with the tiered matcher (exact, normalized, semantic, novel).
prepare_catalog_candidateprivate_writeBuild a sanitized public catalog candidate (program, deadlines, public question wording only) from a staged application imported with a public source_url.
prepare_packetreadReadiness report for freezing an application packet: per question the selectable approved version, whether its approval is bound to the exact hash, length limits, required questions, and content integrity.
present_review_decisionsprivate_writeBuild the offline AQUA review file (HTML, containing the user's answers in plain text) for one application and save it under exports/reviews/ (at most 25 files are kept; refused under --read-only).
read_review_statusreadDerived review status of every question in an application (gap, suggested, needs evidence, under review, approved, ...) and the Direct / Adapt / Gap reuse recommendation against the rest of the answer bank.
record_observed_submissionprivate_writeStore an observation that an application may have been submitted (for example a confirmation e-mail the user saved in inbox/, or uploaded as file_name + content_base64), flagged requires_human_attestation.
refresh_catalogreadFetch approved canonical programs, cycles and questions from the configured public AQUA catalog endpoint (read-only, public key, nothing from the workspace is sent).
request_evidenceprivate_writeRecord an evidence gap on a version (what support is missing).
search_answer_bankreadSearch the user's private answers, versions, facts and evidence in this workspace (decrypted in memory only).
sign_packethuman_onlyNever executes.
submit_catalog_candidatehuman_onlyNever executes.
sync_from_vault_exportprivate_writeImport an encrypted backup the user exported from the AQUA browser vault and placed in the workspace inbox/ (the same checks as "aqua-companion import-backup": integrity, account binding, conflicts recorded, nothing o…
update_questionprivate_writeAdd interpretation or correct metadata on a question — summary, general/custom kind, topic, group, required status, limit, visible options — without ever changing the captured source wording.
verify_packetreadVerify an exported AQUA packet JSON placed in inbox/ (or packets/), or uploaded as file_name + content_base64: canonical manifest, manifest hash, packet id, per-answer hashes, provenance receipts and the signature if …

The fresh-agent journey

  1. Install: npx -y aqua-mcp-server --help (primary, from npm). Fallback: the companion tarball, npx --yes https://aquaidp.xyz/companion/aqua-companion-0.2.5.tgz --help (check the published sha256 first; for a downloaded copy use npx --yes --package <path>.tgz aqua-companion)
  2. Set up a workspace: init_workspace (the user confirms the folder in the MCP client) or the user runs `aqua-companion init --path <folder>`, which creates <folder>/AQUA; then restart the MCP server with --workspace <folder>/AQUA. The passphrase is typed by the user, never sent through the model
  3. Load submitted history: the user copies past submitted applications into a folder inside the workspace inbox/ (for example inbox/history/); import_history { folder: "history" } stages them; the user exports a backup and confirms them at https://aquaidp.xyz/history
  4. Ingest the application: import_local_application (a file in inbox/) or get_application_details for a catalog program
  5. Match and reuse: match_canonical_questions, search_answer_bank, read_review_status (Direct / Adapt / Gap)
  6. Draft: create_draft_version stages unapproved drafts; request_evidence / attach_evidence
  7. Human review and approval: the user runs export-backup <file> --workspace <folder>/AQUA, restores it at https://aquaidp.xyz/aqua-local and approves each answer on the browser review board
  8. Return approvals to the agent: the user exports a browser backup into inbox/; sync_from_vault_export imports it; read_review_status shows approved with the hash preserved
  9. Packet: prepare_packet (readiness), the user freezes/exports in the browser, verify_packet checks the export. Nothing is ever submitted by the agent.

The Contribution Exchange is not part of AQUA; it lives at signalaf.com/exchange.