AQUA Application Hub

AQUA MCP server

aqua-mcp-server 2.0.4 lets an AI agent (Claude Code, Claude Desktop, Cursor and others) work on your applications from your own computer. Your answers stay in your local, encrypted AQUA workspace. The agent can read, match and draft. You approve in the AQUA browser app.

Local-first by design

The server holds no account token and no privileged database key. Its only credential is the public catalog key that this website sends to every browser, and it refuses to start with any other key. Private work happens in a workspace on your machine, decrypted in memory only, with every agent call recorded in the workspace’s own audit log. Catalog requests carry only public program ids.

Three ways to connect

Local, with your workspace: 43 tools

22 read, 15 private_write, 5 human_only, 1 human_consent

npx -y aqua-mcp-server --workspace ~/AQUA

Your encrypted AQUA workspace with tiered tools: search your answer bank, import an application from inbox/, stage drafts, check review status, prepare an export. Plus the public catalog tools.

Local, no workspace yet: 14 tools

13 read, 1 human_consent

npx -y aqua-mcp-server

The public catalog tools, plus the setup tools (locate_workspace, init_workspace, doctor). init_workspace creates a workspace only after you confirm the folder in your MCP client.

Hosted, read-only: 11 tools

11 read

https://aquaidp.xyz/mcp

The public catalog only: approved programs, their exact questions, limits and deadlines. No sign-in, no workspace, nothing private. Rate-limited.

Install

Node.js 22 or newer. aqua-mcp-server 2.0.4 is on npm: npx -y aqua-mcp-server is the primary install, and it includes the companion. The same companion tool set is also served as a tarball from this site, as a fallback. Check its sha256 at the published checksum first.

# primary: aqua-mcp-server 2.0.4 from npm
npx -y aqua-mcp-server --help
claude mcp add aqua -- npx -y aqua-mcp-server --workspace <folder>/AQUA --keychain

# hosted, read-only public catalog (works now)
claude mcp add --transport http aqua-public https://aquaidp.xyz/mcp

# fallback: the AQUA companion tarball from aquaidp.xyz
npx --yes https://aquaidp.xyz/companion/aqua-companion-0.2.5.tgz --help
npx --yes https://aquaidp.xyz/companion/aqua-companion-0.2.5.tgz init --path <folder>
claude mcp add aqua -- npx --yes https://aquaidp.xyz/companion/aqua-companion-0.2.5.tgz mcp --workspace <folder>/AQUA --keychain

Client configuration

Claude Desktop, Cursor, or a project .mcp.json. The workspace passphrase comes from the macOS Keychain (--keychain) or the server’s environment, never from the chat. Add --read-only to allow reading only.

{
  "mcpServers": {
    "aqua": {
      "command": "npx",
      "args": ["-y", "aqua-mcp-server", "--workspace", "/Users/you/AQUA", "--keychain"]
    },
    "aqua-public": {
      "type": "http",
      "url": "https://aquaidp.xyz/mcp"
    }
  }
}

Tiers

Every tool declares a tier in code, and the server enforces it. Tool descriptions are not what keeps it in line.

  • read: Only reads your workspace or the public catalog.
  • private_write: Stages private records in your local workspace (drafts, imports, evidence). Refused with --read-only. Nothing it writes counts as approved.
  • human_consent: Acts only after you confirm in your MCP client (creating a workspace). Your passphrase never goes through the agent.
  • human_only: Never acts. Returns the steps you take in the AQUA browser app: approve an answer, sign, freeze and export a packet, submit, attest.

Where you approve

Approvals, signatures, freezing and exporting a packet, and submitting are yours, in the AQUA browser app. The agent stages drafts in your workspace. You export a backup, restore it at AQUA Local, and approve each answer on the review board, where an approval binds the exact version. Nothing an agent does counts as an approval.

Not available to agents

  • 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.

Upgrading from 1.x? Versions below 2.0 needed a privileged key and wrote private answers to a hosted store. They are retired. The migration table is in the package README.

More