Skip to content

heimdall-mcp-tools.md

Latest commit

 

History

History
98 lines (69 loc) · 4.36 KB

heimdall-mcp-tools.md

File metadata and controls

98 lines (69 loc) · 4.36 KB

Enabling MCP Tools in the Agentic Loop

When Heimdall is enabled, the Bifrost chat uses an agentic loop: the model can call tools (e.g. run Cypher, get status). NornicDB can also expose MCP (Model Context Protocol) memory tools—store, recall, discover, link, task, tasks—so the LLM can manage graph memory in process (create nodes, link them, run semantic search) without leaving the chat.

These MCP tools are disabled by default to avoid bloating the context and to keep the assistant focused on query/status actions. This guide explains how to enable them and optionally restrict which tools are exposed via an allowlist.

Why MCP tools are off by default

  • Context size: Each tool adds name, description, and input schema to the system prompt. With all six MCP tools plus plugin actions (e.g. heimdall_watcher_query), the context grows and leaves less room for conversation.
  • Intent: Many users only want “ask questions about my database”; they don’t need the assistant to create nodes or run semantic discovery from the chat.

When you need in-chat memory (store facts, link concepts, run discover), enable MCP and optionally limit to the tools you use.

Quick enable (all MCP tools)

Environment

export NORNICDB_HEIMDALL_MCP_ENABLE=true
./nornicdb serve

With this, the agentic loop sees all six MCP tools: store, recall, discover, link, task, tasks.
See MCP Integration for tool semantics and parameters.

YAML

heimdall:
  enabled: true
  mcp_enable: true
  # mcp_tools omitted = all tools exposed

Allowlist (only specific tools)

To reduce context and limit what the model can do, expose only a subset of tools.

Environment

  • All tools (when MCP enabled): do not set NORNICDB_HEIMDALL_MCP_TOOLS (leave unset).
  • No tools (disable MCP tools even when “on”): set to empty. 
    export NORNICDB_HEIMDALL_MCP_ENABLE=true
export NORNICDB_HEIMDALL_MCP_TOOLS=
  • Only some tools: comma-separated list. 
    export NORNICDB_HEIMDALL_MCP_ENABLE=true
export NORNICDB_HEIMDALL_MCP_TOOLS=store,recall,link

Valid tool names: store, recall, discover, link, task, tasks.

YAML

heimdall:
  enabled: true
  mcp_enable: true
  # All tools (default when mcp_enable is true)
  # mcp_tools: [store, recall, discover, link, task, tasks]

  # No tools (empty list)
  # mcp_tools: []

  # Only store and link
  mcp_tools: [store, link]
  • Omit mcp_tools → all tools (when mcp_enable: true).
  • mcp_tools: [] → no MCP tools.
  • mcp_tools: [store, link] → only those two.

Configuration reference

Setting Env Default Description
Enable MCP tools NORNICDB_HEIMDALL_MCP_ENABLE false Expose MCP memory tools to the agentic loop.
Tool allowlist NORNICDB_HEIMDALL_MCP_TOOLS (unset) Comma-separated names. Unset = all; empty = none; e.g. store,link = only those.

Precedence is the same as the rest of NornicDB: environment variables override YAML.

How the agentic loop uses MCP tools

  1. User sends a message in Bifrost (e.g. “Remember that we use Postgres for the main DB and link it to the auth decision”).
  2. The model receives the system prompt plus plugin actions (e.g. heimdall_watcher_query) and, if enabled, MCP tool definitions (store, recall, discover, link, task, tasks).
  3. The model may return tool calls (e.g. store, then link) instead of or in addition to text.
  4. The handler executes each tool in process (same server, no HTTP to MCP); results are appended to the conversation and the model continues until it responds with content only.

So “enable MCP tools” here means: add these tools to the agentic loop in Bifrost, not “start the standalone MCP server” (that is controlled by MCPEnabled in server config).

Related documentation