MCP Tool Reference¶

Meridian exposes 61 tools over MCP.

They fall into two usage patterns:

Planner sessions (claude.ai, planning work) - start_session · pin_decision · update_decision · add_note · get_context_block · generate_handoff
Executor sessions (Claude Code, Cursor, automated workers) - start_session · log_task · request_hitl · get_session_brief · generate_handoff

Quick Reference - 5 tools you use 90% of the time¶

Tool	One-liner	Example call
`start_session`	Register session, get full project context	`start_session(project_id="abc-123", session_name="feature-x", human_id="alice")`
`log_task`	Record completed work to the shared task log	`log_task(session_id="sid", project_id="abc-123", description="Wired OAuth redirect")`
`checkpoint`	Snapshot progress: auto-capture + delta handoff + next /goal	`checkpoint(session_id="sid", project_id="abc-123")`
`pin_decision`	Add an architectural decision to the live constitution	`pin_decision(project_id="abc-123", title="Use psycopg3", body="asyncpg has DLL issues on Windows", category="TECHNICAL")`
`request_hitl`	Surface a blocking question to the human queue	`request_hitl(project_id="abc-123", question="Should we rate-limit per IP or per token?", urgency="blocking")`

Tip: Use checkpoint() instead of generate_handoff() when ending a session — it also runs auto_capture and returns the next /goal string.

Starting a session¶

`start_session`¶

Register a session and get the full project context (goal, sprint, recent tasks, decisions) in one call. Use this instead of register_session.

Parameter	Type	Required	Description
`project_id`	string	required
`session_name`	string	required
`human_id`	string	optional
`client`	string	optional
`role`	string	optional	Pass 'executor' to inject executor_config and credentials guidance.
`compact`	boolean	optional	Default true — slim orientation. Set false for the full goal/instructions payload.

Example:

start_session(project_id="abc-123", session_name="feature-x", human_id="alice", role="executor")

`get_session_brief`¶

Read-only: Call this FIRST for project summaries or to see what a session did — returns session, tasks, decisions, and recent commits in one call. Compact session orientation (<500 tokens): sprint focus, pending items, recent tasks, blocking failures, and open HITL requests. Ideal for worker/automation sessions that don't need the full context.

Parameter	Type	Required	Description
`project_id`	string	required
`role`	string	optional	Controls verbosity. 'worker'=sprint+tasks only, 'planner'=full context.

Example:

get_session_brief(project_id="abc-123")

Tasks¶

`log_task`¶

Log what this session did, is doing, or failed at. Call frequently — this is the primary signal in the timeline and handoffs.

Valid statuses: pending · in_progress · done · failed · backlog · future · backburner

Parameter	Type	Required	Description
`session_id`	string	required
`project_id`	string	required
`description`	string	required
`status`	string	optional
`kind`	string	optional	Entry taxonomy. shipped=work done, found=discovery, decided=arch choice, blocked=blocker.

Example:

log_task(session_id="session-uuid", project_id="abc-123", description="Fixed auth bug", status="done")

`get_tasks`¶

Read-only: Get recent tasks across all sessions.

Parameter	Type	Required	Description
`project_id`	string	required
`limit`	integer	optional

Example:

get_tasks(project_id="abc-123")

`search_tasks`¶

Read-only: Search tasks by keyword or natural-language query. Uses trigram similarity on Postgres, LIKE on SQLite. Returns top matches with similarity score.

Parameter	Type	Required
`project_id`	string	required
`query`	string	required
`limit`	integer	optional

Example:

search_tasks(project_id="abc-123", query="rate limiting bug")

Goal & sprint¶

`get_goal`¶

Read-only: Fine-grained — return just the goal fields (north_star, sprint, version_goal) in isolation. Use start_session or get_session_brief for full context including tasks and decisions. Use get_goal when you only need the raw goal fields.

Parameter	Type	Required	Description
`project_id`	string	required

Example:

get_goal(project_id="abc-123")

`set_goal`¶

Set or update the goal state.

Parameter	Type	Required	Description
`project_id`	string	required
`content`	string	required

Example:

set_goal(project_id="abc-123", content="Build a great product")

`get_sprint_progress`¶

Read-only: Sprint progress summary — counts by status, percent_complete, and the item list.

Poll this between tasks. After each complete_sprint_item, call get_sprint_progress(project_id, session_id) (pass session_id) before claiming the next item. The board_change field reports items a planner injected since this session started, so an executor picks them up at the item boundary without restarting — never idle-poll, only poll at task boundaries. The result is cached server-side for 10 seconds, so parallel sessions polling together share a single DB query.

Statuses include provisional_complete — work finished but not yet verified/deployed, a non-terminal state between in_progress and done that does not count toward percent_complete.

Parameter	Type	Required	Description
`project_id`	string	required
`session_id`	string	optional	Optional: include board_change (items added since this session started).
`version`	string	optional	Filter to a specific sprint version bucket.
`item_group`	string	optional	Filter to a specific item group.

Example:

get_sprint_progress(project_id="abc-123")

