CHAPTER 09MCP Interface

Req. prefix: MCv0.2 draft

HiLo.FM exposes a Model Context Protocol server so AI agents are first-class clients for forecast-modification management. The MCP layer is a thin adapter over the Ch. 08 API — same engine, same semantics — with tool descriptions written for an agent that has never seen this specification.

MC-01Tool coverage MUST equal API coverage (AP-01 transitively): anything a user can do to forecast modifications, batch and admin, an agent can do. The UI-only master-data browser (S5, D-23) has no MCP counterpart beyond get_master_data reference reads.

MC-02Tools are task-shaped, not endpoint-shaped, where that reduces round trips — but each tool maps to documented API operations with no additional logic.

9.1Tool catalogue

Tool	Maps to	Notes
`list_entries`	GET /entries	filters, pagination, state filter
`get_entry`	GET /entries/{id} (+ /lo optional)	flag `include_lo_sample` returns first N LO rows
`create_entry`	POST /entries	returns state + error_message + lo_row_count
`update_entry`	PUT /entries/{id}	partial update semantics documented in tool description
`delete_entry`	DELETE /entries/{id}	irreversible — description says so
`preview_disaggregation`	POST /entries/preview	dry-run; nothing persisted
`redisaggregate_entry`	POST /entries/{id}/disaggregate
`query_lo`	POST /lo/query	group-by + filters → aggregated cells; the reporting workhorse
`run_batch` / `get_batch_status`	POST /batch/run · GET /batch/current\|last	status merges live + last report
`get_master_data`	GET /masterdata/…	hierarchy/attributes, locations, customers, calendar — reference reads for scope construction (read-only, D-23)
`regenerate_forecast`	POST /admin/regenerate-forecast	DE-08; requires explicit `confirm:true`; sets all entries RequiresDisaggregation
`reset_demo`	POST /admin/reset	requires explicit `confirm:true` parameter
`get_system_status`	GET /admin/status	orientation call; cheap

9.2Design rules for the tool surface

MC-03Each tool description MUST state: what the tool does, units (SU, integers), the entry state model (an agent must understand InError is a data outcome, not a tool failure), and destructive-action warnings.

MC-04Tool errors follow AP-04: validation problems return the structured error; disaggregation failure returns a successful result whose payload shows state: "InError" with the message. Descriptions MUST make this distinction explicit.

MC-05Responses stay context-friendly: lists paginate with small defaults; query_lo returns aggregated cells, never raw base-grain dumps unless explicitly requested with a row cap.

MC-06Write tools return the post-state of the touched object in full, so an agent needs no follow-up read to confirm effect.

MC-07Authentication mirrors AP-02 (configured account credentials at server level); no per-tool auth logic.

9.3Reference agent flows (informative)

"Add a 12 000 SU campaign on brand B1 for Q4, all locations." → get_master_data (resolve B1, Q4) → preview_disaggregation → create_entry → report resulting state and weekly totals.
"Why is entry e-0087 in error?" → get_entry → relay error_message (names stage, rule, scope element per HE-08) → optionally propose fix and update_entry.
"Show modification volume by brand and month." → query_lo with group-by [brand, month] → tabulate. (Volume by customer: only entry-level — GL-03; the tool description of query_lo repeats this.)
"Refresh everything and tell me how fast it was." → regenerate_forecast (confirm) → run_batch → poll get_batch_status → summarise the DF-08 report.