@engramprotocol/mcp-server

MCP wrapper around the EML HTTP API. Exposes the Engram Protocol as MCP tools for Claude Code (and other MCP clients) — stdio transport, Bearer token auth against api.engramprotocol.io.

Request an API token: [email protected]

Install

EML_API_TOKEN=eml_<prefix><secret> \
  npx --prefer-online @engramprotocol/mcp-server@latest setup install

The installer:

• Verifies the token against /stats before storing
• Writes ~/.eml/config (chmod 600) with URL + token + client-version
• Registers the engramprotocol MCP server via claude mcp add (user scope, stdio transport, pinned to @latest)
• Adds two hooks to ~/.claude/settings.json (see Hooks below):
  • SessionStart → loads your brain at session start (identity, rules, decisions, status, tasks, protocol conventions)
  • UserPromptSubmit → light mid-session reminder on turn 1, every 5 turns, or after >1h pause
• Adds two permissions: mcp__engramprotocol__* (skip per-call prompt for EML tools) and Bash(npx --prefer-online @engramprotocol/mcp-server@latest setup *) (let the agent auto-execute setup update when prompted)
• Performs a final /stats round-trip as smoke test

A backup of ~/.claude/settings.json is created first (pattern .pre-eml-install-YYYY-MM-DD-HH-MM-SS.bak).

Update

npx --prefer-online @engramprotocol/mcp-server@latest setup update

Refreshes hook templates (marker-aware — preserves files you customised), bumps EML_CLIENT_VERSION in ~/.eml/config. Idempotent. The @latest suffix busts the npx cache so you actually get the new version.

Uninstall

npx --prefer-online @engramprotocol/mcp-server@latest setup uninstall

Removes the MCP registration, the two managed hook entries, the two managed permission entries, and ~/.eml/hooks/. Your own hooks and permissions are untouched. ~/.eml/config is kept by default (asks for confirmation before delete — it contains your token).

Hooks

Two bash hooks land in ~/.eml/hooks/:

session_start_boot.sh (SessionStart event)

• Sources ~/.eml/config, POSTs to /boot, prints the returned markdown to stdout
• Claude Code injects that stdout into model context — invisible in chat but reaches the model (verified empirically; behavior decided 2026-05-15)
• Performs an update-banner check: if EML_CLIENT_VERSION from config differs from /boot.version, emits a banner pointing to setup update
• Fail-soft: missing config, missing vars, or unreachable server emits a warning and exits 0 — session continues without brain

user_prompt_submit_reminder.sh (UserPromptSubmit event)

• Local only, no HTTP
• Triggers a 5-bullet reminder on turn 1, every 5 turns, or after >1h pause
• Per-session turn counter at /tmp/eml-turns/<session_id>
• Reminder content is a heredoc inside the script — refreshed via setup update

Both hooks log to ~/.eml/logs/<event>-YYYY-MM-DD.log (self-rotating per day) and carry a # managed-by: engramprotocol-setup marker line that lets setup update / setup uninstall identify which files they own.

Tools (v0.11.0)

All tools have an eml_ prefix. Total: 17 tools.

Boot / Recall

| Tool | HTTP endpoint | Use case | |---|---|---| | eml_boot | POST /boot | Manual brain-reload (SessionStart-Hook does this automatically at session start) | | eml_recall | POST /recall | Topic search (FTS5 + recency) |

Write (typed)

| Tool | HTTP endpoint | Use case | |---|---|---| | eml_decide | POST /context (type=decision) | Record a deliberate, documented decision | | eml_set_status | POST /context (type=status) | Set current status for a scope (auto-supersedes old active status) | | eml_track_task | POST /context (type=task) | Plan/track a task with priority + due date | | eml_note | POST /context (kind-discriminated) | Catch-all for rule/profile/event/reference/log |

Write-time conflict guardrail (v0.10.9). A typed write may return an advisory potential_conflicts list — active same-scope engrams the write looks likely to duplicate or contradict (FTS-retrieved, term-coverage-gated, top by coverage). The write always succeeds; the field is non-binding and the agent resolves each (supersede / merge / relate / dismiss). Surfaced inline at the write tool, so the prompt to resolve reaches the agent at the moment of the write.

Read / Find

| Tool | HTTP endpoint | Use case | |---|---|---| | eml_show | GET /brain-state?scope= | Curated snapshot for any scope | | eml_list | GET /list | Filter-based engram list | | eml_get | GET /engram/:id | Single engram + relations | | eml_projects | GET /projects | List projects (filter: status) | | eml_entities | GET /entities | List entities (filter: kind) |

Self-awareness / Edit

| Tool | HTTP endpoint | Use case | |---|---|---| | eml_stats | GET /stats | Brain stats (counts per type/scope, container counts) | | eml_update | POST /update | Patch engram (status/properties/etc.) |

Container CRUD

| Tool | HTTP endpoint | Use case | |---|---|---| | eml_project_create | POST /project | Register a project (required before scope=project.<id>) | | eml_project_update | PUT /project/:id | Patch project fields | | eml_entity_create | POST /entity | Register an entity (required before scope=entity.<id>) | | eml_entity_update | PUT /entity/:id | Patch entity fields |

Intentionally not exposed (v0.10.0)

• eml_relate — available via HTTP API directly
• eml_confirm_review — deferred to brain-hygiene cluster
• Epistemic-mode write tools (observation/hypothesis/assessment/prediction/pattern) — Alpha-state, available via HTTP API
• Session-Awareness tools — deferred to its own future version
• eml_*_delete — by design not in the agent action space; cleanup is operator-only

Error handling

Backend errors (e.g. 401 invalid token, 400 invalid scope) are returned as isError: true with a clear message — not as MCP protocol errors. The LLM can self-correct.

Protocol errors (malformed JSON-RPC, unknown tool name) are handled by the SDK.

License

MIT — see LICENSE.