Operations

MCP server

The same nine verbs as the Python API, exposed over the Model Context Protocol. One server, every compatible client.

2 min readUpdated May 12, 2026Edit on GitHub

Why MCP

MCP gives an LLM client (Claude Code, Cursor, Codex, Windsurf, Cline, etc.) a uniform way to call external tools. Running atlaso mcp exposes the full Memory surface — with the same Field 3.0 vocabulary, the same conflict-aware verdicts, and zero per-framework adapter code.

Install

bash

pip install "atlaso[mcp]"

This pulls in fastmcp>=0.2,<0.4 — the only MCP runtime dep. Without the extra, atlaso mcp prints an install instruction and exits 1.

Run

bash

atlaso mcp

The server runs on stdio— that's the transport every MCP client speaks. There's no HTTP server to manage.

Wire up Claude Code

Add an MCP server entry to your Claude Code config and atlaso's nine verbs become callable as tools.

~/.config/claude/mcp_servers.json

{
  "mcpServers": {
    "atlaso": {
      "command": "atlaso",
      "args": ["mcp"]
    }
  }
}

Tools exposed

Tool names match the Python method names exactly.

text

add          content, user_id, polarity?, evidence_grade?, scope_note?, tags?
recall       query, user_id, limit?
get          deposit_id, user_id
list_recent  user_id, limit?, offset?
contradict   new_text, contradicts: list[str], reason, user_id
retract      deposit_id, reason, user_id, hard_delete?
health       user_id, window_days?
peek         user_id, limit?
add_many     user_id, items: list[dict], on_gate_reject?

# add_many items[] schema:
#   content         (required, str)
#   idempotency_key (required, str)
#   polarity        (optional, default "open")
#   evidence_grade  (optional, default "anecdotal")
#   scope_note      (optional, str)
#   tags            (optional, list[str])
#   contradicts     (optional, list[str])

Claude Code hooks

Hooks make memory automatic. Where MCP gives the agent tools it has to remember to call, hooks fire on every prompt and turn-end regardless. Install both in one command:

bash

atlaso install-hooks --scope user

This writes ~/.atlaso/hooks/atlaso_recall_hook.sh and atlaso_deposit_hook.sh, then registers them in ~/.claude/settings.json:

UserPromptSubmit — synchronous atlaso recall, prepends results to context via hookSpecificOutput.additionalContext.
Stop — async fire-and-forget atlaso add with --tag claude-code --tag auto-deposit.

Both hooks resolve user_id from $ATLASO_USER, falling back to $USER. They fail silently on timeout or missing CLI — the agent's turn is never broken by a hook.

Previous← CLI reference NextConfiguration →

Was this page helpful?

Tools exposed

Tool names match the Python method names exactly.

text

add          content, user_id, polarity?, evidence_grade?, scope_note?, tags?
recall       query, user_id, limit?
get          deposit_id, user_id
list_recent  user_id, limit?, offset?
contradict   new_text, contradicts: list[str], reason, user_id
retract      deposit_id, reason, user_id, hard_delete?
health       user_id, window_days?
peek         user_id, limit?
add_many     user_id, items: list[dict], on_gate_reject?

# add_many items[] schema:
#   content         (required, str)
#   idempotency_key (required, str)
#   polarity        (optional, default "open")
#   evidence_grade  (optional, default "anecdotal")
#   scope_note      (optional, str)
#   tags            (optional, list[str])
#   contradicts     (optional, list[str])

Claude Code hooks

Hooks make memory automatic. Where MCP gives the agent tools it has to remember to call, hooks fire on every prompt and turn-end regardless. Install both in one command:

bash

atlaso install-hooks --scope user

This writes ~/.atlaso/hooks/atlaso_recall_hook.sh and atlaso_deposit_hook.sh, then registers them in ~/.claude/settings.json:

UserPromptSubmit — synchronous atlaso recall, prepends results to context via hookSpecificOutput.additionalContext.

Stop — async fire-and-forget atlaso add with --tag claude-code --tag auto-deposit.

Both hooks resolve user_id from $ATLASO_USER, falling back to $USER. They fail silently on timeout or missing CLI — the agent's turn is never broken by a hook.