advocatehub-mcp

A Model Context Protocol server for Influitive AdvocateHub, built entirely on the public Influitive REST API (api.influitive.com / api.influitives.com in staging). This is Phase 1: no hub source changes, no internal endpoints — everything here is something any AdvocateHub customer could build against their own API token.

What it does

15 tools across members, groups, challenges, events, rewards, and approvals — 9 read-only, 6 write (all confirm-gated and audit-logged). See docs/tool-reference.md for the full list, endpoints, and known API gaps.

Status

• P1a (stdio, for Claude Desktop/Code): done. See docs/setup-claude.md.
• P1b (streamable HTTP, for ChatGPT / remote clients): done, needs a staging smoke pass. See docs/setup-chatgpt.md.
• Target environment so far: staging (https://api.influitives.com). Production support is a config change (INFLUITIVE_BASE_URL / the setup prompt), not a code change — re-run the staging smoke checklist against production before trusting it there.

Quick start (Claude Desktop / Code, stdio)

npm install
npm run build
npm run setup     # one-time: stores your API token + org id in the OS keychain
npm run start      # or point Claude Desktop's config at dist/index.js — see docs/setup-claude.md

Quick start (hosted HTTP, e.g. ChatGPT)

npm install
npm run build
npm run setup                 # once per tenant
export MCP_HTTP_BEARER_MAP="some-long-random-string:<orgId>"
npm run start:http            # listens on PORT (default 8787), serves POST/GET/DELETE /mcp

See docs/setup-chatgpt.md for the full connector setup and the two-credential auth model (MCP bearer vs. Influitive API token).

Development

npm run dev            # tsx watch, stdio
npm run dev:http       # tsx watch, streamable HTTP
npm test               # unit tests (mocked fetch, no network)
npm run test:integration  # opt-in, hits real staging — see .env.example
npm run lint
npm run typecheck

Repo layout

bin/setup.ts          interactive credential setup CLI
src/
  index.ts            stdio entrypoint (P1a)
  http.ts             streamable HTTP entrypoint (P1b)
  server.ts           builds the McpServer and registers all tools
  config/             credentials: types, keychain/file store, env-var loader, HTTP bearer resolution
  client/             InfluitiveClient: auth headers, retries, cursor pagination, rate limiting
  errors/             typed error classes + HTTP status -> error mapping
  registry/           local per-tenant index of challenges this server has created
  audit/              append-only JSONL write audit log
  tools/               the 15 tools, grouped by resource, plus shared confirm-gate/formatting helpers
test/
  unit/               fast tests, fetch mocked, no network
  integration/        opt-in, mutates a real (disposable) staging tenant
docs/                  setup guides + tool reference

Design notes worth knowing before you touch this

• Write safety: every write tool takes a confirm flag. confirm:false (or omitted) only previews — it never calls the API. confirm:true executes and always appends exactly one entry to the per-tenant audit log (~/.advocatehub-mcp/audit/<orgId>.jsonl), whether it succeeded or failed. See src/tools/shared/confirmGate.ts.
• No raw exceptions cross the MCP boundary. Every tool handler is wrapped so typed errors (AuthError, NotFoundError, ...) come back as { isError: true } text, never an unhandled throw. See src/tools/shared/formatters.ts.
• The public API has no "list challenges" endpoint. ChallengeRegistry (src/registry/challengeRegistry.ts) is a local, best-effort index of challenges this server created — it does not know about challenges created any other way, and is lost if ~/.advocatehub-mcp is wiped.
• contacts_api_search is a per-tenant Labs flag. If it's off, /contacts silently ignores filters instead of erroring. search_members refuses filtered queries once it knows the flag is off (config.contactsSearchEnabled === false), and self-heals that cache the first time it sees evidence either way. See src/tools/members.ts.
• Locking a member is seat reclaim, per current product policy: it blocks login and excludes the member from advocate counts, targeting, and the billable seat count. deactivate_member/reactivate_member describe this explicitly in their tool descriptions so an LLM doesn't undersell what the action does.