Integration Guide

MCP Server

Expose Mithril's governance pipeline over the Model Context Protocol, so any MCP-aware agent (Claude Desktop, Cursor, etc.) reads and writes memory through Mithril instead of calling Cognee directly.

🛡️

Zero-Trust Memory

Every remember() call passes the trust gate — contradiction detection, source reputation scoring, and secret redaction — before anything touches Cognee.

🔍

Verified Recall Only

recall() returns answers exclusively from claims that cleared Mithril's admission pipeline. Poisoned or quarantined memory is automatically excluded.

📋

Quarantine Inspector

Agents can call mithril_quarantine_list to see exactly what was blocked and why — full provenance for every rejected write.

📊

Live Source Reputation

mithril_source_reputation shows adaptive trust scores. Sources caught contradicting verified memory lose trust over time; accepted sources gain it slowly.

Getting Started

Install dependencies

Make sure you have the project installed with its dependencies:

terminal

uv pip install -e ".[dev]"
# or
pip install -e ".[dev]"

Set environment variables

Copy .env.example to .env and set your LLM API key (needed for contradiction and content-danger scoring):

terminal

# macOS / Linux / WSL
cp .env.example .env

# Windows PowerShell
Copy-Item .env.example .env

# Edit .env and set LLM_API_KEY, LLM_ENDPOINT, and LLM_MODEL.

Start the MCP server

For a manual smoke test, run via Make on Windows or directly with Python on any OS:

terminal

# Windows, using this repo's Makefile
make mcp

# macOS / Linux / WSL
python -m mcp_server.server

Register in an MCP host

MCP hosts launch the server for you, so use absolute paths for both command and cwd. Replace the sample path with your local repo path.

claude_desktop_config.json

{
  "mcpServers": {
    "mithril": {
      "command": "/absolute/path/to/hack-ideas2/.venv/bin/python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/absolute/path/to/hack-ideas2"
    }
  }
}

On Windows, the command path usually looks like C:\Users\you\path\hack-ideas2\.venv\Scripts\python.exe. In WSL, use the Linux path inside WSL and configure the IDE that is running inside WSL.

IDE Settings

🖥️

Claude Desktop

Add the server under mcpServers in claude_desktop_config.json, then fully restart Claude Desktop. Common config locations are %APPDATA%\Claude on Windows and ~/Library/Application Support/Claude on macOS.

⌨️

Cursor

Add the same server object in Cursor's MCP settings or in a workspace .cursor/mcp.json file if your Cursor version supports project-level MCP configuration. Keep cwd pointed at the repo root so load_dotenv() finds .env.

.cursor/mcp.json

{
  "mcpServers": {
    "mithril": {
      "command": "/absolute/path/to/hack-ideas2/.venv/bin/python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/absolute/path/to/hack-ideas2"
    }
  }
}

Tools Reference

toolmithril_remember

Submit a memory claim through Mithril's trust gate. The claim is scored for source reputation, checked for contradictions against verified memory, and only stored in Cognee if it clears the admission threshold.

Parameter	Type	Required	Description
`text`	string	required	The claim or fact the agent wants to remember.
`source`	string	optional	Where it came from, e.g. "Slack", "Security Policy". Defaults to "AI Agent".
`author`	string	optional	Who or what produced it. Defaults to "mcp_agent".

Example response

Decision: WARN (STORED in verified memory)
Trust score: 0.84
Reason: Score 0.84 accepted with warning — low confidence

Breakdown:
  - Source 'Security Policy' live reputation: 0.98
  - No contradictions found in verified memory
  - Weighted sum: 0.39 (source 0.39, corroboration +0.00, freshness +0.00, contradiction -0.00, content_danger -0.00)
  - Normalized trust score: 0.84 (÷ 0.47 max theoretical)

toolmithril_recall

Query only verified memory. Poisoned and quarantined claims are excluded, so the agent can't be misled by unverified data.

Parameter	Type	Required	Description
`query`	string	required	The question to answer from verified memory.

toolmithril_quarantine_list

List memory claims Mithril blocked (quarantined / rejected / under review). Inspect exactly what was kept out of memory and why.

toolmithril_source_reputation

Show Mithril's current, adaptive trust score for every known source. Sources caught contradicting verified memory lose trust; accepted sources gain it slowly.