ra-h-os/docs/8_mcp.md

MCP Surface

RA-H exposes MCP tools for direct graph work against the local database or app API.

Core MCP Contract

• queryNodes is the primary tool for direct node retrieval when the user is trying to find a specific existing node.
• retrieveQueryContext is the primary retrieval entrypoint for substantive current-turn work when the agent needs graph context to support a broader answer.
• getContext returns graph orientation: stats, contexts, hubs, and skills.
• createNode and updateNode accept optional context_id but do not require context. Omitting context_id is the normal default.
• writeContext writes one confirmed durable context node and must never be called before explicit user approval.
• queryNodes searches title, description, and source, with optional context filters.
• dimensions are removed from the MCP contract.

Main Tools

Read:

• retrieveQueryContext
• getContext
• queryNodes
• queryContexts
• getNodesById
• queryEdge
• listSkills
• readSkill
• searchContentEmbeddings
• sqliteQuery

Write:

• writeContext
• createNode
• updateNode
• createEdge
• updateEdge
• writeSkill
• deleteSkill

Tool Behavior

• Always search before creating.
• If the user is trying to find a specific existing node, use queryNodes first.
• If the user is asking a broader question that would benefit from graph context, use retrieveQueryContext.
• Prefer explicit context assignment only when the primary scope is clear and a real context is already known.
• Do not send context_id: null unless the tool call is intentionally clearing an existing context.
• Do not assume the server will infer a best-fit context.
• Judge graph quality by node quality and edges, not taxonomy completeness.
• Keep writeback prompts terse and selective. The goal is not to ask constantly whether every useful sentence should be saved.