MCP

Fontana Knowledge Graph exposes agent retrieval as a first-party Model Context Protocol server on kg-engine (/mcp, Streamable HTTP). Agents explore through a six-tool evidence loop: search or open a chunk, read related entities and hop keys in the same payload, then hop to more chunks. A pre-seeded connection named knowledge-graph is available to every agent you assign Knowledge Graph namespaces to.

Agent→MCP client (knowledge-graph connection)→kg-engine /mcp→Namespace ACL check→FalkorDB→Tool result + path citations

The engine resolves the caller's namespace allow-list from Convex on every call and fails closed: missing or unresolvable caller context returns an empty result with an explicit auth error, never a cross-namespace answer.

Tool catalog

Tool	What it does
kg_search	Hybrid search (full-text, vector, graph expansion) fused with RRF. Returns capped chunk-centric evidence packages with citations, mentions, REL neighbors, and hop keys.
kg_open	Open packages by exactly one of chunkKey, outlineKey, entityKey, or fileId.
kg_hop	Typed hop from a graph key onto related packages (mentions, rel, similar, next_chunk, outline_child, same_type).
kg_ontology	Published TBox for a namespace (entity types, relation types, PATTERN endpoints).
kg_entity_search	Named-entity entry by text and/or vector similarity; returns type labels and mention evidence packages.
kg_namespaces	List Knowledge Graph namespaces the caller may search.

Enable these tools on an agent with the Knowledge capability tile (mcp_knowledge-graph.*).

Evidence packages

Every search, open, hop, and entity-search hit is a chunk-centric evidence package: chunk text, human citation (namespace/vfsPath plus outline trail and pages when known), capped mentions and REL neighbors with type labels, outline section context, and keys for follow-up hops. Arrays carry truncated and total when clipped at the requested cap.

Cap	Default	Hard max
topK	8	32
mentions	8	24
rel	8	24
ancestors	6	12
children	8	24
similar	4	16

Pass caps on the tool call to override defaults. Values over the hard max fail closed with an error. Optional tokenBudget omits or truncates chunk text.

Hybrid search (kg_search)

kg_search runs one or more retrieval lanes and fuses results with reciprocal rank fusion (RRF):

Parameter	Default	Purpose
query	(required)	Search text
namespaces	All allowed	Subset of the caller’s namespace allow-list
lanes	fulltext, vector, graph_expand	Which lanes to run; a failed lane soft-fails empty without aborting the whole search
tokenBudget	none	Estimated token cap on returned chunk text
filters	none	Collection, folder, temporal, and relation filters
ranking.rrfK	60	RRF constant k
ranking.laneWeights	1 each	Per-lane multipliers on RRF contributions
ranking.minScore	none	Drop hits below this display score (0–1 scale)

Multi-namespace search keeps per-namespace and per-lane soft-fail: empty the failed lane or namespace, continue others, never abort the agent turn.

Open, hop, ontology, entities

• kg_open: Resolve one key to packages when you already have a chunk, outline, entity, or file id.
• kg_hop: Expand from fromKey with a typed kind. Similarity uses labeled SIMILAR_TO matches, not unlabeled expand.
• kg_ontology: Fetch the published type box when you need TBox without stuffing it onto every search hit.
• kg_entity_search: Start from a name; results still land on mention packages so answers stay citation-backed.

Namespace ACL, fail closed

Unlike a shared, install-wide MCP surface, every KG tool call is namespace-ACL-enforced inside the engine. On each call, kg-engine resolves the caller’s namespace allow-list from Convex (a short-TTL cached service query). If that context is missing or cannot be resolved, the call fails closed: an explicit auth error, never a silent empty result or a cross-namespace answer.

Handshake (initialize / tools/list) uses the install service token alone. Tool execution attaches x-fontana-kg-caller (Convex user and agent context, or a PAT lane for external clients).

Fail closed means what it says

A missing or expired caller context is not treated as unrestricted access. It is treated as zero access. This is the same posture Fontana applies to the shared OpenSandbox MCP server and the Slack channels bridge: least-privilege by default, with an explicit deny rather than an implicit allow.

MCP versus auto-injection and plain S2S

Fontana gives you these Knowledge Graph retrieval paths:

• The knowledge-graph MCP connection: the six tools above, namespace-ACL enforced. Enable on an agent with the Knowledge capability tile.
• Server-side auto-injection: each user turn may inject qualifying kg_search evidence packages as a Knowledge Search system row when the chat KG toggle is on and the agent has namespaces configured. Injection calls the same MCP path agents use.
• Plain service-to-service HTTP: KG Studio Graphs (layout, subgraph, ontology persist) and remaining Studio Search debug lanes talk to kg-engine over HTTP. Studio Graphs does not speak MCP because it needs bulk, cache-friendly payloads, not tool-call semantics.

Agent Memory writes use the separate Agent Memory tile (knowledge_addMemory / knowledge_forgetMemory), not MCP.

Tenant path exposure

On each tenant origin, kg-engine is path-routed like the workflow engine and chat-channels bridge:

• Health: https://<tenant>.<baseDomain>/_kg-engine/health (no auth)
• MCP (Streamable HTTP): https://<tenant>.<baseDomain>/_kg-engine/mcp

In-cluster (Convex agents): http://kg-engine:8720/mcp with the install S2S bearer. Connect and tool discovery use the service token alone. Agent tool calls also send x-fontana-kg-caller.

External MCP clients (Cursor, scripts): create a personal access token in Flow at Admin → Personal access tokens (/admin/access-tokens) on your tenant origin. Send Authorization: Bearer fnt_pat_… on /_kg-engine/mcp. Do not use FONTANA_KG_ENGINE_SERVICE_TOKEN; that token is for Convex to kg-engine service traffic only.

fontana resources <tenant> lists the /_kg-engine base URL on the Flow hostname.