MCP setup

What this gives you

The server speaks the Model Context Protocol at /mcp (streamable HTTP). Connect an AI assistant — any MCP client — and it can read and work the family board. The tools cover lists and items (list_items, add_item, complete_item, assign_item), the calendar (list_events, add_event, update_event), the meal library and the weekly rota (list_meals, add_meal, get_week, set_rota_slot, override_day, add_ingredients_to_list), plus the family roster and rewards (list_family, list_rewards). Jobs carry their sub-tasks — get_item returns the steps and add_item accepts a parent_uid. Each member can pull their own data with export_my_data (self-scoped and size-capped). Larger exports go through the web app or the CLI.

1. Turn the endpoint on

The endpoint ships disabled. An admin turns it on under Admin → System, or from the CLI:

eagraiclainne system set --mcp-enabled

The setting takes effect immediately, no restart. While it is off, authenticated calls to /mcp get a 403 with a named reason. Anonymous or revoked callers get a 401 either way and never learn whether the endpoint is on.

2. Mint an API key

In the web app: Admin → Keys. Or from the CLI:

# A personal key — acts as one member
eagraiclainne apikey create --name sile-assistant --user <user-uid>

# A standalone key — for a shared device such as Home Assistant
eagraiclainne apikey create --name kitchen-tablet --roles member --act-as <uid>,<uid>

A personal key acts as its member. A standalone key names who actually acted per call via acting_user, honoured only against its admin-set allowlist. You can list and revoke keys at any time (eagraiclainne apikey list, eagraiclainne apikey revoke).

3. Add the server to your MCP client

Most MCP clients take an HTTP server entry like this:

{
  "mcpServers": {
    "eagraiclainne": {
      "type": "http",
      "url": "http://your-server:8080/mcp",
      "headers": { "Authorization": "Bearer <api-key-token>" }
    }
  }
}

4. Ask

Síle's evening check, from her own laptop:

> what's left on the family board this week?

Two open jobs: Tidy room (Fiadh), Bins out (Cormac, due
Thursday). Saturday has the football match at 11am.

The server authorises every call as the key's member — the same role rules as the app. Deletes and role management are deliberately not on the MCP surface.