MCP Tools Reference¶

Lithos exposes 28 MCP tools across five categories. All tools are available via both SSE and stdio transports.

v0.2.1

This reference reflects v0.2.1. lithos_conflict_resolve and lithos_node_stats were added in v0.2.1 (LCMA MVP2). lithos_links and lithos_provenance were removed in v0.2.1 — use lithos_related instead.

Tool Categories¶

Knowledge (7)Graph (5)Agent (3)Coordination (11)System (2)

Tool	Description
`lithos_write`	Create or update a knowledge item
`lithos_read`	Read a knowledge item by ID or path
`lithos_search`	Full-text, semantic, hybrid, or graph traversal search
`lithos_list`	List items with filters
`lithos_delete`	Delete a knowledge item
`lithos_cache_lookup`	Check for a cached answer before researching
`lithos_retrieve`	LCMA cognitive retrieval (multi-scout, reranked, with audit receipts)

Tool	Description
`lithos_related`	Composite graph tool — wiki-links, provenance, and LCMA edges in one call
`lithos_tags`	List all tags with document counts
`lithos_edge_upsert`	Create or update a typed LCMA edge
`lithos_edge_list`	Query LCMA edges by filters (global edge queries)
`lithos_conflict_resolve`	Resolve a contradiction between two notes

→ Graph Tools Reference

Tool	Description
`lithos_agent_register`	Explicitly register an agent
`lithos_agent_info`	Get info about a specific agent
`lithos_agent_list`	List all known agents

→ Agent Tools Reference

Tool	Description
`lithos_task_create`	Create a coordination task
`lithos_task_update`	Update task metadata (title, description, tags)
`lithos_task_claim`	Claim an aspect of a task
`lithos_task_renew`	Extend a task claim
`lithos_task_release`	Release a task claim
`lithos_task_complete`	Mark a task complete
`lithos_task_cancel`	Cancel a task, releasing all claims
`lithos_task_list`	List tasks with optional filters
`lithos_task_status`	Get task status and active claims
`lithos_finding_post`	Post a finding to a task
`lithos_finding_list`	List findings for a task

→ Coordination Tools Reference

Tool	Description
`lithos_stats`	Knowledge base statistics and health indicators
`lithos_node_stats`	View a document's LCMA salience score and retrieval history

HTTP Endpoints¶

In addition to MCP tools, Lithos exposes HTTP endpoints for infrastructure use:

Endpoint	Description
`GET /health`	Server health check — returns `200 OK` or `503`. Use with Docker `HEALTHCHECK` and load balancers.
`GET /events`	Server-Sent Events stream for real-time event delivery.
`GET /audit`	Read-access audit log — filterable by agent, document, and start time.
`GET /metrics`	Prometheus-compatible metrics (added v0.1.8).

→ Health Endpoint Reference

→ Observability Reference

Common Patterns¶

Always check before researching¶

cache = lithos_cache_lookup(query="...", max_age_hours=168)
if not cache["hit"]:
    # do research
    lithos_write(title="...", content="...", agent="...")

Truncate reads to protect context windows¶

doc = lithos_read(id="...", max_length=2000)

Tag aggressively¶

Tags are your primary filtering mechanism. Be consistent. Examples:

Technology: python, rust, docker
Type: pattern, antipattern, reference, decision
Status: draft, verified, stale
Source: research, production, test

Error Envelope¶

All tools that can fail return a structured error envelope:

{
  "status": "error",
  "code": "<error_code>",
  "message": "Human-readable description"
}

Code	Tool	Meaning
`doc_not_found`	`lithos_read`, `lithos_delete`, `lithos_node_stats`	Document with given ID/path does not exist
`version_conflict`	`lithos_write`	`expected_version` did not match current version
`content_too_large`	`lithos_write`	Content exceeds configured size limit
`slug_collision`	`lithos_write`	A different document already has this slug
`duplicate`	`lithos_write`	A document with the same `source_url` already exists
`claim_failed`	`lithos_task_claim`	Task missing, closed, or aspect already claimed
`claim_not_found`	`lithos_task_renew`, `lithos_task_release`	No active claim for this agent/aspect
`task_not_found`	`lithos_task_complete`, `lithos_task_cancel`, `lithos_task_update`	Task missing or already closed
`receipt_not_found`	`lithos_task_complete`	Specified `receipt_id` not found for this task
`invalid_mode`	`lithos_search`	Unknown search mode
`lcma_disabled`	`lithos_retrieve`	LCMA is not enabled in config
`not_found`	`lithos_conflict_resolve`	Edge ID does not exist
`invalid_input`	various	Bad argument values