MCP Tools

Quipu exposes its API as MCP (Model Context Protocol) tools for agent integration. These tools are available when Quipu runs as a Bobbin subsystem or standalone MCP server.

The registry (tool_definitions()) exposes 46 tools in a default build, or 48 when built with the owl feature (which adds quipu_load_ontology and quipu_explain). (The counts are pinned by tests in src/mcp/tests.rs, which also check this page and the README against the manifest.)

Connect directly

The server includes the native mcp feature. Build the CLI and its companion:

cargo build --release --features full --bin quipu --bin quipu-server
claude mcp add quipu -- /absolute/path/to/target/release/quipu mcp --db /absolute/path/to/store.db

quipu mcp starts the sibling quipu-server --mcp-stdio with the same configuration and store initialization as HTTP mode. It opens no network listener. On Unix it replaces the CLI process, so signals and EOF reach the server directly. Install both binaries together. Protocol output uses stdout; diagnostics use stderr.

For an already running server, register its /mcp URL as streamable HTTP. Calls are stateless: a server restart does not leave stale MCP sessions. The HTTP caller supplies the same service-specific bearer used for REST writes. For stdio with protected writes, pass --mcp-token-file /absolute/path/to/private-token; the file must be regular, at most 4096 bytes, and private (0600 or 0400 on Unix). Credentials are never accepted in tool arguments or forwarded from a claimed actor field. Unconfigured local stores retain the CLI’s existing local authority; configuring write authentication applies to stdio too. Read-only mode refuses writes even with a valid credential. No existing shared credential or open REST read changes.

Every tool dispatches through the existing REST application in process, sharing its authentication, dataset selection, read pools, validation, and committed transaction attribution. The schemas come from tool_definitions(); the native transport does not maintain a second schema catalogue. quipu_graph_list preserves its query filters. Tool failures are MCP error results with the REST error body. Natural-language quipu_search still requires the configured embedding provider; a precomputed embedding works without one. The transport does not download models.

Browser MCP requests require an Origin explicitly present in quipu.server.cors_allowed_origins; no Origin is normal for native agent clients. The REST origin policy remains unchanged. Tool requests are limited to 64 MiB.

Bobbin’s knowledge_* tools and existing Homelab quipu_* proxies remain supported compatibility surfaces. Native MCP lets an installation use Quipu without either proxy. The Homelab proxy continues to call REST; Bobbin keeps its existing library integration. Register the intended server explicitly to avoid ambiguous names; this addition does not remove an existing MCP entry or its credentials.

Run just mcp test for HTTP and stdio protocol acceptance against isolated stores, including concurrent named/shared credentials and read-only refusal. Set QUIPU_MCP_TEST_MODEL_DIR to a model directory containing onnx/model.onnx and tokenizer.json, plus ORT_DYLIB_PATH as needed, to test natural-language search with a real local embedding provider. Otherwise the test checks vector search and the explicit missing-provider error separately.

Tool Reference

quipu_query

Execute a SPARQL SELECT query.

Query results use prefixes declared by the loaded shape sets for compact CURIE values by default. IRIs in unknown namespaces remain full IRIs.

quipu_export

Export deterministic RDF from ROOT, a named graph, an episode provenance group, or a SPARQL graph query. Scope parameters are mutually exclusive.

quipu_align_propose

READ. Proposes candidate cross-graph alignments between two named graphs as a scored SSSOM mapping set, and returns the expected_version that quipu_align_apply requires.

Refuses an unknown graph IRI rather than returning zero candidates: align::enumerate returns an empty enumeration for an IRI it cannot look up, so a typo would otherwise come back as 0 candidates — indistinguishable from two graphs that genuinely share nothing.

quipu_align_decide

READ. Applies operator accept / negate verdicts to a proposed mapping set. Touches no store. Returns the decided set and the expected_version to carry into quipu_align_apply.

quipu_align_apply

WRITE. Materialises decided alignments as owl:sameAs / quipu:distinctFrom in an alignment graph derived from the two source graphs, creating that graph if needed.

expected_version is required and must be carried from the decision being applied. It is not computed here: set_version hashes the mapping set itself, so deriving the version at apply time would hash the set about to be written, always match, and silently discard a concurrent operator’s decision.

