Knolo MCP Server: Pinned Knowledge Images for AI Agents

Knolo is an open-source, local-first Knowledge Image runtime and format: you pack knowledge into a portable .knolo file, pin it by digest, and query it locally with @knolo/core (Apache-2.0, 6.2.0 on npm today). The Knolo MCP server, @knolo/mcp, puts those pinned images in front of AI agents over the Model Context Protocol. This guide covers what the server does, what it deliberately refuses to do, and how to wire it into an MCP client, using the live Knolo MCP docs on knolo.dev.

What the Knolo MCP server is

@knolo/mcp is a read-only stdio MCP server for pinned local V5 Knowledge Images. Version 0.2.0 is the npm latest tag (published 2 November 2026), requires Node 20 or newer, and expects @knolo/core ^6.2.0 and @knolo/tools ^0.2.0. Pins, policy checks, and query receipts come from @knolo/tools.

The core tool set is four calls:

• knolo_search: search the approved, verified images you mounted.
• knolo_get: read an authorized evidence object at the state root returned by search.
• knolo_verify: check the local bytes and V5 roots.
• knolo_status: list the mounts the caller is allowed to see.

The Knolo MCP docs list additional, optional evidence-check tools that appear only when a mount opts into them. None of the tools call a model.

What Knolo MCP will not do

The useful part of this server is its narrow scope. It speaks stdio only. It does not download images, open a runtime network connection, write or compile knowledge, or expose MCP resources or prompts. You install and pin each image before you start it.

It also fails closed. If an image's sha256, V5 stateRoot, or policy root does not match the pin in the config, the process exits non-zero before an MCP connection starts. If a pinned file changes on disk later, the server checks it against the pin before the next call; a mismatch returns IMAGE_INVALID and the previous image is not served. A mount removed from the config is no longer served, even if the file is still on disk.

Knolo MCP identity and receipts

Caller identity is agentId in the config file (default mcp), and that id must be listed in the mount's agents array. Tool arguments cannot set it. The MCP client's clientInfo.name is recorded on the receipt as sessionId and is not used for authorization.

Every search writes an openclaw-knolo-query-v1 receipt into auditDir before it returns hits. If the audit directory is not writable, the call returns AUDIT_UNAVAILABLE and no hits. No receipt, no answer. That is the same receipt shape described in Knolo query receipts, and it is why the server pairs well with the OpenClaw integration, which exposes the same four tools.

Configure Knolo MCP

Paths are absolute. sha256 is 64 lowercase hex characters; stateRoot is sha256- plus 64 lowercase hex characters. A minimal config from the package README:

{
  "agentId": "mcp",
  "auditDir": "/var/lib/knolo/receipts",
  "mounts": [
    {
      "id": "handbook",
      "path": "/opt/knolo/handbook.knolo",
      "sha256": "<64 hex>",
      "stateRoot": "sha256-<64 hex>",
      "policyPath": "/opt/knolo/handbook.policy.json",
      "agents": ["mcp"],
      "principal": "<policy principal>"
    }
  ]
}

Then register the server in your client. The README documents the same mcpServers block for Claude Desktop, Claude Code, and Cursor:

{
  "mcpServers": {
    "knolo": {
      "command": "npx",
      "args": ["-y", "@knolo/mcp", "--config", "/absolute/knolo-mcp.json"]
    }
  }
}

You can also start it with knolo-mcp --config /absolute/knolo-mcp.json or the KNOLO_MCP_CONFIG environment variable. Logs go to stderr; stdout is JSON-RPC only.

Getting a pinned Knolo image to mount

The MCP server serves images; it does not build them. The usual path:

1. Install the runtime and CLI per the Knolo installation guide. On npm today, @knolo/core is 6.2.0 and @knolo/cli is 6.2.1.
2. Build or migrate a V5 image with the Knolo V5 quickstart, then record its sha256 and stateRoot.
3. Confirm the bytes match their roots with Knolo verification, or pull a public image from Knolo Hub and pin it by digest.
4. Check the Knolo versions page for which package versions work together.

Verification answers one question: do these bytes match the roots they declare? It does not decide that a claim or an answer is true. What it does give an agent is a fixed, checkable source and an audit trail for every search.

Knolo resources

• Knolo on knolo.dev: docs, packages, and releases for developers.
• Knolo on knolo.org: open specifications, compatibility, and lifecycle notes.
• Knolo core repository on GitHub: source for @knolo/core, @knolo/mcp, and @knolo/tools, under Apache-2.0.

Knolo is maintained by Hive AI. The MCP server keeps the Knolo model simple: the knowledge lives in a file you pinned, the agent reads it through four read-only tools, and every search leaves a receipt.