# MCP & Hooks

<!-- Canonical: https://www.atlaso.ai/docs/mcp -->

Run atlaso as an MCP server (or as auto-fire hooks) inside Claude Code, Cursor, Codex, Windsurf, Cline — any MCP-compatible client.

## Why MCP

MCP gives an LLM client a uniform way to call external tools. Running `atlaso mcp` exposes the full `Memory` surface — same Field 3.0 vocabulary, same conflict-aware verdicts, zero per-framework adapter code.

## Install

```bash
pip install "atlaso[mcp]"
```

Pulls in `fastmcp>=0.2,<0.4`. Without the extra, `atlaso mcp` prints an install instruction and exits 1.

## Run

```bash
atlaso mcp
```

Runs on **stdio** — the transport every MCP client speaks. No HTTP server to manage.

## Wire up Claude Code

```json
// ~/.config/claude/mcp_servers.json
{
  "mcpServers": {
    "atlaso": {
      "command": "atlaso",
      "args": ["mcp"]
    }
  }
}
```

## Tools exposed

Tool names match the Python method names exactly.

| Tool | Args |
|---|---|
| `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:

```text
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])
```

## ATLASO_API_KEY at startup

The server starts even if `ATLASO_API_KEY` is unset — a warning prints to stderr. In v0.1 the local backend doesn't require it; tool calls succeed against the local field. The env var is sniffed today so v0.2 (remote backend) can enforce auth without breaking your config.

---

## 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.

```bash
atlaso install-hooks --scope user
```

Writes:

- `~/.atlaso/hooks/atlaso_recall_hook.sh`
- `~/.atlaso/hooks/atlaso_deposit_hook.sh`

And registers them in `~/.claude/settings.json`:

- `UserPromptSubmit` — synchronous `atlaso recall <prompt>`, prepends results to context via `hookSpecificOutput.additionalContext`.
- `Stop` — async fire-and-forget `atlaso add <last text>` 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.

### Remove

```bash
atlaso uninstall-hooks --scope user
```

Removes only the atlaso entries from `settings.json`. The shell scripts remain at `~/.atlaso/hooks/` — delete manually if you want a clean removal.

---

<!-- atlaso:doc-trailer -->
**Source:** <https://www.atlaso.ai/docs/mcp>  
**Edit on GitHub:** <https://github.com/imashishkh21/atlaso/tree/main/docs/mcp-and-hooks.md>  
**Updated:** 2026-05-12