MCP tools

Carabase ships a Model Context Protocol server that exposes the host’s retrieval layer as callable tools. Any MCP client can consume it — the OpenClaw gateway, Claude Desktop, Cursor, Codex, the MCP Inspector — over Streamable HTTP at /mcp (and the legacy SSE surface at /mcp/sse). The in-process agent runtimes and chat engines call the same tools directly.

The canonical tool surface is a single, DB-agnostic source of truth that any consumer can import. It defines exactly 14 canonical tools; the host mounts that surface, adds a couple of host-only write tools, and registers two legacy aliases (search_semantic → carabase_search_semantic, query_graph → carabase_search_graph).

The 14 canonical tools

All 14 are read/retrieval tools. They are the only retrieval surface an external MCP client or an in-process ReAct loop can reach.

carabase_search_semantic(query, limit?)

Semantic vector search across artifacts (documents, notes, memories, knowledge). Returns the top limit (default 5) chunks ranked by similarity, each with a carabase://artifact/<id> resource URI for the full body. When the workspace has unified embeddings enabled, this runs as a dual-leg (legacy-1536 + unified-1024) search fused with reciprocal rank fusion — fused hits carry an rrf_score, single-leg hits carry a cosine score.

{ "query": "what did Alice say about pricing?", "limit": 5 }

carabase_search_graph(entity, depth?, min_confidence?, source_kinds?, as_of?, include_invalid?)

Knowledge-graph traversal from a named entity. Walks edges up to depth hops (clamped to 1–3, default 1), optionally filtering by edge confidence and provenance. Honest confidence scores — there is no default min_confidence; you opt in.

{ "entity": "Alice Chen", "depth": 2, "min_confidence": 0.6, "source_kinds": ["extracted"] }

source_kinds accepts "extracted" (directly observed), "inferred" (LLM/curator-derived), and/or "ambiguous" (awaiting human review). as_of (ISO-8601) time-travels the graph to facts that were valid at that instant; include_invalid returns both currently-valid and superseded edges, each rendered with its [valid_at – invalid_at] interval. By default only currently-valid facts are returned.

carabase_query_metadata(tags?, date_after?, date_before?, source?, entity_name?, limit?)

Structured filter over artifact columns — the only leg that accepts a temporal range. Combine tags (AND semantics), a created_at date window, a source substring, and a linked entity_name. Use this for “what did I write last Tuesday?” type questions.

{ "entity_name": "Acme Corp", "date_after": "2026-01-01", "tags": ["contract"], "limit": 10 }

carabase_find_entity_candidates(name, limit?)

Disambiguation lookup — given a name fragment (“Alice”), returns candidate canonical entities plus their context, so the agent can resolve the right one before traversing the graph.

carabase_route_and_execute(query, concept_root_ids?, cursor?)

Cross-strategy router. Classifies the query, resolves primary entities, runs the appropriate strategies, and returns the fused result set ranked by relevance. The top hits (up to 10) are hydrated with a query-anchored snippet; any remainder is reported as a count plus a cursor you pass back to page the next batch. The default entry point when the agent doesn’t want to compose tools itself.

{ "query": "everything about the Q3 roadmap" }

carabase_query_timeseries(source, metric, range, aggregation?, group_by?)

Substrate-table time-series queries. Reads pre-aggregated rows from connector substrate tables (Strava, Spotify, Last.fm, Whoop, and others declared via a manifest’s substrateTable block) so the agent doesn’t re-aggregate downstream. range (with both from and to) is required — there is no default window.

{ "source": "strava", "metric": "distance_meters", "aggregation": "sum", "group_by": "week", "range": { "from": "2026-01-01", "to": "2026-05-01" } }

group_by accepts "day" | "week" | "month" for time bucketing, or the metric’s categorical column (e.g. "activity_type" for Strava). When the underlying substrate has been purged out from under the aggregate, the result carries metadata.aggregate_status: "aggregate_only" so the agent can present a freshness caveat.

carabase_resolve_mesh_uri(uri)

Just-in-time mesh resolver for hollow / metadata-only artifacts. Hydrates the body from the source connector at query time, compacted to a token budget, and returns provenance (connector, uri, fetched_at). The host-side resolver enforces a capability and budget ladder (connector capability → per-account flag → token caps → daily budget → per-workspace concurrency). REST companion: POST /api/v1/mesh/resolve.

carabase_verify_hypothesis(claim, limit?)

Corroborate vs. contradict a natural-language claim against retrieved evidence.

{
  "verdict": "corroborated" | "contradicted" | "mixed" | "inconclusive",
  "corroborated_by": [...],
  "contradicted_by": [...]
}