These are three separate tools rather than one with a mode because an MCP client judges a tool by its annotation. A moded tool would carry a single, necessarily destructive annotation, and every read-only call — including propose, the entry point — would be refused under a no-approval policy.

quipu_knot

Assert facts from Turtle data, with optional SHACL validation.

Returns: transaction ID, fact count, the normalised valid_from actually stored, and whether validation passed.

timestamp and valid_from are the store’s two time axes and they answer different questions — valid_from is queried with valid_at, timestamp with tx/as_of_tx. A commit authored in March and ingested tonight wants valid_from in March and timestamp tonight; passing only timestamp collapses both, which is what this surface did before aegis-sb8of5.

Valid-time is compared as text, so valid_from is normalised to YYYY-MM-DDTHH:MM:SSZ: a UTC offset is applied (git’s %aI emits the author’s local offset, and 2026-09-07T00:30:00+01:00 would otherwise sort after 2026-09-06T23:45:00Z, though it is earlier) and sub-second precision is dropped (.5Z sorts before Z). A malformed value is refused before the vocabulary gate, the SHACL pass, or any transaction — nothing is written.

replace_snapshot retractions are not back-dated: a replaced fact’s valid_to is the transaction stamp, because “these stopped being true in March” is a different claim from “we replaced them tonight”.

When replacement deletes an entity, a reference from another producer preserves its label, but not its stale type membership. Code snapshot keys code:<repo>:<partition> share a producer boundary with code:<repo> and all partitions of that repository. Their sibling references do not preserve a deleted label: a promote replaces keys in separate transactions, so sibling references can still be stale. References from another repository or producer still preserve the label. Other snapshot keys retain exact-key ownership semantics.

quipu_cord

List entities with optional filtering.

quipu_unravel

Time-travel query: view facts at a past state.

At least one of tx or valid_at must be provided.

quipu_validate

Dry-run SHACL validation without writing.

Returns: conforms boolean, plus arrays of violations, warnings, and informational issues.

quipu_shapes

Manage persistent SHACL shapes that auto-validate writes.

quipu_retract

Retract facts for an entity.

quipu_set

Atomically set (entity, predicate) to exactly one value: retracts every current object on that predicate and asserts the new one in a single transaction — the supersede primitive. Single-value semantics: to add without removing, assert via quipu_knot.

quipu_retract_episode

Episode-scoped logical retraction (POST /episode/retract). Retracts the facts an episode’s ingest contributed (activity node, entities, edges, reified statements) by closing valid_to — logical, not physical, so time-travel history is preserved. Entities and other episodes’ facts (even about shared IRIs) are untouched. Idempotent.

By default (on_orphan: "preserve") it does not retract every currently-active fact: it keeps rdfs:label / rdf:type alive for nodes that other episodes still reference, so scope retraction cannot leave a node visible to predicate queries but invisible to label/type scans.

Response: tx_id, retracted, episode, statements, plus identity accounting — on_orphan, identity_preserved (+identity_preserved_statements), and identity_orphans (+identity_orphan_entities).

Retraction is a more sensitive write than assertion. The endpoint honours read-only mode and bearer auth today; when per-principal scopes (hq-azs) and crew identity (hq-otm) land it should require an authorized principal.

quipu_retract_source

Retract-only repair of facts owned by a legacy transaction source (POST /retract/source).

Retraction in the store is source-scoped: it closes every currently-live fact whose transaction source equals a given string. quipu_knot composes its own tag as snapshot:<key>, so a producer can only ever clear what it wrote under that scheme — facts written under any other source string (a free-form producer string, a hand-run CLI promote) were unreachable by any retraction, permanently. This tool names the source explicitly and clears it.

It is deliberately not a raw source-tag input on quipu_knot. There, one tag stamps a transaction that carries both retractions and new assertions, so a raw tag would let any caller write facts attributed to any producer. Here there is no turtle parameter at all, so the transaction cannot carry an assertion and impersonation is impossible by construction rather than by discipline.

Response: source, graph, planned, entities, applied, tx_id, retracted, repair_source, sample (+ sample_truncated), and — on an applied call — remaining, a fresh read of the post-state rather than an echo of the request.

Two properties worth knowing before using it:

