MCP Setup

Configure HippoDid as an MCP server in your AI client.

Table of contents
  1. Overview
    1. Required environment variables
    2. Optional environment variables
  2. Claude Desktop
    1. 1. Find your config file
    2. 2. Add the HippoDid server
    3. 3. Restart Claude Desktop
    4. 4. Verify
  3. Cursor
    1. 1. Open MCP settings
    2. 2. Add server configuration
    3. 3. Verify
  4. OpenClaw
    1. 1. Configure the server
    2. 2. Workspace auto-detection
    3. 3. Compaction safety
  5. Generic MCP client
  6. hippodid init
  7. Troubleshooting

Overview

HippoDid runs as an MCP server via stdio transport. Once configured, your AI client will have access to 20 tools:

  • Character tools (7): create_character, list_characters, get_character, archive_character, update_character_profile, update_character_aliases, resolve_character_alias
  • Memory tools (4): add_memory, add_memory_direct, search_memories, delete_memory
  • File sync tools (9): sync_file, import_document, list_synced_files, get_latest_snapshot, get_sync_status, export_character, download_file, add_watch_path, list_watch_paths, force_sync

Required environment variables

Variable Description
HIPPODID_MCP_API_KEY Your HippoDid API key (hd_key_...) — required
HIPPODID_MCP_CHARACTER_ID Default character UUID for background sync — required for auto-sync
SPRING_DATASOURCE_URL PostgreSQL JDBC URL
SPRING_DATASOURCE_USERNAME Database username
SPRING_DATASOURCE_PASSWORD Database password

Optional environment variables

Variable Default Description
HIPPODID_MCP_WATCH_PATHS (none) Comma-separated paths to watch for auto-sync
HIPPODID_MCP_SYNC_INTERVAL_SECONDS 300 Sync polling interval in seconds
HIPPODID_MCP_AUTO_CAPTURE false Enable AI auto-capture (paid tiers only)
HIPPODID_MCP_AUTO_RECALL false Enable AI auto-recall (paid tiers only)
HIPPODID_MCP_RECALL_CACHE_TTL 120 Search result cache TTL in seconds
HIPPODID_AI_API_KEY (none) Your BYOK AI provider key (see BYOK)
HIPPODID_AI_PROVIDER openai AI provider: openai or anthropic
HIPPODID_AI_MODEL gpt-4o-mini Model to use for AI operations
OPENCLAW_WORKSPACE (auto-detect) OpenClaw workspace path (overrides auto-detection)

Claude Desktop

1. Find your config file

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the HippoDid server 

{
  "mcpServers": {
    "hippodid": {
      "command": "/path/to/hippodid-mcp",
      "env": {
        "HIPPODID_MCP_API_KEY": "hd_key_YOUR_KEY_HERE",
        "HIPPODID_MCP_CHARACTER_ID": "00000000-0000-0000-0000-000000000000",
        "HIPPODID_MCP_WATCH_PATHS": "/path/to/your/MEMORY.md",
        "SPRING_DATASOURCE_URL": "jdbc:postgresql://localhost:5432/hippodid",
        "SPRING_DATASOURCE_USERNAME": "hippodid_app",
        "SPRING_DATASOURCE_PASSWORD": "your_password"
      }
    }
  }
}

Replace:

  • /path/to/hippodid-mcp — path to the HippoDid MCP binary or wrapper script
  • hd_key_YOUR_KEY_HERE — your API key from the dashboard
  • 00000000-0000-0000-0000-000000000000 — your character UUID

3. Restart Claude Desktop

Quit and reopen the application.

4. Verify

Ask Claude: “What HippoDid tools do you have?”

You should see 20 tools registered (7 character + 4 memory + 9 file sync).

Cursor

1. Open MCP settings

Go to Settings → MCP → Add MCP Server

2. Add server configuration 

