MCP tools reference¶

Exocortex exposes its capabilities to LLM clients through the Model Context Protocol (MCP). Run the server with:

exocortex serve            # stdio transport, default for Claude Desktop
exocortex serve --http     # HTTP/SSE, default for browser clients

Once connected, the client sees one tool per registered McpTool subclass. The table below is the built-in tool set. Plugins add their own — call tools/list from your client to see the full inventory of a running server.

Built-in tools¶

Source of truth: exocortex/mcp/tools/*.py. The "Class" column is the file/class you'd grep for if you want to read the implementation.

Knowledge tools¶

Tool name	Class	Purpose	LLM call?
`search_thoughts`	`SearchThoughts`	pgvector cosine top-K over `thoughts`	embed only
`expand_node`	`ExpandNode`	Apache AGE Cypher traversal, 1–2 hops, filterable by edge type	no
`synthesize`	`SynthesizeFetch`	Fetch the latest active row from `syntheses` for a `(perspective_type, perspective_key)` pair	no
`find_action_items`	`FindActionItems`	Parser over meeting markdown — open `[ ]` items, filterable by owner / client / due date	no
`find_contradictions`	`FindContradictions`	Unresolved `contradicts` edges in the graph	no
`ask`	`Ask`	Full GraphRAG: vector retrieval + graph traversal + LLM answer with inline citations	yes

FRP workflow tools¶

Drive the Futures Reading Protocol lifecycle from an MCP client. These read and write content_queue, frp_sessions, and thoughts; none call the LLM directly (the prompt LLM is the client itself).

Tool name	Class	Purpose
`query_content_queue`	`QueryContentQueue`	Score-sorted reading queue, joined with `raw_sources`
`create_frp_session`	`CreateFrpSession`	Open a new FRP session anchor — `(frame ∈ A/B/C, level ∈ 1/2/3)`
`append_session_thought`	`AppendSessionThought`	Add a step thought + auto `session_contains` edge (+ optional entity edges)
`complete_session`	`CompleteSession`	Record 1–5 resonance, schedule `revisit_due = now + 48h`, mark queue item used
`enqueue_generated_frp_story`	`EnqueueGeneratedFrpStory`	Persist a generated story as a curated `generated-frp` queue item — UPSERTs `raw_sources` + `content_queue` + scored `thoughts` row + `acquired_from` edge in one call. Idempotent on `SHA256(body)[:16]` URI
`add_revisit`	`AddRevisit`	Append a `frp_revisit` thought + emit a `revisits` edge, optional `materializes_as` edge

Promotion tools¶

Wikilink-aware bridges that move structured items between the graph and Markdown surfaces (vault TODO files).

Tool name	Class	Purpose
`promote_action_items`	`PromoteActionItems`	Promote selected action items into `wiki/work/TODO/*.md`
`unpromote`	`Unpromote`	Reverse a promotion — remove the wiki block, leave the graph row
`list_promoted`	`ListPromoted`	Show which action items are currently surfaced in TODO files

Live sections¶

Inject scheduled or event-driven Markdown blocks into wiki pages. See the F16-live-sections-design.md spec for the event model.

Tool name	Class	Purpose
`list_live_sections`	`ListLiveSections`	Inventory of registered `SectionGenerator` instances + their bindings
`trigger_live_section`	`TriggerLiveSection`	Force-render a section now, regardless of its schedule or event binding

Calling a tool¶

From an MCP client, the call is whatever your client wraps tools/call as. From the CLI:

exocortex query "ask" --args '{"question": "what shipped this quarter?"}'

--args is JSON matching the tool's input schema. The schema is served alongside the tool via tools/list.

Adding your own¶

Plugins register new tools through the McpTool extension point. See Writing a plugin → Register an MCP tool for the contract (.name, .schema, handler(args) -> result) and a worked example.

Verification¶

exocortex query --diag plugins

The mcp_tools bucket lists every registered tool name. Tools from plugins appear alongside the built-ins; last-write-wins per .name, so plugin tools can shadow built-ins if you want them to.