MCP reference
What netherite mcp (stdio) and /mcp on a running netherite serve (streamable HTTP) offer an agent. Every write returns the new hash; pass it back as baseHash and the write fails if the file changed in between.
Tools
search
Full-text search over IDs, titles, aliases, paths and text. Returns matching items, best first.
| Name | Type | Required | Description |
|---|---|---|---|
query | string | yes | |
types | goal | project | task | adr | doc | context | runbook[] | Only these item types. | |
status | string | Only items with this status (goals, projects, ADRs) or state (tasks). | |
project | string | Only items that belong to this project. | |
tag | string | Only items with this tag or label. | |
limit | integer |
get
One item in full: its fields, text, links in both directions, progress, freshness and content hash.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Item ID, such as TASK-00042. |
as_of | string | A date (2026-03-01): show the state as it stood then, rebuilt from git history. Needs git. |
list
Items matching filters, in ID order. Use it to browse; use search to find by text.
| Name | Type | Required | Description |
|---|---|---|---|
type | goal | project | task | adr | doc | context | runbook | ||
status | string | Only items with this status (goals, projects, ADRs) or state (tasks). | |
project | string | Only items that belong to this project. | |
tag | string | Only items with this tag or label. | |
limit | integer | ||
offset | integer | ||
as_of | string | A date (2026-03-01): show the state as it stood then, rebuilt from git history. Needs git. |
create
Create an item with the next free ID, or with the id you give for an import: it must be a free ID of the type. Give its type, title and fields; the file name, dates and folder are handled for you.
| Name | Type | Required | Description |
|---|---|---|---|
type | goal | project | task | adr | doc | context | runbook | yes | |
title | string | yes | |
id | string | An explicit free ID of the type, for imports. Omit it for the next free ID. | |
fields | object | Fields for the type (see the schema resource for each type). | |
body | string | Text after the title heading, as Markdown. [[ID]] links to other items. | |
created_by | string | A @handle. Defaults to the person running the server. |
update
Change fields and/or one section of an item. Only the lines you change are touched. Use set_state for states and link for relationships.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Item ID. |
set | object | Fields to set. id and type cannot be changed. | |
unset | string[] | Fields to remove. | |
section | object | ||
base_hash | string | The hash from an earlier result. The write fails if the file changed since. |
set_state
Set a task's state, an ADR's status, or whether a doc, runbook or context item is active, deprecated or superseded. Making an item superseded needs superseded_by and updates both items. A retired item is left out of freshness and of agent context.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Task, ADR, doc, runbook or context ID. |
state | string | yes | Task states: backlog, doing, blocked, done. ADR statuses: proposed, accepted, deprecated, superseded. Doc, runbook and context statuses: active, deprecated, superseded. |
superseded_by | string | The item that replaces this one, of the same kind. Required when state is superseded. | |
base_hash | string | The hash from an earlier result. The write fails if the file changed since. |
toggle_check
Tick or untick checklist items in an item's text: one item, a list of items, or all, in one write. The edit is all or nothing: an item that does not exist changes none. The result lists each item as it is now.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Item ID. |
item | any | One checklist item: its 0-based position, or its exact text. | |
items | any[] | Several checklist items, each a position or its exact text. | |
all | boolean | Every checklist item. Ticks them unless checked is false. | |
checked | boolean | Set to this state. Omit to flip each one (with all, omit to tick). | |
base_hash | string | The hash from an earlier result. The write fails if the file changed since. |
link
Add a typed relationship from one item to another by ID. supersedes updates both ADRs.
| Name | Type | Required | Description |
|---|---|---|---|
from | string | yes | The item that holds the relationship. |
to | string | yes | The item it points at. |
kind | belongs_to | implements | explains | supersedes | depends_on | related | yes | |
base_hash | string | The hash from an earlier result. The write fails if the file changed since. |
unlink
Remove a typed relationship. Required ones, such as a task's project, cannot be removed.
| Name | Type | Required | Description |
|---|---|---|---|
from | string | yes | The item that holds the relationship. |
to | string | yes | The item it points at. |
kind | belongs_to | implements | explains | supersedes | depends_on | related | yes | |
base_hash | string | The hash from an earlier result. The write fails if the file changed since. |
delete
Delete an item. Refused while other items link to it, unless force is true.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Item ID. |
force | boolean | ||
base_hash | string | The hash from an earlier result. The write fails if the file changed since. |
mark_reviewed
Record that a doc, runbook or context item was reviewed, by setting reviewed_at. Defaults to today.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Doc, runbook or context ID. |
date | string | ||
base_hash | string | The hash from an earlier result. The write fails if the file changed since. |
lint
Check one item, or the whole workspace, for schema errors, broken links, duplicate IDs, stale docs and more. Each problem has a position, rule and severity.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Only report on this item. Omit for the whole workspace. |
context
The curated context for agents: context items marked for inclusion, highest priority first, within the token budget.
| Name | Type | Required | Description |
|---|---|---|---|
project | string | Only context for this project (and context not tied to one). |
Resources
| URI | What |
|---|---|
netherite://context | Curated context for agents, within the token budget. |
netherite://timeline | Goals, projects, tasks and decisions on one time axis, with holds, due dates and overdue flags. Needs git. |
netherite://stats | Tasks created and done, cycle time, goal areas and knowledge health over 30 days, against the 30 before. Needs git. |
netherite://item/{id} | The raw Markdown file of an item, by ID. |
netherite://stats/{period} | The same for a period: 30d, quarter or year. Needs git. |
netherite://schema/{type} | JSON Schema for an item type. |
The schema of each item type is read at netherite://schema/<type> (goal, project, task, adr, doc, context, runbook); see the schema reference.