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 --helpFallback: 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 --helpsha256 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.tgzpath 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 --keychainTarball 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_workspacereports where a workspace is, or would be created.init_workspaceuses MCP elicitation when the client supports it: the user confirms the folder and consent in the client UI, outside the model. Otherwise it returnsrequires_humanwith the exact command, for exampleaqua-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
- The user runs
aqua-companion export-backup <file> --workspace <folder>/AQUA. - In the browser: AQUA Local, Restore backup, then review and approve each answer on the review board. Approval binds the exact version hash.
- The user exports a browser backup into the workspace
inbox/. - The agent runs
sync_from_vault_export;read_review_statusthen shows the approvals. prepare_packetreports readiness; the user freezes and exports in the browser;verify_packetchecks 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)
| Tool | Tier | What it does |
|---|---|---|
add_question | private_write | Manually index one question in an application with its exact source wording — for fields the extractor missed or fields added after a later capture. |
approve_answer | human_only | Never executes. |
assemble_application | private_write | Build a Markdown application from explicitly chosen APPROVED answer versions plus the unresolved fields and provenance. |
attach_evidence | private_write | Stage 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_submission | human_only | Never executes. |
create_draft_version | private_write | Stage a NEW, unapproved draft version of an answer in this workspace (method recorded as an agent draft). |
discover_applications | read | Search the cached public AQUA catalog (approved programs) and list the applications in this workspace. |
doctor | read | Self-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_packet | human_only | Never executes. |
get_application_details | read | Full 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_questions | read | Find 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_stats | read | Public 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_scores | read | Approved canonical programs ranked by heat score (current applicant interest and deadline pressure). |
hub_get_program_by_slug | read | One approved canonical program by slug with its public stats and theme weights (DNA) in a single call. |
hub_get_program_detail | read | Full 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_questions | read | The 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_rankings | read | Approved canonical programs ranked by program value score (what you get versus what you give up, relative to application effort). |
hub_get_program_themes | read | Theme weight breakdown of one approved canonical program (what it emphasizes, from its questions), by program_id or slug. |
hub_get_question_significance | read | How 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_questions | read | Canonical questions asked by most approved programs: the ones to answer first. |
hub_search_programs | read | Search approved canonical AQUA programs (accelerators, grants, fellowships, VC and other programs) by words, type, status, equity, cash, rolling and deadline window. |
import_history | private_write | Batch-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_application | private_write | Stage a private local application from a file the user placed in the workspace inbox/ folder (.txt, .md, .html, .csv, .json, .docx). |
init_workspace | human_consent | Create an encrypted AQUA workspace ONLY after the user confirms the folder and consent in the MCP client UI (elicitation). |
inspect_extracted_questions | read | Show how the questions of a workspace application were extracted: exact wording, parsed requirements, source location, and items the parser was unsure about. |
link_answer | private_write | Mark an approved answer version as a direct-reuse candidate for a later question. |
link_history | private_write | Record a relevance link between an imported history answer (a submitted, unconfirmed record) and a workspace question. |
locate_workspace | read | Where 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_question | private_write | Mark 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_questions | read | Match 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_candidate | private_write | Build a sanitized public catalog candidate (program, deadlines, public question wording only) from a staged application imported with a public source_url. |
prepare_packet | read | Readiness 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_decisions | private_write | Build 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_status | read | Derived 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_submission | private_write | Store 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_catalog | read | Fetch approved canonical programs, cycles and questions from the configured public AQUA catalog endpoint (read-only, public key, nothing from the workspace is sent). |
request_evidence | private_write | Record an evidence gap on a version (what support is missing). |
search_answer_bank | read | Search the user's private answers, versions, facts and evidence in this workspace (decrypted in memory only). |
sign_packet | human_only | Never executes. |
submit_catalog_candidate | human_only | Never executes. |
sync_from_vault_export | private_write | Import 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_question | private_write | Add 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_packet | read | Verify 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
- 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)
- 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
- 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
- Ingest the application: import_local_application (a file in inbox/) or get_application_details for a catalog program
- Match and reuse: match_canonical_questions, search_answer_bank, read_review_status (Direct / Adapt / Gap)
- Draft: create_draft_version stages unapproved drafts; request_evidence / attach_evidence
- 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
- 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
- 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.