Connecting an assistant (MCP)

Wateera ships an MCP server, so the assistant a person already uses can work on their day: read today's board, add tasks, run one of the agent patterns, close the day, read the week's numbers.

The model that answers belongs to the client. This server is a thin, typed client of the product's own API: it never touches the database, it holds no copy of any rule, and it cannot see a workspace other than the one its key belongs to.

1. Create a key

pnpm --filter @repo/scripts api-key -- --workspace <workspace-slug> --name "Claude Desktop"

The key is printed once — only its SHA-256 is stored, so it cannot be shown again. Manage keys with:

pnpm --filter @repo/scripts api-key -- --list   --workspace <slug>
pnpm --filter @repo/scripts api-key -- --revoke <keyId> --workspace <slug>

A key acts as the workspace owner who created it: every call is attributed to that person, and the API applies their membership and their plan exactly as it does in the browser.

2. Point the client at it

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
	"mcpServers": {
		"wateera": {
			"command": "pnpm",
			"args": ["--filter", "@repo/mcp", "start"],
			"cwd": "/absolute/path/to/the/repo",
			"env": {
				"WATEERA_API_KEY": "wk_...",
				"WATEERA_API_URL": "https://app.example.com"
			}
		}
	}
}

Cursor, Codex and any other MCP host take the same shape. Two optional variables:

• WATEERA_API_URL — defaults to http://localhost:3100.
• WATEERA_MCP_READ_ONLY=1 — registers the read tools only. Use it to hand an assistant your day without handing it the ability to change it.

3. The tools

Two behaviours the tool descriptions state, because an assistant should not have to guess: a pattern outside the plan is refused, and a spent model quota falls back to the local engine — the result always says which engine answered. No tool takes a workspace id; the key decides it.

4. How it is authorised (and what it cannot do)

• A key belongs to one workspace and is bound to the user who created it. A request that names another workspace is refused with FORBIDDEN, and the attempt is written to the audit trail.
• Revoking a key takes effect immediately: the lookup ignores revoked rows.
• The MCP server never opens the database, so a compromised client cannot read another tenant's data — it can only make the API calls its own key allows.
• Everything an assistant does appears in the workspace's activity log (automation.completed, item.deleted, period.closed) next to what people did in the browser.
• Read-only mode exists for the case where someone wants the assistant to look and not touch.

5. Verifying it yourself

WATEERA_API_KEY=wk_... WATEERA_MCP_READ_ONLY=1 pnpm --filter @repo/mcp start

One line goes to stderr naming the workspace, the acting user, the plan and the registered tools, then the process waits on stdio. Nothing is written to stdout except the protocol — a stray console.log there corrupts the stream and the client reports a parse error instead of the message you wanted.

Known gaps

• Keys are managed from the CLI. There is no settings screen for creating and revoking them yet.
• The server runs from the repository (pnpm --filter @repo/mcp start); publishing it as a standalone npm package, so a user needs no checkout, is not done.
• Tool results are JSON text. Assistants handle that well, but a summarised get_today would be kinder to small context windows.