MCP tools reference

Esment is an MCP server on two transports. Both serve the same memory tools; the HTTP surface is a little smaller and its descriptions are written for remote clients.

• HTTP on the Mac. The engine serves Streamable HTTP at http://127.0.0.1:8080/mcp. It listens on your Mac only, unless you turn on the tunnel in the app, which gives it a public https address ending in /mcp.
• stdio on the Mac. The app bundles esment-mcp, a local MCP server that apps such as Claude Desktop, Cursor and Codex start themselves.
• Cloud. The hosted endpoint is a single /mcp URL, shown on the Assistants page of the dashboard. It looks like https://cloud.esment.notas.ai/mcp.

The HTTP endpoint is stateless: each request is resolved to a workspace from its credential, and no session is needed for routing. POST carries JSON-RPC messages.

{
  "mcpServers": {
    "esment": {
      "url": "http://127.0.0.1:8080/mcp",
      "headers": { "Authorization": "Bearer <admin-token>" }
    }
  }
}

# ~/.codex/config.toml
[mcp_servers.Esment]
command = "/Applications/Esment.app/Contents/MacOS/esment-mcp"
args = ["--config", "<path to config.toml in the .esment folder>"]

Every request to /mcp needs a bearer credential, and every tool call is scoped to one workspace. Two kinds are accepted.

• OAuth 2.1 access token. For web assistants. The flow is authorization code with mandatory PKCE (S256). Clients register dynamically or identify themselves with a client metadata document, and the token is bound to the /mcp resource.
• API key. Send it as Authorization: Bearer <key>. On the cloud, create one in Settings → Workspace. On the Mac, use the admin token, or an extra key from Settings → Connection → API keys.

Without a valid credential the server answers 401 with a WWW-Authenticate header that points at the protected-resource metadata, which is how OAuth clients discover the sign-in. The metadata and sign-in routes are:

GET /.well-known/oauth-protected-resource
GET /.well-known/oauth-authorization-server
GET /oauth/jwks
POST /oauth/register
GET  /authorize
POST /oauth/token
POST /oauth/revoke

Keys carry a permission, read only, read write or admin, so a read-only key cannot call the write tools.

By default the server shows the personal profile: the everyday tools below. On the Mac, turn on Settings → Advanced → MCP tools → Advanced tools for the full profile, then restart the assistant. Two names are aliases: recall for search_context and remember for add_memory.

Start and recall

• session_brief: loads the usage profile, Memory Blocks, pinned facts, per-entity summaries and recent work in one call. Call it once at the start of a chat. Arguments: input (the user’s message, adds a relevant-now section), budget_tokens.
• search_context (alias recall): searches memory. Arguments: query (required), top_k (default 20), space. Over HTTP also tags (all must match) and since (RFC 3339).
• get_context (stdio only): memory relevant to a message. Arguments: query (required), format (markdown, json, xml or plain).
• list_memories: lists stored memories. Arguments: space, limit (default 50); memory_type over HTTP, lifecycle over stdio.

Save and change

• add_memory (alias remember): saves a fact. Arguments: content; memory_type (episodic, semantic, procedural or fact); tags; space; evergreen (pin it); voice_note_id and at to link a voice note. Over HTTP, facts saves several at once and replaces lists ids of memories being corrected, which the user can undo.
• update_memory: replaces the text of a memory in place. Arguments: memory_id, content (the full new text).
• confirm_memory: the user restated a stored fact, so raise its importance instead of saving a duplicate. Argument: memory_id.
• forget_memory: expires a memory. Argument: memory_id.
• add_event: records a timestamped event. Arguments: content, event_type, source, importance.

space is one of user, session, agent, org or task. Each saved memory is also stamped with the assistant that wrote it, taken from the client name the connection announced. That is not a tool argument.

Memory Blocks and pages

• get_memory_block: reads a block by name (soul, facts, persona, project or a custom one).
• update_memory_block: overwrites a block. Arguments: name, content (full text), kind, position, enabled.
• list_memory_blocks (stdio only): lists every block.
• list_pages: lists Library pages. Arguments: kind (authored, derived or imported), limit.
• get_page: reads a page by wiki path such as entities/acme. provenance: true adds the source memories of each sentence.

The block tools are hidden on plans without Memory Blocks (see Memory Blocks).

Voice notes

• list_voice_notes: notes waiting to become memories. Arguments: status (pending, processed or all; default pending), query, limit.
• get_voice_note: one note’s timestamped transcript. Argument: id. The first memory saved with its voice_note_id marks it processed.

Hidden on plans without voice notes (see Voice notes).

Statistics and audit (full profile)

• get_stats: counts for the workspace. commit_history (limit), get_commit (hash), get_audit_trail (memory_id) and diff_memory (from, to) read the change log of the store.
• time_travel_memory: memories valid at a past moment. Arguments: query, at (required), top_k.

Other stdio tools

Over stdio, get_memory_health, toggle_observational_memory, get_context_window and close_session manage Observational Memory sessions. The full profile adds get_entity_graph, sample_finetune_dataset and apply_lifecycle.