{
  "mcpServers": {
    "hippodid": {
      "command": "/path/to/hippodid-mcp",
      "env": {
        "HIPPODID_MCP_API_KEY": "hd_key_YOUR_KEY_HERE",
        "HIPPODID_MCP_CHARACTER_ID": "00000000-0000-0000-0000-000000000000",
        "SPRING_DATASOURCE_URL": "jdbc:postgresql://localhost:5432/hippodid",
        "SPRING_DATASOURCE_USERNAME": "hippodid_app",
        "SPRING_DATASOURCE_PASSWORD": "your_password"
      }
    }
  }
}

3. Verify

Open the MCP panel in Cursor and confirm hippodid appears with 20 tools listed.

OpenClaw

HippoDid has first-class OpenClaw integration with workspace auto-detection and compaction safety.

1. Configure the server 

{
  "mcpServers": {
    "hippodid": {
      "command": "/path/to/hippodid-mcp",
      "env": {
        "HIPPODID_MCP_API_KEY": "hd_key_YOUR_KEY_HERE",
        "HIPPODID_MCP_CHARACTER_ID": "00000000-0000-0000-0000-000000000000",
        "OPENCLAW_WORKSPACE": "/path/to/your/openclaw-workspace",
        "SPRING_DATASOURCE_URL": "jdbc:postgresql://localhost:5432/hippodid",
        "SPRING_DATASOURCE_USERNAME": "hippodid_app",
        "SPRING_DATASOURCE_PASSWORD": "your_password"
      }
    }
  }
}

2. Workspace auto-detection

If OPENCLAW_WORKSPACE is not set, HippoDid walks up the directory tree looking for a .openclaw marker file. When found, the memory/ subdirectory is automatically registered as a watch path.

3. Compaction safety

HippoDid polls for .openclaw-compaction-pending in the workspace root every 2 seconds. When this file appears, HippoDid triggers an immediate sync and then removes the marker — ensuring no context is lost during compaction.

If your OpenClaw version doesn’t write the .openclaw-compaction-pending marker, use the force_sync tool manually before any compaction operation.

Generic MCP client

For any MCP-compatible client that supports stdio transport:

Command: /path/to/hippodid-mcp

Transport: stdio

Required env vars: See the table at the top of this page.

Example stdio config (Claude-compatible format):

{
  "command": "/path/to/hippodid-mcp",
  "args": [],
  "env": {
    "HIPPODID_MCP_API_KEY": "hd_key_...",
    "HIPPODID_MCP_CHARACTER_ID": "...",
    "SPRING_DATASOURCE_URL": "jdbc:postgresql://localhost:5432/hippodid",
    "SPRING_DATASOURCE_USERNAME": "hippodid_app",
    "SPRING_DATASOURCE_PASSWORD": "..."
  }
}

hippodid init

Bootstrap a new character from an existing project directory:

hippodid-init \
  --api-key hd_key_... \
  --path /path/to/your/project \
  --character-name "My Project Agent"

The init command:

  1. Scans the project directory (build tools, languages, frameworks, dependencies)
  2. Creates a new character with developer category preset
  3. Seeds initial memories from the scan (tech stack, key decisions, project goals)
  4. Optionally imports importable context files (MEMORY.md, CLAUDE.md)

Requires Starter tier or above.

Troubleshooting

“No API key configured” Set HIPPODID_MCP_API_KEY in your MCP client’s environment configuration.

“Import requires Starter tier or above” The import_document MCP tool and import CLI require a paid subscription. Free tier supports file sync only.

“Invalid watch path” Only .md and .txt files, or directories containing such files, within your home directory are permitted. Files larger than 10 MB are rejected.

Background sync not running Ensure HIPPODID_MCP_CHARACTER_ID is set and watch paths are configured. Check stderr logs for [HippoDid] Background sync skipped.

Compaction hook not triggering If OpenClaw doesn’t write .openclaw-compaction-pending, call force_sync manually from your AI agent before compaction.

Tools not appearing Restart your MCP client. If the problem persists, check stderr for [HippoDid] API key validation failed — this means the key is invalid or the API is unreachable.

Copyright © 2024 HippoDid. Distributed under the MIT License.

This site uses Just the Docs, a documentation theme for Jekyll.