Reference

This page lists everything the reference server exposes. The authoritative definitions are in the specification and its JSON Schemas, which win whenever prose and a schema disagree.

Command line

Install nothing: every command runs with npx @mentu/monitor-protocol <command>.

Command	What it does
serve	Serve the HTTP binding, JSON-RPC and server-sent events under /mp/v0
mcp	Serve the MCP extension ai.mentu/monitors over standard input and output
watch	Follow one subscription, one line per observation, for the Claude Code Monitor tool
publish	Publish one observation to a monitor on a running server
conform	Run the conformance suite against an implementation
tools	Print the MCP tool surface without starting anything

Flag	Used with	What it does
--port 8130, --host 127.0.0.1	serve	Where to listen
--state <file>	serve, mcp	Keep monitors and subscriptions in this file across restarts. A leading ~ means your home directory. Only one server may write a file at a time.
--registration-token <token>	serve	Require this token to create a monitor, and mark the monitors it creates as attested
--retire-after-mute <seconds>	serve	The default time a subscription may go without pulling before it is retired
--allow-admin[=token]	serve	Enable the admin endpoints, which always require the admin token
--allow-origin <origin,...>	serve	Browser origins allowed to call the server, such as https://dash.example. Every other web page is refused.
--allow-host <name,...>	serve	Extra host names to accept on loopback connections, for example behind a local proxy
--max-body <bytes>	serve	The largest request body read. The default is 1048576, one MiB.
--base <url>, --subscription <id>, --token <token>	watch	Which subscription to follow
--catch-up, --wait 25, --limit 50, --once	watch	Print the backlog first, the pull wait, the batch size, and stop after one batch
--self or --base <url>, --json	conform	Test this package or another server, with machine-readable output
--json	tools	Print the tool definitions as JSON

HTTP endpoints

All paths are under /mp/v0. Send JSON bodies, and send tokens as Authorization: Bearer <token>.

Method and path	What it does	Token
GET /discover	Protocol versions, capabilities, limits and server identity	none
GET /monitors	The monitors you can see	owner token for private ones
POST /monitors	Create a monitor. The reply carries the owner token once.	registration token, if the server requires one
GET /monitors/<id>	One monitor's definition	owner token if private
GET /monitors/<id>/state	The computed state	as the monitor's visibility allows
POST /monitors/<id>/observations	Publish one observation	owner token
POST /monitors/<id>/update	Change the definition, with a reason	owner token
POST /monitors/<id>/pause, /resume, /retire	Pause, resume or retire the monitor, with a reason	owner token
POST /subscriptions	Subscribe. The reply carries the subscription token once.	as the monitor's visibility allows
GET /subscriptions/<id>/pull	Observations after the cursor. Query: wait, limit, cursor for a read-only replay, and filter keys.	subscription token
GET /subscriptions/<id>/stream	The same, as server-sent events. Last-Event-ID resumes.	subscription token
POST /subscriptions/<id>/ack	Commit the cursor: {"cursor": n}	subscription token
POST /subscriptions/<id>/seek	Move the cursor on purpose: {"cursor": n, "reason": "..."}	subscription token
POST /subscriptions/<id>/renew	Rotate the subscription token	subscription token
POST /subscriptions/<id>/retire	End the subscription and keep its cursor	subscription token
POST /subscriptions/<id>/leases/claim	Claim a subject: {"subject": "...", "lease_duration_seconds": 900}	subscription token with act
POST /subscriptions/<id>/leases/renew, /complete, /release, /reject	Extend, finish with evidence, give back, or refuse the work	subscription token with act
POST /rpc	The same operations as JSON-RPC 2.0	as above

JSON-RPC methods

POST /mp/v0/rpc accepts these methods. Their parameters match the HTTP bodies above.

Group	Methods
Monitors	monitors/discover, monitors/list, monitors/get, monitors/create, monitors/update, monitors/pause, monitors/resume, monitors/retire, monitors/state, monitors/publish
Feeds	feeds/subscribe, feeds/pull, feeds/ack, feeds/seek, feeds/renew, feeds/retire
Leases	leases/claim, leases/renew, leases/complete, leases/release, leases/reject

