MCP Setup

Configure HippoDid as an MCP server in your AI client.

Table of contents

Overview
1. Available tools (21)
Quick start (hosted mode)
Prerequisites
1. Hosted mode
2. Local mode (advanced)
Install local JAR
1. Verify your API key
2. Environment variables
Claude Code
Claude Desktop
Cursor
1. Option A: Hosted (recommended)
2. Option B: Local JAR
Gemini CLI
Codex CLI
ChatGPT
1. Setup
2. Verify
3. How it works
4. Limitations
OpenClaw
Generic MCP client
Project bootstrapping
Troubleshooting

Overview

HippoDid provides two modes for connecting your AI client:

Hosted mode (recommended) — connect directly to https://api.hippodid.com/mcp over HTTP. No download, no Java required.
Local mode — run the MCP server JAR on your machine via stdio. Required for file watching, background sync, and OpenClaw integration.

Available tools (21)

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 (10): 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

Hosted mode exposes 19 of the 21 tools. The filesystem-only tools (add_watch_path, list_watch_paths, force_sync) require local mode.

Quick start (hosted mode)

The fastest path to HippoDid in any AI client — no Java required.

Get your API key from the dashboard → Settings → API Keys
Pick your client below and paste in the hosted config
Restart your client and ask: “What HippoDid tools do you have?”

That’s it. No download, no JAR, no environment variables beyond your API key.

Prerequisites

Hosted mode

A HippoDid API key (hd_sk_...) from the dashboard

Local mode (advanced)

Java 21 runtime
A HippoDid API key (hd_sk_...) from the dashboard

Install local JAR

Skip this section if you’re using hosted mode. The local JAR is only needed for file watching, background sync, or OpenClaw integration.

Download the latest JAR from GitHub Releases:

# macOS / Linux
curl -L -o hippodid-mcp-server.jar \
  https://github.com/SameThoughts/hippodid-mcp-server/releases/latest/download/hippodid-mcp-server-1.1.0.jar

Or build from source:

git clone https://github.com/SameThoughts/hippodid-mcp-server.git
cd hippodid-mcp-server
mvn clean package -DskipTests
# JAR is at target/hippodid-mcp-server-1.1.0.jar

Move the JAR somewhere permanent and note the absolute path — you’ll need it in the configs below. Tilde (~) does not expand inside JSON, so always use the full path (e.g. /Users/yourname/hippodid-mcp-server.jar).

Verify your API key

Before configuring any MCP client, confirm your API key works:

curl -H "Authorization: Bearer hd_sk_YOUR_KEY_HERE" \
  https://api.hippodid.com/v1/tier

You should see a JSON response with your tier info (e.g. {"tier":"STARTER"}). If you get a 401, your key may be invalid, revoked, or expired — generate a new one from the dashboard.

Environment variables

