MCP tool catalogue¶

This page is the human-readable reference for the current public tool contract. The authoritative runtime schema is the schema returned by MCP tools/list; the generated snapshot is contracts/mcp-tools.json. This page and the generated snapshot must be updated in the same pull request when that schema changes.

Read-only tools¶

Tool	Purpose	Required scope
`server_identity`	Return resource, instance, environment, revision, and authenticated project	`memory:read`
`continuity_context`	Return bounded project memory, open tasks, and recent receipts	`memory:read`, `tasks:read`
`memory_get`	Read one memory entry	`memory:read`
`memory_search`	Search or list project memory	`memory:read`
`task_get`	Read one task and its receipts	`tasks:read`
`task_list`	List bounded project tasks	`tasks:read`
`runtime_bootstrap_get`	Read pinned runtime document references	`documents:read`
`git_document_get`	Read a bounded fragment from an allowlisted commit-pinned document	`documents:read`

Mutating tools¶

Tool	Purpose	Additional safety
`memory_add`	Append a note or decision	`write_context`; decisions require rationale
`task_create`	Create a todo task	`write_context`; supports idempotency
`task_update`	Update task state and optionally append a receipt	`write_context`; mandatory `expected_version`

`write_context`¶

Every mutating call includes:

{
  "resource": "https://mcp.heyaira.eu/mcp",
  "instance_id": "<selected connection profile>",
  "project_id": "<authenticated project UUID>"
}

The exact instance value must come from the client’s operator-selected connection profile. Do not copy an instance ID from an untrusted response into a mutation.

`task_update`¶

The minimum concurrency-safe shape is:

{
  "task_id": "<task UUID>",
  "expected_version": 3,
  "status": "in_progress",
  "write_context": {
    "resource": "https://mcp.heyaira.eu/mcp",
    "instance_id": "<selected instance>",
    "project_id": "<authenticated project UUID>"
  }
}

If the version is stale, the whole update is rejected. Re-read with task_get; do not retry the stale mutation blindly.

Current contract rule¶

The server schema is authoritative. If a client reports write_context_required, it has either omitted the current required field or has not rediscovered the current tool schema. Reconnect and rediscover before trying again.