Skip to main content

MCP Server Setup

Model Context Protocol (MCP) is an open standard that lets a host (an IDE, an agent runtime, a desktop client) discover and call tools exposed by a server over stdio or HTTP. iLAB Memory ships an MCP stdio server that surfaces all 8 facade methods as MCP tools — with full docstrings — so the agent can use them correctly without any additional prompt engineering on your side.

Run the server​

After installing the package, you get the ilab-memory mcp CLI entrypoint:

pip install ilab-memory
ilab-memory mcp --db-path ~/.ilab-memory/memory.db

The process speaks MCP over stdio. You don't run it directly — you register it as a server in your MCP host's config, and the host spawns it when needed.

Claude Code​

Claude Code reads MCP servers from either a project-local .mcp.json or the user-global ~/.claude/settings.json.

Project-local — .mcp.json at the repo root​

{
  "mcpServers": {
    "ilab-memory": {
      "command": "ilab-memory",
      "args": ["mcp", "--db-path", "./.ilab-memory/memory.db"]
    }
  }
}

User-global — ~/.claude/settings.json​

{
  "mcpServers": {
    "ilab-memory": {
      "command": "ilab-memory",
      "args": ["mcp", "--db-path", "~/.ilab-memory/memory.db"]
    }
  }
}

Restart Claude Code; the 8 tools (mem_session_start, mem_save, mem_search, mem_get_observation, mem_timeline, mem_session_summary, mem_session_end, mem_stats) appear in the agent's tool list immediately.

Claude Desktop​

Edit claude_desktop_config.json (location varies by OS — see Claude Desktop's docs):

{
  "mcpServers": {
    "ilab-memory": {
      "command": "ilab-memory",
      "args": ["mcp", "--db-path", "/Users/<you>/Library/Application Support/ilab-memory/memory.db"]
    }
  }
}

Restart Claude Desktop. The tools become callable from any chat.

Cursor​

Cursor supports MCP servers via its settings UI (Settings → Features → MCP). Register a new server with:

  • Command: ilab-memory
  • Args: mcp --db-path /absolute/path/to/memory.db

Cursor handles the rest.

Tools come pre-described​

note

Each tool's docstring (signature, parameters, when-to-call rules, error codes) is surfaced to the agent on tools/list. The docstrings live in package/src/ilab_memory/api/mcp.py and are deliberately verbose — the agent should not need an external CLAUDE.md to use them correctly.

For the canonical text the agent receives, read api/mcp.py directly or call tools/list against a running server.

Validating the connection​

A quick way to confirm the server is wired correctly:

  1. Start a fresh chat in your MCP host.
  2. Ask the agent: "Call mem_session_start for user_id='alice'."
  3. The agent should return a SessionStartResponse JSON — session_id, is_new=true, empty memories[] on a fresh database.

If the tool isn't in the list, double-check the command/args pair and that ilab-memory is on the host process's PATH.

See also​

Cookbook: Long-running agent

Library reference