• planned: 0 is a real answer. It means the named source owns no live facts. quipu_knot reports replaced: true, count: 0 both for a retraction that removed nothing and for one that emptied a graph, so this question previously had no answer.
• Re-keying order is retract FIRST, then re-promote. The store dedups an identical triple to one row carrying one source, and the existence check ignores the transaction source — so asserting canonically first is skipped as a duplicate, every row keeps its legacy source, and the retraction then removes everything.

quipu_episode

Ingest structured agent knowledge as an episode.

quipu_search

Semantic vector search over entity embeddings. Supply either a natural-language query (auto-embedded when an EmbeddingProvider is attached) or a pre-computed embedding vector. At least one is required.

Requires an embedding provider when called with query and no embedding; without one it errors naming the missing [quipu.embedding] configuration. The response carries an embeddings block (configured, embedded_entities) so zero results are distinguishable from an unembedded store — see Embeddings and Semantic Search. | group_ids | No | Best-effort filter to entities from these provenance groups (episode-scoped label, not an isolation boundary; /knot facts are ungrouped and dropped from a group scope) | | entity_type | No | Restrict to entities of this rdf:type IRI |

quipu_hybrid_search

Combined SPARQL filtering + vector ranking. Supply either a natural-language query (auto-embedded) or a pre-computed embedding; the sparql pre-filter is optional.

Requires an embedding provider when called with query and no embedding; without one it errors naming the missing [quipu.embedding] configuration. The response carries an embeddings block (configured, embedded_entities) so zero results are distinguishable from an unembedded store — see Embeddings and Semantic Search.

quipu_graph

Project the knowledge graph into a render-ready node-link payload in one response: nodes (IRI, label, type, degree), index-addressed edges, and a type census. Episode/provenance scaffolding is excluded by default; nodes are ranked by degree and capped, and the response states what was dropped.

quipu_project

Graph projection and algorithms.

The louvain algorithm runs deterministic modularity-based community detection and returns { communities: [{ community, entities, size }], modularity }. Read-only unless persist: true.

quipu_context

Unified knowledge context pipeline.

The summary includes an embeddings block (configured, embedded_entities) reporting whether semantic retrieval was possible.

quipu_report

Live graph report — graphify’s GRAPH_REPORT.md equivalent, but queryable. Read-only.

Returns three sections:

• hubs — “god-nodes”: the most central entities by PageRank, each with its in_degree as a secondary signal.
• surprising_connections — low-prior edges that bridge two otherwise-separate Louvain communities. Rarer bridges (fewer edges crossing between the same two communities — bridge_rarity) rank first; ties break toward bridges touching higher-PageRank endpoints.
• suggested_questions — deterministic, template-generated prompts seeded by the hubs and bridges above.

Plus a graph summary (nodes, edges, communities, modularity). Communities here are emergent clustering for surfacing, not an access boundary.

quipu_policy_check

Committed-tier evaluation of a governance Policy over the graph of record. Evaluates the policy’s aegis:claim (a SPARQL ASK, optionally with a $target placeholder) and returns a Verdict — outcome ∈ satisfied | unsatisfied | unknown bound to a reproducible evidence_hash. Deterministic: any verifier re-running the same ASK over the same committed evidence gets the same verdict (checked, not trusted). The verdict is returned unsigned unless the store has a signing identity attached.

quipu_verdict_verify

Verify a signed Verdict against the Phase-0 root of trust: the signature must be valid under the verifier’s registered public key, and the verifier must be authorized to attest the predicate. trusted is the conjunction — the property a consumer should gate on.

quipu_verifier_authorized

Check the Phase-0 verifier registry: may this verifier attest this predicate? The discovery half of the governance gate.

quipu_cooccurrence

Deterministic, auditable work-item co-occurrence: given a work-item (Bead) IRI, returns the other work-items that share at least one touched code entity via the provenance chain Bead ←implements− GitCommit −modifies→ entity. A graph query over typed provenance edges, ordered by overlap strength.

quipu_overlay_create

Register an overlay-class named graph bound (bind-once) to a committed parent branch. Overlays are scratch layers over the committed graph: write hypotheses into an overlay, read the composed view, and the committed layer stays untouched.

quipu_overlay_write

Write one overlay primitive: assert, retract, or tombstone a triple in an overlay graph. Tombstone masks the parent branch’s fact in the composed view without touching the committed layer.

quipu_overlay_compose

