MCP Setup

The Moatlog MCP server exposes behavioral memory as tools your agent can call. It reads moat.json from .moatlog/ and returns hot files, file histories, co-access patterns, and task-relevant context based on past agent sessions.

Available tools

  • get_hot_files — top files by agent access frequency
  • get_file_history — read/write counts, sessions, co-access for one path
  • get_co_accessed_files — files opened in the same sessions as a given file
  • get_task_context — files historically relevant to a task description

Configure your editor

If you ran moatlog init, .cursor/mcp.json and .cursor/rules/moatlog.mdc are already configured. Restart Cursor after init so the MCP server connects.

To configure manually, add Moatlog to a project-level .cursor/mcp.json or your global ~/.cursor/mcp.json. The server must run with your project root as cwd so it finds .moatlog/moat.json.

json
{
  "mcpServers": {
    "moatlog": {
      "command": "moatlog",
      "args": ["mcp"]
    }
  }
}

If moatlog is not on your PATH, use the full path to the binary or npx:

json
{
  "mcpServers": {
    "moatlog": {
      "command": "npx",
      "args": ["-y", "@moatlog/cli", "mcp"]
    }
  }
}

For manual setup, add .cursor/rules/moatlog.mdc with alwaysApply: true so agents call get_task_context at session start.

Run manually

moatlog mcp

Start the MCP server on stdio

Use this to test the server or debug tool responses. In normal use, your editor spawns this process automatically from MCP config.

Troubleshooting

If your agent reports that the Moatlog MCP server is missing or tools fail to connect, work through these checks in order.

  1. Build the CLI — project-level .cursor/mcp.json often points at packages/cli/dist/bin.js. Run yarn build from the repo root (or use npx @moatlog/cli mcp in MCP config if you installed from npm).
  2. Restart Cursor — MCP servers load at startup. After changing mcp.json or building the binary, restart Cursor or reload the moatlog server in Settings → MCP.
  3. Check server status — in Cursor Settings → MCP, Moatlog should show as connected. If it failed on launch, expand the entry for the error (missing binary, wrong cwd, etc.).
  4. Verify manually — from your project root, run moatlog mcp. You should see "moatlog MCP server running" on stderr. If that works but Cursor still fails, the issue is editor config, not the server.
  5. Start a new chat — after reconnecting MCP, open a fresh agent session so tools are available to the agent.