clue-tools-mcp

The Clue.tools MCP server — a team AI activity logger for Claude Code. It captures session metadata only and ships it to your team's Clue.tools dashboard. It never captures, stores, or transmits raw prompt or response text.

This is Phase 2A of the Clue.tools platform. It feeds the shared backend's POST /api/ingest endpoint built in Phase 1 (apps/web).

What it captures

Metadata only:

• timestamps (session start/end, duration)
• tool names used (e.g. Read, Edit, Bash) — names only
• file paths touched — paths only, never file contents
• token counts and conversation turn counts (when the host exposes them)
• a short, locally-generated, redacted activity summary (raw_context)

It never captures: prompt text, response text, file contents, clipboard, or anything resembling conversation content. There is no code path that accepts such data — privacy is structural, not just policy.

Install & connect

npx clue-tools-mcp init --team-key <your-team-key> --name "Your Name"

init will:

1. Validate the team key against the Clue.tools API.
2. Store credentials in ~/.clue/credentials.json (mode 0600) — never in your project directory.
3. Write default privacy settings to ~/.clue/config.json if absent.
4. Register the server in your Claude Code config (~/.claude.json) so future sessions load it automatically.

Then restart Claude Code.

Flags:

| Flag | Purpose | |---|---| | --team-key <key> | Your team key (prompted if omitted). | | --name <name> | Your display name (prompted if omitted). | | --api-base <url> | API base URL. Default https://clue.tools. | | --mcp-config <path> | Host config file to patch. Default ~/.claude.json. Use for Claude Desktop or project-scope .mcp.json. | | --print-only | Print the config snippet instead of writing it. | | --skip-validation | Skip the team-key API check (offline setup). |

Check status any time:

npx clue-tools-mcp status

How it works

MCP servers can only observe calls to their own tools, not the host's calls to Read/Write/Bash. So this server exposes tools the host invokes to report activity:

| Tool | Purpose | |---|---| | clue_record_activity | Log a metadata-only event (tool name, file paths, turn/token counts, short note). | | clue_flush_session | End the current session and ship its summary now. | | clue_status | Report connection health and pending-upload count. |

A session also auto-flushes after 10 minutes of inactivity (the spec's idle end trigger) and on process shutdown (SIGINT/SIGTERM). Payloads are written to a durable on-disk queue (~/.clue/queue.json) and retried with exponential backoff, so nothing is lost during a network outage; the queue is drained on the next startup.

Privacy configuration — ~/.clue/config.json

{
  "redact_conversation_content": true,
  "send_file_names_only": true,
  "send_tool_calls": true,
  "opt_out_days": [],
  "api_endpoint": "https://clue.tools/api/ingest"
}

• redact_conversation_content (default true) — raw prompt text is never shipped regardless; this flag is for transparency.
• send_file_names_only (default true) — set false to omit files_touched entirely. (There is no "contents" mode; the only alternative is omission.)
• send_tool_calls (default true) — set false to omit tool_calls.
• opt_out_days — list of YYYY-MM-DD dates or weekday names (e.g. "Saturday") on which all tracking is suppressed.

A malformed config falls back to the strict defaults — it can never silently weaken privacy.

Environment variables

init writes these into the Claude Code MCP entry; you can also set them manually:

CLUE_TEAM_KEY=        # your team key (secret)
CLUE_MEMBER_NAME=     # your display name
CLUE_API_ENDPOINT=    # full ingest URL, e.g. https://clue.tools/api/ingest

Environment variables take precedence over ~/.clue/credentials.json.

Development

npm install            # from repo root (workspaces)
npm run build --workspace=clue-tools-mcp
npm run typecheck --workspace=clue-tools-mcp
npm run test --workspace=clue-tools-mcp

Ingest contract (must stay in sync with apps/web)

POST /api/ingest with headers x-team-key and x-member-id, body:

{
  "source": "mcp",
  "tool": "claude-code",
  "started_at": "2026-06-25T09:00:00Z",
  "ended_at": "2026-06-25T10:30:00Z",
  "duration_mins": 90,
  "model": "claude-sonnet-4-6",
  "input_tokens": 14200,
  "output_tokens": 8100,
  "turns": 34,
  "tool_calls": ["Read", "Edit", "Bash"],
  "files_touched": ["src/api/routes.ts"],
  "raw_context": "compressed activity summary…"
}

The endpoint uses a strict schema: it rejects unknown keys and any field that looks like conversation content. This package emits exactly these keys and nothing else.