MCP tools and resources

Tool	What it does
monitor_discover	Protocol version, capabilities, limits and server identity
monitor_list, monitor_get	The monitors you can see, and one definition
monitor_create, monitor_configure	Create a monitor, and update, pause, resume or retire it
monitor_publish	Publish one observation
monitor_state	The computed state
monitor_subscribe, monitor_pull, monitor_ack	Subscribe, read after the cursor, and commit
lease_claim, lease_complete, lease_release	Claim work, finish it with evidence, or give it back

Resources: monitor://<id>/definition and monitor://<id>/state for every visible monitor. When a monitor records something, the server sends a resource update notification for its state.

Error codes

Code	HTTP	JSON-RPC	When
INVALID_FILTER	400	-32000	A filter uses an unknown key or an invalid value
UNKNOWN_VOCABULARY	400	-32001	A tier, origin, verification or other closed value is not in its list
TIER_NOT_ASSERTABLE	400	-32002	A non-human origin asserts tier: src
INVALID	400	-32003	A request is malformed, such as a cursor that is not a whole number
UNAUTHORIZED	401	-32005	A token is missing or wrong
CAPABILITY_MISSING	403	-32004	The subscription was not granted what the call needs
PROVENANCE_CEILING	403	-32014	A claim needs a person behind it, or names someone the monitor does not act for
NOT_FOUND	404	-32006	No such monitor, subscription or action
DUPLICATE	409	-32007	A monitor with that id already exists
CURSOR_BACKWARDS	409	-32008	An acknowledgement below the stored cursor
LEASE_HELD	409	-32010	Someone else holds the lease. The reply names them.
LEASE_LOST	409	-32011	Your lease expired and someone else claimed the subject
EVIDENCE_REQUIRED	409	-32012	Reserved for completing work without the evidence it requires. Version 0.1 does not use it yet.
CURSOR_EXPIRED	410	-32009	The cursor is below the retention floor. Rebuild from the state.
OVER_BUDGET	429	-32013	Reserved. Version 0.1 does not enforce budgets yet.
ORIGIN_REFUSED	403	-32015	A web page on an origin the server does not allow, or a Host that does not name this machine
TOO_LARGE	413	-32016	A request body over the server's limit
UNAVAILABLE	409	-32017	A publish to a paused or retired monitor. The refusal is recorded.

Every error body has code and error, and often more fields that help you recover, such as known_keys, holder or retention_floor.

Vocabularies

Every closed value is checked when it is written. An unknown value is refused, never stored.

Field	Values
tier	src, measured, derived, unverified, falsified
origin	human, agent, webhook, probe, system
verified	human_verified, machine_verified, certified, reported, unverified
horizon	event, minute, hour, day, week, month
capabilities	observe, react, act
visibility	private, shared, public
source.kind	shell, ws, http, file, feed, cir, formula, log
reset_policy	earliest, latest, none
protocol	pull, http, mcp
gaps	independence_unknown, single_actor, stale_source, no_subscribers, no_event_provenance, unattested_origin

Observation types the protocol defines

Type	Written when
ai.mentu.monitor.configured	A monitor is created, updated, paused, resumed or retired
ai.mentu.monitor.subscribed	A subscription is created, or its cursor is moved with seek
ai.mentu.monitor.subscription_retired	A subscription is retired, by request or because it stopped pulling
ai.mentu.monitor.lease	A lease is claimed, renewed, completed, released, rejected or expires
ai.mentu.monitor.rejected	A write is refused. It keeps the reason and the raw input.
ai.mentu.monitor.contradiction, ai.mentu.monitor.contradiction_resolved	Published by a producer to record that two observations disagree, and when that is settled. The state counts the open ones as contradictions_open.
ai.mentu.monitor.state, ai.mentu.monitor.bookmark	Reserved for state snapshots and bookmarks