MCP tool reference

Altretta exposes your vault to any MCP client through a small, local endpoint — so your AI can query your notes, follow the graph, and check provenance instead of guessing. This page lists all 43 tools on that endpoint, the 6 more on the code endpoint, what each one does, and — for every single one — whether it can change anything.

You don't call these by hand. Your AI client discovers and calls them for you once connected — connecting is one click. This reference is here so you understand what your model can reach, and can trust what it reports back.

How to read this

Tools are grouped by purpose: grounded retrieval, your notes and their tasks and cards, graph query, verifiability, consistency, the tools that change things, and the code tools on their own endpoint.
Every row carries an access marker — Read-only or Mutating — and the default access level is read-only. A connected client is refused every mutating tool until you explicitly grant read-and-write in the Trust panel. This is not a label applied by hand: the server classifies each tool in a table, an unclassified tool is denied rather than waved through, and a tool that ships without a classification fails the build instead of shipping unguarded.
A few tools depend on build features, noted in their row. dag brings the signed-history tools; sparql brings the SPARQL tool. A build without a feature does not expose its tools at all, rather than exposing one that errors when called.
Every retrieved passage carries a citation (source:lines) and a provenance anchor — so what the AI quotes can be traced back to your note and its signed history. An anchor is a pointer, not a proof: it names a signed action, and aingle_dag_action is what turns it into evidence.
Folder exclusions you set in the Trust panel are applied to these tools: an excluded folder never appears in grounded results, backlinks, the vault map, folder or tag listings, tasks, cards, source listings, graph queries or signed history.

Grounded retrieval

The core of grounded, cited answers: the AI pulls only the passages that bear on your question, each with a citation and a signed anchor.

Tool	Access	What it does
`aingle_ground`	Read-only	The workhorse. Returns cited passages for a question, a provenance anchor per passage, a groundedness verdict (how well the evidence supports an answer), and an instruction the model must follow when answering.
`aingle_note_context`	Read-only	The notes semantically related by meaning to a given note, not just those it links to — each with the matching passage as evidence.
`aingle_backlinks`	Read-only	For a note: its backlinks, its outgoing links, and unlinked mentions of it, each with the source's context line.
`aingle_path`	Read-only	The shortest verified connection between two notes, as a chain of typed hops — link or semantic — each with its score, so every step can be cited.
`aingle_vault_map`	Read-only	A Map & Manual–style map of the vault: hub entry points, topic clusters, orphan notes, and tag indices. The tool a client should call first to navigate accurately.
`aingle_sources`	Read-only	The ingested source files with their content hashes as recorded at ingest — the provenance registry. Takes no arguments.
`aingle_ping`	Read-only	Liveness check. Returns `pong` — useful when wiring up a client.

Your notes, tasks and cards

The vault as a reader uses it rather than as a graph: what is tagged, what is filed where, what is due, and what is up for review. Each item carries a provenance anchor where one exists.

Tool	Access	What it does
`aingle_list_tags`	Read-only	Every tag in the vault with the number of notes carrying it — from frontmatter `tags:` and from inline `#tag` alike.
`aingle_list_folders`	Read-only	Every folder in the vault, derived from the ingested paths. Folders you excluded are omitted rather than listed and then refused.
`aingle_tasks`	Read-only	Every task extracted from your notes, open and closed, optionally filtered by status. Each carries its text, priority, scheduled and deadline dates, and its effective due date.
`aingle_agenda`	Read-only	The open, dated tasks bucketed against a reference day into overdue, today and upcoming within a horizon. The tool behind "what's due?".
`aingle_cards`	Read-only	Every spaced-repetition card in the vault, with its front text, whether it is a cloze card, and its scheduling state.
`aingle_due_cards`	Read-only	Cards bucketed for a review session against a reference day: due, new (never scheduled) and scheduled.

Graph query

Query the underlying semantic graph directly — subjects, predicates, triples, patterns.

Tool	Access	What it does
`aingle_query_pattern`	Read-only	Query the graph by triple pattern. Any field you omit is a wildcard.
`aingle_sparql`	Read-only	Run a SPARQL query (`SELECT` / `CONSTRUCT` / `ASK`) over the graph, for precise structured retrieval. Requires the `sparql` feature.
`aingle_list_subjects`	Read-only	The unique subjects (entities) in the graph, optionally filtered by predicate.
`aingle_list_predicates`	Read-only	The unique predicates (relationship types), optionally filtered by subject.
`aingle_list_triples`	Read-only	Triples with optional subject and predicate filters, paginated.
`aingle_get_triple`	Read-only	Fetch a single triple by its hash id.
`aingle_graph_stats`	Read-only	Summary statistics about the graph — counts and shape.

Verifiability & the signed history

Inspect Altretta's signed action history and its cryptographic proofs — this is what makes answers checkable rather than merely plausible. The five history tools are only present in a build with the dag feature; the two proof tools are always there.

Tool	Access	What it does
`aingle_dag_history`	Read-only	The provenance history of a subject, newest first, each entry with its hash and signature status. The signed payload is left out to keep the list small — fetch an entry to verify it. Requires `dag`.
`aingle_dag_action`	Read-only	The verifiable lookup. Fetches one action by hash and returns the signature, the public key, and the exact values that were signed, plus a step-by-step procedure for checking it without trusting this server. This is what turns a provenance anchor into evidence. Requires `dag`.
`aingle_dag_chain`	Read-only	One author's chain of actions, newest first. Requires `dag`.
`aingle_dag_tips`	Read-only	The current tips — the frontier of the history — and their count. Requires `dag`.
`aingle_dag_stats`	Read-only	Action count, tip count, and this node's signing public key. Pin that key on first use and compare it every time: a signature only attests to the holder of that key. Requires `dag`.
`aingle_get_proof`	Read-only	Fetch a stored cryptographic proof by id, with everything needed to replay the check yourself. Its stored `verified` flag is a cached verdict from a past call, not a check performed now.
`aingle_verify_proof`	Read-only	Ask the node to check a stored proof, and get back the material to check it yourself — including whether the proof is bound to a statement at all. An invalid proof returns `valid: false` rather than an error.

