Kosh API MCP

The Kosh API MCP lets an AI agent work with the plan of your Household. The agent acts as you: every change it makes shows your name and the source "mcp".

Endpoint: https://api.ourkosh.com/mcp (Streamable HTTP)
Auth: the header Authorization: Bearer kmcp_… on every request

Make a token

In the app, open Household, then MCP tokens.
Type a name for the token and pick how many days it stays valid (1 to 90).
Copy the secret. Kosh shows it only once and keeps only a hash of it.

You can revoke a token at any time. The Owner can revoke any token in the Household. When a Member is removed from the Household, all tokens of that Member stop working.

Connect an agent

Add a remote MCP server to your agent with the endpoint and the header above. A request without a valid token gets 401 and changes nothing.

Tools

Read tools:

Tool	What it returns
`list_plan_items`	Plan Items, optionally by state
`get_plan_item`	One Plan Item
`list_occurrences`	Occurrences in a date range, optionally by status
`get_today`	The Today screen: due and overdue Occurrences
`list_holdings`	Holdings with their latest Snapshot
`get_holding`	One Holding
`list_snapshots`	Snapshots of one Holding
`get_family_view`	The Family view totals
`list_warnings`	Hard rule warnings

Write tools:

Tool	What it changes
`create_plan_item`	Adds a Plan Item (`dryRun` shows warnings only)
`update_plan_item`	Edits a Plan Item (`dryRun` shows warnings only)
`set_plan_item_state`	Pauses, resumes, or stops a Plan Item
`mark_occurrence_done`	Marks an Occurrence done
`undo_occurrence_done`	Undoes a done mark
`create_holding`	Adds a Holding
`update_holding`	Edits a Holding
`put_snapshot`	Sets the value of a Holding on one date

Write tools return Hard rule warnings in the same way as the app. There are no tools for Imports, Members, invites, tokens, or Household settings, and no delete tool.