It uses an LLM entailment judge (per-snippet supports/refutes/neutral), degrading to a lexical overlap/negation heuristic when no judge is wired.

carabase_traverse_memory_network(anchor[], mode?, depth?, link_types?, min_confidence?, limit?)

Personalized PageRank over the memory-network typed graph. Seeds at anchor[] (memory UUIDs — keyword anchoring requires a prior carabase_search_semantic call to resolve IDs first), walks typed edges filtered by link_types and min_confidence, and returns the top memories ranked by stationary distribution. Modes: "pagerank" (default), "shortest_path", "neighbours"; depth 1–3 (default 2).

carabase_search_visual(query, limit?, source_kinds?)

Text→image nearest-neighbour search over the 1024-dim image_embeddings space (the same basis photo bytes are embedded into). Finds photos by description.

carabase_search_multimodal(query, limit?, text_weight?, visual_weight?)

Fuses the text and image legs into one ranked set (reciprocal rank fusion with per-leg dedup and a matched_via accumulator), for queries that span documents and photos. Optional text_weight / visual_weight bias the fusion.

carabase_scan_mesh(...)

Read-only self-survey of the workspace mesh, used by the nightly mesh-scan cron and the proposal skills (gated per skill by an opt-in flag). Filters by date range, tags, metadata key/value, and source.

carabase_read_folio(slug?, id?, kind?, status?, limit?)

Read a synthesized folio’s narrative and its citations, so taste / domain / project questions are answered from the cited narrative instead of re-derived from raw hits. Pass slug or id to fetch one folio (slug wins if both); omit them to list folios filtered by kind (taste / domain / project) and status.

carabase_search_lexical(query, kinds?, limit?)

pg_trgm fuzzy/substring grep for rare proper nouns and “grep my notes for X” queries that cosine semantic search structurally abstains on. The agent leg runs at a raised trigram threshold (0.5) to cap the multi-word fan-out; the desktop Summon Bar keeps the Postgres default (0.3).

Host-only tools

These live in the host (not the canonical surface) and run only in the in-process agent-runtime / chat path — they are not served over /mcp.

carabase_read_artifact

The snippet→full-body hydration tool: fetches a complete artifact body (and an email’s attachments). It exists because the AI-SDK ReAct loop cannot call the MCP resources/read verb that the carabase://artifact/{id} resource serves. It retries once then emits a typed [hydration_failed] signal rather than a bare “not found”, resolves a backing artifact for a graph entity that has no directly-readable body, and memoizes by id through a per-run cache so a chunked document hydrates once.

commit_to_folio(folio_name, content)

Find or create a named folio and add a new commit with the given content. Splits the content into chunks, embeds each, and links them via a single commit. Used by the dream injector and the agent’s research-and-summarize flows. Fuzzy-matches an existing folio when the name doesn’t hit exactly.

carabase_attach_file / carabase_commit_session

Available only in the in-process agent-runtime path. carabase_attach_file attaches a file artifact to the originating logCard of an agentic-flow run; carabase_commit_session commits a captured AI coding session into its bound project folio(s). Write tools are denied when a run holds a read-only MCP token.

External MCP servers

The agent runtime can additionally pull tools from per-workspace external MCP servers registered for the workspace. At session start the runtime queries each enabled server, namespaces its tool list, and lays the discovered tools alongside the canonical Carabase surface. Failures are isolated per server, so a down external endpoint never breaks the canonical tools. This is how, for example, a local Beeper Desktop MCP endpoint can be exposed to the agent.

Resources

The MCP server also exposes resources (URIs the client can call resources/read on):

URI pattern	What it returns
carabase://artifact/{id}	Lazy artifact body fetch. Tool results return URIs of this form so the client only fetches the bodies it actually needs.
folio://{id}/readme	Folio name + README summary.

When folio proactive priming or the mesh surface map are enabled, additional gated resources register: carabase://surfaces (a read-only link index of connected accounts, folios, skills, and external MCP servers) and an owner-context surface under carabase://folios/leads. When disabled, these are unregistered entirely — they do not appear in resources/list.

Hint repair

When a Carabase tool returns 0 results or an error, Carabase appends a structured [hint: ...] and [trace: ...] trailer to the response so the agent can course-correct without resetting its chain of thought (for example, suggesting the metrics or aggregations a substrate actually supports). Hints are deterministic — no extra LLM call.

Format-aware compaction

Artifact bodies fetched through carabase://artifact/{id} can be auto-compacted to fit a token budget: CSVs preserve the header plus matching rows, markdown keeps headings plus relevant paragraphs, and PDFs split by page and rank pages by query-token frequency. This is opt-in via the tool context and off by default in the host shim.