11 — MCP Integration Plan (AI & Terminal Logging Surface)

Purpose

Health Debug will fully support the Model Context Protocol (MCP) so that users can log protocol events and query engine state from any MCP-capable AI assistant (Claude Code, Claude Desktop, other agents) or directly from the terminal — without opening an app. This was added to the spec by Fady on 2026-09-01 and makes MCP a first-class client surface alongside the web dashboard, native apps, Chrome extension, and Electron desktop client.

The MCP server obeys the same architectural rule as every other client: it is a thin presentation/transport layer. It holds no protocol logic and no AI keys; every tool call translates to a request against the ToGO backend REST API, which remains the Single Source of Truth for all temporal and state logic.

Architecture

• Language / packaging: Go, in the same monorepo as the ToGO backend so API client types are shared (mirrors the existing brain-mcp.exe pattern from the ToGO ecosystem — the old cabrain MCP binary is the in-house reference implementation for a Go MCP server).
• Transports: stdio (for local AI clients and terminal use) first; streamable HTTP as a later option for remote/hosted use.
• Auth: a Health Debug personal access token minted via TOGO auth, supplied through env (e.g. HEALTHDEBUG_TOKEN) in the MCP client config — never an AI provider key. Tokens are separately revocable, same as the mobile/watch clients' tokens.
• Idempotency: logging tools send an Idempotency-Key header so an AI retry cannot double-log water or medication. The server-side 30-second hydration cooldown still applies and is the final guard.

Planned MCP tools (initial set)

Tool	Action	Backend call (sketch)
log_water	Log +250ml (unit fixed by the Hydration Engine; server enforces 5000ml cap + 30s cooldown)	POST hydration entry
log_caffeine	Log a caffeine drink by kind (categorical — kind only, never mg)	POST caffeine entry
log_meal	Log a food item; server returns its Trigger Family classification (Gout / IBS-GERD / Fatty Liver / Safe)	POST nutrition entry
log_medication	Log a medication within the 60-minute Medication Grace window	POST medication entry
check_trigger	Ask whether a named food/ingredient is Safe or Trigger-bearing (categorical answer only)	GET trigger lookup
today_status	Full computed day: all engine states, GERD window countdown, caffeine block, hydration progress	GET today state
pomodoro_status	Current work/break state of the Kinetic Pomodoro Engine (read-only — breaks are validated by wearable motion, never by an MCP call)	GET pomodoro state
list_notifications	Unread notification items	GET notifications

Deliberately excluded tools:

• No complete_break — a Pomodoro break registers only via wearable-detected movement; an AI must not be able to fake it.
• No cycle/fertility prediction tool beyond what the backend already exposes; the Cycle Engine's fail-safe rules apply unchanged.
• No AI-analysis passthrough that could produce diagnosis-like output. Any AI text generated about Health Debug data still goes through the server-side BYOK proxy with its "Consult your doctor" guardrails (Core Opinion 2).

Core Opinions applied

1. Categorical, not quantitative: tool inputs are kinds/identities (log_meal name, log_caffeine kind), never quantities beyond the fixed 250ml hydration unit. check_trigger answers Safe / Trigger-bearing only.
2. No medical certainty: the MCP server returns engine state verbatim from the backend; it adds no interpretation. Descriptions in tool schemas explicitly instruct client AIs that outputs are behavioral-tracking data, not medical advice.

Terminal use

The same binary doubles as a plain CLI (healthdebug log water, healthdebug status) so terminal users get 1-command logging without an MCP client — same API, same token. PENDING DESIGN: none of this surface depends on the visual design; it can be built any time after Phase 1's API exists.

Phasing

• Ships as Phase 1.5: immediately after the Phase 1 backend exposes the hydration/today endpoints, since it is the thinnest possible client and doubles as an API smoke-test harness.
• Tool list grows with the engines: each new engine endpoint added in later phases gets a matching MCP tool in the same change.

Open questions

• Distribution: single downloadable binary vs. published npm/go-install package for MCP client configs.
• Whether the hosted (streamable HTTP) transport should ship at all before B2B partners ask for it.
• Rate limits for AI-driven logging beyond the engines' own cooldowns.