Executor config & file coordination¶

`set_executor_config`¶

Store project-level executor defaults so worker sessions start with repo path, env file, test command, deploy command, shell, branch, and the injected credentials rule.

Parameter	Type	Required	Description
`project_id`	string	required
`repo_path`	string	optional
`repo_paths`	array	optional	Known locations [{cwd, hostname}] — merged into existing repo_paths, not overwritten.
`env_file`	string	optional
`test_cmd`	string	optional
`test_min`	integer	optional
`deploy_cmd`	string	optional
`shell_type`	string	optional
`branch`	string	optional

Example:

set_executor_config(project_id="abc-123", repo_path="/repo", env_file="/repo/.env", test_cmd="pixi run test", test_min=619, deploy_cmd="git push", shell_type="powershell", branch="dev")

`claim_file`¶

Claim exclusive edit rights on a file path for this session. Locks auto-expire after 2 hours.

Parameter	Type	Required	Description
`session_id`	string	required
`file_path`	string	required
`symbol`	string	optional	Optional symbol to claim (class/function/method name, e.g. 'AuthRouter' or 'AuthRouter.login'). Requires `content`.
`content`	string	optional	Full source of the file, required when `symbol` is given so the server can resolve the symbol's line range.

Example:

claim_file(session_id="session-uuid", file_path="meridian/server.py")

`release_file`¶

Release a file lock held by this session when you're done editing.

Parameter	Type	Required	Description
`session_id`	string	required
`file_path`	string	required

Example:

release_file(session_id="session-uuid", file_path="meridian/server.py")

`idle_until_session_done`¶

Read-only: Wait on another session before touching a shared file. The tool polls every 30 seconds until the watched session is done.

Parameter	Type	Required	Description
`watching_session_id`	string	required

Example:

idle_until_session_done(watching_session_id="session-uuid")

Decisions¶

`pin_decision`¶

Record an authoritative decision that supersedes earlier statements. Pinned decisions appear in every session's context block.

Categories: STRATEGIC · COMPETITIVE · TECHNICAL · TACTICAL · BUSINESS · PRODUCT · ARCHITECTURAL

Parameter	Type	Required
`project_id`	string	required
`title`	string	required
`body`	string	required
`category`	string	optional

Example:

pin_decision(project_id="abc-123", title="Use psycopg3", body="asyncpg has DLL issues on Windows", category="TECHNICAL")

`update_decision`¶

Patch a pinned decision. Pass new_title + new_body to atomically supersede (creates a new row, marks old as superseded). Otherwise patches in place.

Parameter	Type	Required
`decision_id`	string	required
`new_title`	string	optional
`new_body`	string	optional
`title`	string	optional
`body`	string	optional
`category`	string	optional
`status`	string	optional

`get_pinned_decisions`¶

Read-only: List pinned decisions (active only by default, newest first).

Parameter	Type	Required	Description
`project_id`	string	required
`include_superseded`	boolean	optional

Example:

get_pinned_decisions(project_id="abc-123")

Human-in-the-loop (HITL)¶

`request_hitl`¶

Surface a question to the human queue. Response includes chat_prompt (question + options formatted for inline display) and, when urgency='blocking', a poll_instruction. Dual-channel: filed in the dashboard AND shown in Claude Code chat — first answer wins. For blocking: display chat_prompt to the user, then poll get_hitl_request(request_id) every 30 s. If the user answers in chat, call answer_hitl(request_id, answer). normal/high land in the dashboard without blocking the session.

Parameter	Type	Required	Description
`project_id`	string	required
`question`	string	required
`session_id`	string	optional
`context`	string	optional
`urgency`	string	optional
`kind`	string	optional	question (default, auto-answerable) or correction (non-blocking mid-run human correction).
`assigned_to`	string	optional
`options`	array	optional	Answer choices rendered as selectable buttons in the dashboard.
`recommended`	string	optional	The safe-default option — an option string or a 0-based index into options. Highlighted in the dashboard; Enter submits it; auto-answer prefers it.

Example:

request_hitl(project_id="abc-123", question="Should we add rate limiting here?", urgency="normal")

`get_hitl_request`¶

Read-only: Poll a HITL request for the human's answer. Returns the row including status (pending/answered/dismissed) and answer text.

Parameter	Type	Required	Description
`request_id`	string	required

Example:

get_hitl_request(request_id="hitl-uuid")

`answer_hitl`¶

Answer a pending HITL request programmatically. Marks it answered so the waiting session can resume. Use when the human answers in Claude Code chat rather than the dashboard.

Parameter	Type	Required	Description
`request_id`	string	required
`answer`	string	required
`answered_by`	string	optional	Optional human_id of the answerer.

`dismiss_hitl`¶