Resolve an overlay’s composed view over [overlay > parent-branch-root]. Read-only. Two precedence modes: nearest (default, the scratch-layer read — asserted-and-not-tombstoned, nearest wins) and governed (the quarantine-plane read — the parent’s facts always win: an overlay value on a same-subject-same-predicate slot the parent claims is suppressed, and an overlay tombstone cannot mask a parent fact; it only masks the overlay’s own contributions).

quipu_search_nodes

Search for entities by natural-language query (text matching on names, labels, and values). Replaces Graphiti’s search_nodes.

quipu_search_facts

Search for relationships/edges by natural-language query (matches predicate or value). Replaces Graphiti’s search_memory_facts.

quipu_episodes_complete

Graphiti-compatible flat episode ingestion: accepts name, body text, group, and source, then converts to a Quipu episode and ingests.

quipu_impact

Impact analysis: walk downstream from an entity. With remove=true, speculatively retracts the entity first (counterfactual). The store is never mutated.

quipu_path_cone

Golden paths: compute the provenance cone of a trajectory — which steps did its falsifier-gated verified result depend on? Per-step verdicts are in-cone (load-bearing; pruning needs a human Decision), out-of-cone (mechanically prunable), or cannot-evaluate (no derivation edges recorded — never silently prunable). Refuses trajectories with no steps or no falsifier-gated verification. See the golden-paths design.

quipu_path_backtest

Golden paths: backtest a pruned candidate (exemplar trajectory minus omitted steps) over recorded history — which past trajectories with a shared work-item topic would have conformed under gp-grammar/1, and how did their work items close? Distinguishes 0 matches from cannot-evaluate, and refuses a pattern it cannot compile.

quipu_unified_search

Unified knowledge search for Bobbin integration: combines text and optional vector search, returning results tagged source="knowledge" with normalized 0–1 scores.

quipu_ask

Run a curated, parameterized named query by name instead of hand-writing SPARQL. The catalog is self-describing: call with no name (or name="list") to list every query, its parameters, and their types.

Catalog:

Parameters are validated and escaped by type before substitution, so values are safe against SPARQL injection. The response includes the resolved sparql, the result columns, and rows.

Example — service dependencies of an entity:

{ "name": "service_deps", "params": { "entity": "http://example.org/traefik" } }

quipu_queries

Manage stored named queries — competency questions a consumer ships with its domain, callable through quipu_ask alongside the compiled-in catalog. Definitions are validated at load and versioned (re-loading a name closes the prior version rather than overwriting it).

quipu_graph_list

List registered named graphs with class, source, storage lifecycle, and labels (freshness / durability / trust / policy / kind). The read half of the graph-kinds surface, and the consumer capability probe: a store that does not serve this tool (or GET /graphs) predates the kind axis, which a consumer must treat as “cannot tell” — never as “no graphs”.

quipu_graph_freeze

Deep-freeze a named graph: export its full history (retracted rows and transactions included) into a read-only archive pack, verify the copy by content hash, delete the local rows, and re-attach the pack — the graph stays addressable at the same IRI. Compose frozen graphs back in with FROM <iri>, FROM <urn:quipu:dataset:frozen>, or include_kinds: ["archive"]. Known cost: as_of_tx time travel is refused while any archive is attached (pre-existing rule for attachments); valid-time queries survive.

quipu_graph_thaw

Thaw a frozen graph: verify its archive pack, detach it, restore the full history into the local store under the same IRI, and reopen the graph for writes. The pack file is kept on disk; the freeze registry row is closed, never deleted.

quipu_datasets

Manage named datasets — a reusable name for an arbitrary set of graphs, so it can be labelled, governed and handed to another agent. FROM <dataset-iri> then means FROM over its members.

quipu_propose_schema_change

Submit a schema-evolution proposal (shape, class, property, or ontology change). Proposals require explicit acceptance before taking effect.

quipu_list_proposals

List schema-evolution proposals, optionally filtered by status.

quipu_accept_proposal

Accept a pending schema proposal. Shape proposals are validated before writing.

quipu_reject_proposal

Reject a pending schema proposal with a reason.

quipu_resolve_entity

Check for existing near-duplicate entities before writing, using vector similarity and canonical-name matching (Jaro-Winkler). Returns candidates with similarity scores and match explanations.

quipu_load_ontology (requires owl feature)

Manage OWL ontologies: load (parse + materialize entailments), list, or remove. Only registered when Quipu is built with the owl feature.