Variable	Default	Description
`HIPPODID_API_KEY`	(required)	Your HippoDid API key (`hd_sk_...`)
`HIPPODID_MCP_CHARACTER_ID`	(none)	Target character UUID for background file sync. Only required when `HIPPODID_MCP_WATCH_PATHS` is set.
`HIPPODID_MCP_WATCH_PATHS`	(none)	Comma-separated local file paths to watch and auto-sync. Requires `HIPPODID_MCP_CHARACTER_ID` to be set.
`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 Code

Option A: Hosted (recommended)

Claude Code natively supports HTTP transport — no proxy needed.

Create or update .mcp.json in your project root:

{
  "mcpServers": {
    "hippodid": {
      "type": "http",
      "url": "https://api.hippodid.com/mcp",
      "headers": {
        "Authorization": "Bearer hd_sk_YOUR_KEY_HERE"
      }
    }
  }
}

Replace hd_sk_YOUR_KEY_HERE with your API key from the dashboard. Your API key authenticates at the account level — no character ID needed. You select which character to use per tool call (e.g. when calling search_memories or add_memory).

Add .mcp.json to .gitignore since it contains your API key:

echo '.mcp.json' >> .gitignore

Restart Claude Code. Run /mcp to verify hippodid appears with 19 tools.

Alternatively, use the CLI:

claude mcp add --transport http --scope user hippodid \
  https://api.hippodid.com/mcp \
  --header "Authorization: Bearer hd_sk_YOUR_KEY_HERE"

Option B: Local JAR (advanced / file watching)

Use this if you need background file sync, watch paths, or OpenClaw integration.

Project-level .mcp.json is recommended over the global ~/.claude/mcp.json. The global config may not be loaded reliably in all Claude Code versions.

{
  "mcpServers": {
    "hippodid": {
      "type": "stdio",
      "command": "java",
      "args": ["-jar", "/absolute/path/to/hippodid-mcp-server.jar"],
      "env": {
        "HIPPODID_API_KEY": "hd_sk_YOUR_KEY_HERE"
      }
    }
  }
}

Optional — only needed for background file sync:

{
  "mcpServers": {
    "hippodid": {
      "type": "stdio",
      "command": "java",
      "args": ["-jar", "/absolute/path/to/hippodid-mcp-server.jar"],
      "env": {
        "HIPPODID_API_KEY": "hd_sk_YOUR_KEY_HERE",
        "HIPPODID_MCP_CHARACTER_ID": "00000000-0000-0000-0000-000000000000",
        "HIPPODID_MCP_WATCH_PATHS": "/path/to/your/project/CLAUDE.md,/path/to/your/project/MEMORY.md"
      }
    }
  }
}

HIPPODID_MCP_CHARACTER_ID is only required when using watch paths — it tells the background sync daemon which character to push file changes to. Without watch paths, the API key alone is sufficient.

If java is not on your PATH, use the full path to your Java 21 binary (e.g. /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home/bin/java). You can find it with which java or /usr/libexec/java_home -v 21.

Restart and verify

Quit and reopen Claude Code in your project directory. Ask Claude Code: “What HippoDid tools do you have?”

You should see 19 tools (hosted) or 21 tools (local JAR) listed. You can also run /mcp to check the server status.

Claude Desktop

1. Find your config file

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

Option A: Hosted (recommended)

Requires Node.js (for npx). Uses mcp-remote to connect Claude Desktop to the hosted endpoint.

{
  "mcpServers": {
    "hippodid": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.hippodid.com/mcp",
        "--transport",
        "http-first",
        "--header",
        "Authorization:Bearer hd_sk_YOUR_KEY_HERE"
      ],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Replace hd_sk_YOUR_KEY_HERE with your API key from the dashboard. Your API key authenticates at the account level — no character ID needed here. You select which character to use per tool call (e.g. when calling search_memories or add_memory).

Tip (macOS with Homebrew): If npx is not found, use the full path. Run which npx in your terminal to find it, then replace "npx" with the full path (e.g. /opt/homebrew/bin/npx or /Users/yourname/homebrew/bin/npx). Also update the PATH env to match your Homebrew prefix.

Option B: Local JAR (advanced / file watching)

Use this if you need background file sync or watch paths.

{
  "mcpServers": {
    "hippodid": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/hippodid-mcp-server.jar"],
      "env": {
        "HIPPODID_API_KEY": "hd_sk_YOUR_KEY_HERE"
      }
    }
  }
}

Optional — only needed for background file sync:

{
  "mcpServers": {
    "hippodid": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/hippodid-mcp-server.jar"],
      "env": {
        "HIPPODID_API_KEY": "hd_sk_YOUR_KEY_HERE",
        "HIPPODID_MCP_CHARACTER_ID": "00000000-0000-0000-0000-000000000000",
        "HIPPODID_MCP_WATCH_PATHS": "/path/to/your/project/CLAUDE.md"
      }
    }
  }
}

Restart and verify

Quit and reopen Claude Desktop. Ask Claude: “What HippoDid tools do you have?”

You should see 19 tools (hosted) or 21 tools (local JAR) listed.

Cursor

Option A: Hosted (recommended)

Cursor does not yet support HTTP MCP transport in its Settings UI. Use the local JAR config below, or add the server manually via ~/.cursor/mcp.json with the same format as Claude Code’s .mcp.json hosted config. (Update this note once Cursor adds native HTTP MCP support.)

Option B: Local JAR

Go to Settings → MCP → Add MCP Server
Add server configuration:

{
  "mcpServers": {
    "hippodid": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/hippodid-mcp-server.jar"],
      "env": {
        "HIPPODID_API_KEY": "hd_sk_YOUR_KEY_HERE",
        "HIPPODID_MCP_CHARACTER_ID": "00000000-0000-0000-0000-000000000000",
        "HIPPODID_MCP_WATCH_PATHS": "/path/to/your/project/CLAUDE.md"
      }
    }
  }
}

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

Gemini CLI

1. Find your config file

macOS / Linux: ~/.gemini/settings.json
Windows: %USERPROFILE%\.gemini\settings.json

Create the file if it doesn’t exist yet.

Option A: Hosted (recommended)

Add the mcpServers block to your settings.json:

{
  "mcpServers": {
    "hippodid": {
      "url": "https://api.hippodid.com/mcp",
      "headers": {
        "Authorization": "Bearer hd_sk_YOUR_KEY_HERE"
      }
    }
  }
}

Use the url key (not httpUrl). This tells the Gemini CLI to connect to the remote MCP server over HTTP. If your settings.json already has other keys, merge the mcpServers block into the existing file rather than overwriting it.

Option B: Local JAR (advanced / file watching)

Use this if you need background file sync, watch paths, or OpenClaw integration.

{
  "mcpServers": {
    "hippodid": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/hippodid-mcp-server.jar"],
      "env": {
        "HIPPODID_API_KEY": "hd_sk_YOUR_KEY_HERE"
      }
    }
  }
}

Optional — only needed for background file sync:

{
  "mcpServers": {
    "hippodid": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/hippodid-mcp-server.jar"],
      "env": {
        "HIPPODID_API_KEY": "hd_sk_YOUR_KEY_HERE",
        "HIPPODID_MCP_CHARACTER_ID": "00000000-0000-0000-0000-000000000000",
        "HIPPODID_MCP_WATCH_PATHS": "/path/to/your/project/GEMINI.md"
      }
    }
  }
}

Restart and verify

Restart the Gemini CLI and run:

/mcp

You should see hippodid listed as a connected server with 19 tools (hosted) or 21 tools (local JAR). You can also ask Gemini: “What HippoDid tools do you have?”

Codex CLI

OpenAI’s Codex CLI natively supports Streamable HTTP MCP servers with bearer token authentication. The config uses TOML format.

1. Find your config file

macOS / Linux: ~/.codex/config.toml
Windows: %USERPROFILE%\.codex\config.toml

Create the file if it doesn’t exist yet. The Codex CLI and IDE extension share this config.

Option A: Hosted (recommended)

Add the following to your config.toml:

[mcp_servers.hippodid]
url = "https://api.hippodid.com/mcp"
bearer_token_env_var = "HIPPODID_API_KEY"
startup_timeout_sec = 20
tool_timeout_sec = 120

Then set the environment variable in your shell profile (~/.zshrc, ~/.bashrc, or equivalent):

export HIPPODID_API_KEY="hd_sk_YOUR_KEY_HERE"

Replace hd_sk_YOUR_KEY_HERE with your API key from the dashboard. Codex reads the env var name from bearer_token_env_var and sends it as a Bearer token automatically — your key is never stored in the TOML file.

Tip: Codex supports enabled_tools and disabled_tools to control which tools are available. If you want to start with read-only access, add this to the [mcp_servers.hippodid] block:

enabled_tools = ["list_characters", "get_character", "search_memories", "get_character_stats"]

You can expand the allow-list as needed. Omit enabled_tools to expose all 19 hosted tools.

Option B: Local JAR (advanced / file watching)

Use this if you need background file sync, watch paths, or OpenClaw integration.

[mcp_servers.hippodid]
command = "java"
args = ["-jar", "/absolute/path/to/hippodid-mcp-server.jar"]

[mcp_servers.hippodid.env]
HIPPODID_API_KEY = "hd_sk_YOUR_KEY_HERE"

Optional — only needed for background file sync:

[mcp_servers.hippodid]
command = "java"
args = ["-jar", "/absolute/path/to/hippodid-mcp-server.jar"]

[mcp_servers.hippodid.env]
HIPPODID_API_KEY = "hd_sk_YOUR_KEY_HERE"
HIPPODID_MCP_CHARACTER_ID = "00000000-0000-0000-0000-000000000000"
HIPPODID_MCP_WATCH_PATHS = "/path/to/your/project/AGENTS.md"

Restart and verify

Restart Codex CLI. Run /mcp in the Codex TUI to see hippodid listed with 19 tools (hosted) or 21 tools (local JAR). You can also run codex mcp --help to manage MCP servers from the command line.

ChatGPT

ChatGPT connects to HippoDid via OAuth 2.1 with PKCE. The authorization flow is fully automatic — ChatGPT discovers the OAuth server, registers itself, and handles the token exchange. You just need to authorize the connection once.

Requirements: ChatGPT Business, Enterprise, or Edu plan with developer mode enabled. ChatGPT Plus and Pro do not currently support custom MCP apps.

Setup

Open ChatGPT on the web (desktop app does not support initial app setup)
Go to Settings → Apps → Create (or Settings → Connectors → Add custom connector)
Enter the MCP server URL:
```
https://api.hippodid.com/mcp
```
ChatGPT automatically discovers the OAuth configuration:
- Fetches https://api.hippodid.com/.well-known/oauth-protected-resource
- Finds the authorization server (Clerk)
- Registers itself via Dynamic Client Registration
- Requests the profile and email scopes
You are redirected to Clerk’s consent screen — sign in with your HippoDid account and authorize access
After authorization, ChatGPT attaches the Bearer token to all MCP tool calls

Verify

After setup, ask ChatGPT: “What HippoDid tools do you have?”

You should see 19 tools listed. You can also check the Apps panel in ChatGPT settings to confirm hippodid appears as a connected app.

How it works

The OAuth 2.1 flow is fully automatic:

ChatGPT → GET /.well-known/oauth-protected-resource (discovers Clerk)
        → GET clerk.hippodid.com/.well-known/oauth-authorization-server
        → POST clerk.hippodid.com/oauth/register (Dynamic Client Registration)
        → Redirect user to Clerk consent screen
        → POST token exchange (Authorization Code + PKCE)
        → POST /mcp (with Bearer token on every tool call)

Your existing HippoDid account and organization membership carry over — no separate API key needed. The OAuth token automatically identifies your organization and user permissions.

Limitations

Setup must be done on the web — mobile ChatGPT can use an app after it has been linked on web
Organization context required — you must belong to a HippoDid organization. Personal (non-org) accounts are not supported for MCP access
Company Knowledge mode — if your ChatGPT workspace uses Company Knowledge, it supports read/search tools only (no writes)

OpenClaw

Tip: If you don’t need file watching or local JAR mode, the OpenClaw Plugin is the simpler setup — install one npm package, set your API key, done. No Java required.

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

1. Configure the server

{
  "mcpServers": {
    "hippodid": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/hippodid-mcp-server.jar"],
      "env": {
        "HIPPODID_API_KEY": "hd_sk_YOUR_KEY_HERE",
        "HIPPODID_MCP_CHARACTER_ID": "00000000-0000-0000-0000-000000000000",
        "OPENCLAW_WORKSPACE": "/path/to/your/openclaw-workspace"
      }
    }
  }
}

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 — including daily log files (memory/YYYY-MM-DD.md).

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, use stdio transport with the local JAR:

{
  "command": "java",
  "args": ["-jar", "/absolute/path/to/hippodid-mcp-server.jar"],
  "env": {
    "HIPPODID_API_KEY": "hd_sk_YOUR_KEY_HERE",
    "HIPPODID_MCP_CHARACTER_ID": "...",
    "HIPPODID_MCP_WATCH_PATHS": "/path/to/CLAUDE.md,/path/to/MEMORY.md"
  }
}

Or for HTTP transport (if your client supports it):

Endpoint: https://api.hippodid.com/mcp
Header:   Authorization: Bearer hd_sk_YOUR_KEY_HERE

Project bootstrapping

A hippodid init CLI command is planned that will scan a project directory, create a character, and seed initial memories from your project context. For now, create characters via the dashboard or the create_character MCP tool, and use import_document to import existing context files.

Troubleshooting

“No API key configured” Ensure HIPPODID_API_KEY is set in your MCP server env config.

“Import requires Starter tier or above” The import_document MCP tool requires a paid subscription. Free tier supports manual sync_file 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 Verify HIPPODID_MCP_CHARACTER_ID is set and watch paths are configured. Check stderr logs for [HippoDid] Background sync skipped.

Compaction hook not triggering Ensure OpenClaw workspace is detected. 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 that your API key is valid by running the curl test above.