Claude Code Setup

This guide covers connecting Claude Code to Hoard for seamless data access.

Quick Setup

1. Ensure Hoard server is running

   hoard serve

2. Run the setup command

   hoard setup --claude

3. Confirm instruction injection

   If setup is running in an interactive project directory, Hoard prompts to update CLAUDE.md.

4. Restart Claude Code

5. Test the connection In Claude Code, ask: “What MCP tools do you have?”

Remote Hoard Server

If Hoard runs on another machine:

hoard setup remote --url https://hoard.example.com --token hoard_sk_... --claude

For project-scope configuration:

hoard setup remote --url https://hoard.example.com --token hoard_sk_... --claude --project-scope

Instruction Injection

Hoard can inject a short guidance block into CLAUDE.md so agents consistently use:

• memory_write for stable facts/preferences
• inbox_put for durable notes/documents
• sync when file changes are not visible yet

Manual control:

hoard instructions --claude --dry-run
hoard instructions --claude --yes

Configuration Modes

Hoard supports two configuration modes for Claude Code:

User Scope (Default)

Recommended for personal use

Writes the token directly to ~/.claude.json:

hoard setup --claude

Generated ~/.claude.json:

{
  "mcpServers": {
    "hoard": {
      "url": "http://127.0.0.1:19850/mcp",
      "headers": {
        "Authorization": "Bearer hoard_sk_544e528b4b1ae6..."
      }
    }
  }
}

Pros: Works immediately, no extra setup Cons: Token in plaintext (but in user config, not committed to git)

Project Scope

For teams sharing configurations

Uses environment variable in project .mcp.json:

hoard setup --claude --project-scope

Generated .mcp.json:

{
  "mcpServers": {
    "hoard": {
      "url": "http://127.0.0.1:19850/mcp",
      "headers": {
        "Authorization": "Bearer ${HOARD_TOKEN}"
      }
    }
  }
}

Caution

Requires additional setup for environment variables.

Required steps:

1. Add to ~/.zshrc or ~/.bashrc:

   export HOARD_TOKEN="hoard_sk_544e528b4b1ae6..."

2. Add .mcp.json to .gitignore
3. Restart terminal and Claude Code

Available Tools

Tool	Description
search	Search indexed content
get	Get full entity content
get_chunk	Get specific chunk
memory_get	Retrieve stored context
memory_put	Store context
memory_search	Search stored memory
memory_write	Store structured memory
inbox_put	Drop a note into the agent inbox
sync	Trigger a sync

Note

inbox_put requires the ingest scope and sync requires the sync scope.

Verifying the Connection

hoard setup --verify

Troubleshooting

”Connection refused” errors

Ensure the Hoard server is running:

hoard serve --status
# If not running:
hoard serve

Tools not appearing

1. Verify config exists: cat ~/.claude.json
2. Check server URL matches: http://127.0.0.1:19850/mcp
3. Restart Claude Code completely

Authentication errors

1. Check token is valid: hoard tokens list
2. Regenerate if needed: hoard tokens add claude-code
3. Re-run setup: hoard setup --claude

Next Steps

• Codex Setup - Configure Codex
• OpenClaw Setup - Configure OpenClaw
• hoard instructions - Instruction injection details