Dismiss a HITL request (won't-answer / no longer relevant).

Parameter	Type	Required	Description
`request_id`	string	required

Handoff & context¶

`generate_handoff`¶

Read-only: Generate a context handoff document. mode='full' writes the complete L0/L1/L2 handoff. mode='delta' returns a compact session summary with completed items, pending items, and the next /goal string.

Parameter	Type	Required	Description
`project_id`	string	required
`mode`	string	optional
`session_id`	string	optional	Optional session id for auto-delta on repeated calls in the same session.

Example:

generate_handoff(project_id="abc-123", mode="delta", session_id="session-uuid")

`get_context_block`¶

Read-only: Return a compact plain-text context block (north star, sprint, pending sprint items, recent tasks, recent decisions, active sessions). Use mode='full' to paste into a fresh Claude Code session; mode='chat' for a shorter paste into claude.ai.

Parameter	Type	Required	Description
`project_id`	string	required
`mode`	string	optional

Example:

get_context_block(project_id="abc-123", mode="chat")

Planning tools¶

`get_planning_brief`¶

Read-only: Return a compact planning context (sprint, north star, pending items, in-progress items, recent tasks, active sessions, recent decisions, pending HITLs). No session registration needed — designed for planning chat sessions that need to see project state without side effects.

Parameter	Type	Required	Description
`project_id`	string	required

Example:

get_planning_brief(project_id="abc-123")

`reconcile_sprint_drift`¶

Read-only: Cross-reference pending sprint items against recent git commits and return items that may already be done. confidence='high' means 3+ keywords overlap (safe to mark done via complete_sprint_item); confidence='medium' means 1–2 (verify first). Call during planning sessions to identify board drift.

Parameter	Type	Required	Description
`project_id`	string	required

Example:

reconcile_sprint_drift(project_id="abc-123")

Rate limits¶

The hosted MCP surface (Bearer-token requests) is metered per tenant per minute by plan:

Plan	Requests / minute
`free`	500
`standard`	2000
`pro`	unlimited

Over-limit requests receive 429 Too Many Requests with a Retry-After header. Dashboard (cookie) traffic, /health, and /static are never metered, and self-hosted instances are unmetered. Polling get_sprint_progress between tasks stays well within these limits — the 10 s server-side cache keeps parallel polling cheap.

Notes¶

`add_note`¶

Add a per-project wiki note. Use for setup instructions, gotchas, environment details, how-tos.

Parameter	Type	Required	Description
`project_id`	string	required
`title`	string	required
`body`	string	required
`tags`	string	optional
`kind`	string	optional
`priority`	string	optional	high-priority notes surface first in generate_handoff and planner context.
`category`	string	optional

Example:

add_note(project_id="abc-123", title="Deploy note", body="Reminder: update env vars before deploy", tags="ops,deploy")

`get_notes`¶

Read-only: List project notes (newest first). Filter by tag substring.

Parameter	Type	Required	Description
`project_id`	string	required
`tag`	string	optional
`query`	string	optional	Text search across note title and body (case-insensitive).

Example:

get_notes(project_id="abc-123")

`delete_note`¶

Hard-delete a project note by id.

Parameter	Type	Required	Description
`note_id`	string	required

Projects¶

`create_project`¶

Create a new Meridian project.

Parameter	Type	Required	Description
`name`	string	required

Example:

create_project(name="my-app")

Legacy¶

`register_session`¶

Deprecated

Use start_session instead — it registers the session and returns goal + context in one call.

Parameter	Type	Required
`project_id`	string	required
`session_name`	string	required
`human_id`	string	optional
`client`	string	optional

Example:

register_session(project_id="abc-123", session_name="feature-x", human_id="alice")

MCP Tool Reference¶

Quick Reference - 5 tools you use 90% of the time¶

Starting a session¶

start_session¶

get_session_brief¶

Tasks¶

log_task¶

get_tasks¶

search_tasks¶

Goal & sprint¶

get_goal¶

set_goal¶

get_sprint_progress¶

Executor config & file coordination¶

set_executor_config¶

claim_file¶

release_file¶

idle_until_session_done¶

Decisions¶

pin_decision¶

update_decision¶

get_pinned_decisions¶

Human-in-the-loop (HITL)¶

request_hitl¶

get_hitl_request¶

answer_hitl¶

dismiss_hitl¶

Handoff & context¶

generate_handoff¶

get_context_block¶

Planning tools¶

get_planning_brief¶

reconcile_sprint_drift¶

Rate limits¶

Notes¶

add_note¶

get_notes¶

delete_note¶

Projects¶

create_project¶

Legacy¶

register_session¶

`start_session`¶

`get_session_brief`¶

`log_task`¶

`get_tasks`¶

`search_tasks`¶

`get_goal`¶

`set_goal`¶

`get_sprint_progress`¶

`set_executor_config`¶

`claim_file`¶

`release_file`¶

`idle_until_session_done`¶

`pin_decision`¶

`update_decision`¶

`get_pinned_decisions`¶

`request_hitl`¶

`get_hitl_request`¶

`answer_hitl`¶

`dismiss_hitl`¶

`generate_handoff`¶

`get_context_block`¶

`get_planning_brief`¶

`reconcile_sprint_drift`¶

`add_note`¶

`get_notes`¶

`delete_note`¶

`create_project`¶

`register_session`¶