@capitalthought/highfives-mcp

MCP server for High Fives — company directory, peer high fives, and Who's Who face game.

Your agent gets 16 tools to look up teammates, give public recognition, play the Who's Who game, and export or retract their high fives as portable W3C VC credentials — no web UI required.

Install

npm install -g @capitalthought/highfives-mcp

Configure

1. Mint an agent token

Visit https://highfives.app/settings/agent-tokens (or your org's host), create a token, copy the hf_live_... value — you only see it once.

2. Claude Code / Cursor / Windsurf / Zed

Add this to your MCP server config (~/.claude.json, ~/.cursor/mcp.json, etc.):

{
  "mcpServers": {
    "highfives": {
      "command": "highfives-mcp",
      "env": {
        "HIGHFIVES_API_URL": "https://highfives.app",
        "HIGHFIVES_TOKEN": "hf_live_..."
      }
    }
  }
}

Environment variables

| Var | Required | Purpose | |-----|----------|---------| | HIGHFIVES_API_URL | yes | High Fives server URL (e.g. https://highfives.app) | | HIGHFIVES_TOKEN | yes | Bearer token minted at /settings/agent-tokens |

Legacy TEAMBOARD_URL / TEAMBOARD_TOKEN names are still accepted for backward compatibility.

Upgrade from 0.1.x (breaking)

@capitalthought/[email protected] removed the service-role auth path. If you were previously using SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY + HIGHFIVES_ORG_ID, those env vars are ignored now.

Migration: mint an agent token at /settings/agent-tokens, swap your MCP config to use HIGHFIVES_API_URL + HIGHFIVES_TOKEN (see above).

Why the change: service-role keys grant full DB access and have no per-user scoping. Agent tokens are per-user, per-org, optionally read-only, and revokable from the UI.

Tools

| Tool | Purpose | |------|---------| | list_values | List company values. Call before give_high_five. | | list_directory | List active people. Supports department filter + pagination. | | search_people | Fuzzy search by name, email, or title. | | get_person | Full profile for one person by UUID. | | give_high_five | Public recognition for a teammate. Alias: h5. | | ask_whos_who | Start a Who's Who question (photo + 4 choices). | | answer_whos_who | Submit an answer; returns correctness + streak. | | sync_directory | Trigger a Google People API sync. Admin only. | | claim_portable_handle | Reserve a /p/<handle> vanity slug for your portable credentials. | | retract_portable_high_five | Mark a portable high five as retracted; verifiers honor the tombstone. | | export_my_data | Download every high five you gave or received as signed W3C VC JSON. | | list_contests / get_contest / log_match / log_score / dispute_match | Contest ladder tracker (ping pong, Mario Kart, Tetris high scores, etc.). |

All tools return structured errors:

{
  "error": "value_not_found",
  "suggestion": "Call list_values to get the exact list of slugs for this org.",
  "details": { "available_slugs": ["excellence", "bias-for-action", "..."] }
}

Example prompts

Once installed, try these prompts with your agent:

• "List everyone in the Engineering department."
• "Give a high five to [email protected] for embodying 'Excellence' with the message 'Crushed the Q3 review.'"
• "Who does Sarah Lee report to?"
• "Play a round of Who's Who."

Development

# From packages/highfives-mcp/
npm install
npm run build       # tsc -> dist/
npm start           # run the built server on stdio

# Dev loop (watches + rebuilds)
npm run dev

Test it by setting env vars and piping a JSON-RPC tools/list request:

HIGHFIVES_API_URL=https://highfives.app HIGHFIVES_TOKEN=hf_live_... \
  node dist/index.js

Security

• Every request goes over HTTPS with a Bearer token — no service-role key leaves your config.
• Tokens are revocable from the web UI at any time.
• Read-only tokens are supported: scope is enforced server-side on every write.
• give_high_five refuses self-high-fives and validates value / recipient against your org only.
• ask_whos_who / answer_whos_who never reveal the correct answer to the client — it's held in pending_questions with a 5-minute TTL.
• sync_directory is admin-only and rate-limited (1/hr per org).

License

MIT © Capital Thought