The proof and validation tools return the node's assertion, and they say so in their own output rather than leaving you to infer it. A proof that is not statement-bound verifies beside any claim whatsoever, so a passing check means "someone produced a valid proof of that shape", not "this proof backs the sentence it was served with". Each tool publishes the replay procedure precisely so an assistant can run it instead of relaying a boolean.

Consistency

Check whether the vault agrees with itself, and whether an agent's assertions hold up — surfacing contradictions before they mislead the AI.

Tool	Access	What it does
`aingle_validate`	Read-only	Run triples through the node's proof-of-logic rule engine. Reports `valid`, `invalid` or `not_evaluated` — the last meaning no rule examined them, which is not the same as passing.
`aingle_validate_skill`	Read-only	Check a semantic skill manifest against the same rule set.
`aingle_verify_assertions_batch`	Read-only	Check many assertions by subject and predicate at once, separating "a rule rejected it" from "this node does not hold it", which a bare `false` would blur.
`aingle_agent_consistency`	Read-only	An agent's assertion consistency score: the fraction of its assertions that pass validation. Null — not zero — when nothing was evaluated.

Tools that change things

Every tool in this section is refused under the default read-only access level. They become callable only if you switch a client to read-and-write in the Trust panel.

Tool	Access	What it does
`aingle_propose_note`	Mutating	Stage a proposed note into the vault's inbox for human review. It is written with a pending status and is not indexed and not signed until you approve it. This is the tool the Web Clipper and well-behaved agents use instead of writing directly — see the review inbox.
`aingle_edit_note`	Mutating	Append to, prepend to, or replace text in a vault note, and sign the change into the history. A dry run previews the content-hash change and the triple diff without writing.
`aingle_tag_add`	Mutating	Add a tag to a note — the frontmatter list where one exists, inline otherwise — and sign the change. Idempotent, and previewable with a dry run.
`aingle_tag_remove`	Mutating	Remove a tag from a note and sign the change. Idempotent, and previewable with a dry run.
`aingle_create_folder`	Mutating	Create a folder, and any missing parents, inside the vault. A path escaping the vault or landing in an excluded folder is refused.
`aingle_ingest`	Mutating	Ingest a notes vault or a codebase: extract triples, index text for semantic recall, and record signed provenance. Incremental — unchanged files are skipped.
`aingle_create_triple`	Mutating	Add one fact to the semantic graph.
`aingle_batch_insert`	Mutating	Add many facts atomically. Duplicates are skipped silently.
`aingle_delete_triple`	Mutating	Removes a triple from the graph by its hash id.
`aingle_dag_prune`	Mutating	Destructive. Drop actions from the signed history under a retention policy, and report how many went. Requires `dag`.
`aingle_sandbox_create`	Mutating	Create a temporary namespace for skill testing.
`aingle_sandbox_delete`	Mutating	Delete a sandbox, removing every triple under it.

Two of those genuinely destroy data: aingle_delete_triple removes a fact outright, and aingle_dag_prune drops history. The "nothing is ever deleted" principle describes how ordinary editing works — a superseded note is retracted with a signed action rather than erased — but it is not an absolute property of the system, and these tools are the exception. They are one more reason to leave a connected client read-only unless you have a specific reason not to.

The note-writing tools sign what they change, which is a different guarantee from the inbox. A signature makes an edit attributable and tamper-evident; it does not make it reviewed. Only aingle_propose_note puts a human decision in front of the write. If you grant read-and-write, aingle_edit_note and the tag tools take effect the moment they are called.

Code tools

If you've ingested a codebase, a second endpoint at http://127.0.0.1:19191/mcp-code exposes six more tools alongside the first. Point your client at it as well if you want code questions answered.

All six are read-only — and they are classified in a table of their own for the same reason as the rest: a tool that is not classified is denied, so the first code tool that ever writes anything is refused under a read-only policy even if whoever adds it never thinks about policy.

Tool	Access	What it does
`code_find_symbol`	Read-only	Find symbols by name and return their ids, so you can hand one to the tools below.
`code_impact`	Read-only	The impact radius of a symbol: what calls it directly and transitively, which decisions document it, and its signed history.
`code_history`	Read-only	A symbol's signed story over time — defined, changed, started using other symbols, removed — each step backed by a signed receipt, plus the decisions that govern it.
`code_map`	Read-only	Export a source's code graph as a verifiable map: every symbol, every edge, a content digest that recomputes from the returned data, and the anchor to the signed history.
`code_ask`	Read-only	Ask a question about the project and get an answer with receipts: cited note decisions and code symbols with their spans.
`drift_check`	Read-only	Find documentation drift: notes referencing code that no longer exists, or documenting a symbol whose code changed after the note was written.

Reference overview

The section this page belongs to.

Connect your AI

One-click setup for Claude Desktop, Claude Code, Cursor, VS Code and Windsurf.

Grounded, cited answers

What aingle_ground powers.

What your AI sees

The transparency view over exactly this context, and where the read-only switch lives.

Review inbox

Where aingle_propose_note puts a note, and how you approve it.

Semantic graph

The triple store the graph-query tools run against.

Signed history

What the history tools read, and what a signature does and does not prove.

Glossary

Definitions for MCP, provenance anchor, groundedness, and more.