Connect an AI agent

pink-lemonade has no built-in chatbot. It hosts a local MCP server; you point your own AI agent at it from a terminal. The agent searches the open case, correlates activity, reads cached intel, and records findings — which land in Case mode for your review.

  • Everything happens beside the app: keep it open with a workspace focused while the agent works.
  • Claude Code is the documented, tested client. Any MCP client that supports a local HTTP endpoint with a custom Authorization header can connect — open MCP in the header for the URL and token; approval controls vary by client.

Evidence rules the agent can’t skip

  • record_event validates cited rows — evidence that matches nothing is refused. Each accepted citation stores a quoted line captured by the app, not a paraphrase.
  • record_negative runs the search itself and refuses to record an “absence” if anything matches, naming the term that hit.
  • query_sql accepts one read-only SELECT — writes, ATTACH, PRAGMA are rejected — and every query is logged into the case.
  • Log data is untrusted input: invisible/direction-flipping characters are made visible, and instruction-like text inside evidence is treated as evidence, never as a command.

Claude Code setup

Prereq: Claude Code installed and signed in. No Anthropic API key, no bundled binary. The server starts with the app — the MCP button’s dot shows 🟢 running / 🟡 starting / 🔴 error.

Register once, work from any folder:

  1. Click MCP in the header → copy the one-time command:

    claude mcp add --transport http pinklemonade http://127.0.0.1:8765/mcp \
  --header "Authorization: Bearer <your token>" --scope user
  2. Run it in any terminal. User scope = the tools load in every session, no per-folder files, no trust prompt.
  3. From then on: cd ~/cases/acme-ir && claude. The agent drives whichever workspace is focused in the app.

Check or undo with claude mcp list / claude mcp remove pinklemonade.

Want the agent to import evidence itself? Set the Evidence folder in Settings → Storage first — it’s the only folder the agent may read files from. Unset = it can only use what you’ve imported.

Alternative — a self-contained case folder. The MCP dialog’s second option writes a dedicated folder with .mcp.json (URL + token), CLAUDE.md (the investigation methodology), pre-approved tool settings, and a .gitignore. Run claude from that folder. It’s project-scoped, so Claude Code asks you to trust it once.

The token. The server binds to 127.0.0.1 only, port fixed at 8765; every request needs the bearer token (generated on first run, stored locally, never in source). It stops other local programs from driving the app — tool approvals are your MCP client’s job.

What the agent can do

  • Orient — list sources and host groups, describe columns, list evidence-folder files, list other cases.
  • Search — one source or all at once (whole-token for IPs/hashes, substring for domains), structured filters, distinct values, group-and-count, read-only SQL.
  • Correlate in time — rows within ±N seconds of a timestamp, across sources.
  • Record — events, IOCs, leads, proven absences, entities and links; mark cited rows.
  • Manage — create/open a case, import evidence, tag rows, assign hosts, maintain the plan and progress note.
  • Read cached intel for free — it never spends fresh VirusTotal/MaxMind lookups. That’s your call.

Left for your approval in the terminal: import_evidence, tag_rows, set_source_group. Everything else is pre-approved in the generated settings; recording actions are reversible and reviewable in Case. The agent can never mark an entity Cleared or approve/reject a finding — analyst only.

The Case workflow

Agent output lands in Case mode (the badge counts pending review). Work it in order:

  1. Overview — case activity and status.
  2. Queue — approve or reject findings.
  3. Findings — Graph / Time axis / Table / IOC views over recorded events; Table exports l2t_csv-style.
  4. Report — assemble and export the deliverable.

Investigation, Systems & Accounts, and IOCs hold the plan, subjects, and indicator catalog.

Terms: Evidence = cited source rows · Finding = a recorded event, lead, absence, or entity assessment · Queue = the review line · ✨ marks = rows the agent flagged, filterable in the grid.

Queue

  • Pending first, grouped by host. Approve (✓) or Reject (✗) — rejection requires a reason, kept and shown back to the agent. Nothing is deleted; anything can go back to pending.
  • Amber flags call out what to read first: overturned, caveat, stale, single-source, not-collected.
  • Each finding shows its quoted evidence rows; the telescope jumps to where the evidence lives.
  • Reviewed items hide by default (show reviewed). Approve N batch-approves a host’s pending items after a confirm.

Systems & Accounts

  • Machines and accounts in the case, from host groups and recorded events. Set status (Compromised / Suspected / Cleared / Unknown — Cleared is analyst-only), role, notes.
  • A banner lists named systems with no collected data — you can’t pivot into what was never imported.
  • Accounts never merge across domains: EXAMPLE\admin ≠ OTHER\admin. Lookalikes are only suggested; merges must be confirmed.

IOC catalog

Indicators the agent cataloged, by type. Cataloging never sends anything anywhere — pushing to the Intel grid is your action.

Report

  • Approved findings flow in. Edit metadata and narrative sections (double-click / pencil; Ctrl+Enter saves, Escape cancels); unsaved drafts are marked and guarded on close.
  • Comments attach to sections, resolve/delete as addressed; they stay out of the export.
  • Export as Markdown. Drafts can include unreviewed findings — labeled as such.

Report checks, measured from the case itself:

  • Coverage — every source and host examined.
  • Review — nothing pending, no unanswered rejection (hiding a finding doesn’t help).
  • Evidence — every included finding cites rows.
  • Verification — see below; an unresolved refutation blocks Ready.

Export is never blocked — a draft that fails checks just confirms first and carries a draft warning.

Independent verification

On request, a separate reviewer re-checks each finding from its cited rows and quotes, without the original explanation, recording supports / refutes / cannot-verify with a reason. Asymmetric on purpose: one refutation marks it refuted no matter the supporting votes. Verification sits beside your approve/reject; it never replaces it.

Proven absences

The agent records “didn’t happen” as negatives with their scope stored — sources, terms, time window — so they can be re-run, not taken on faith. A separate evidence gap records a limitation (unparsed artifact, failed parser) and can’t be machine-re-checked.

Negatives appear in Report with a Negative badge and their scope line. Flags:

  • stale — a source arrived after the absence was established; unverified against the current case, not wrong.
  • overturned — a re-check found rows; kept and flagged, because those rows are the finding.

Read the scope line before treating not present as did not happen.

MITRE ATT&CK

Technique ids resolve against the official catalog baked in at build time — no network, nothing to configure. Retired ids upgrade automatically; unknown ids are kept but marked (unverified) instead of silently trusted. Hand-typed techniques go through the same resolution.

ATT&CK data © MITRE, CC BY 4.0 — attribute MITRE ATT&CK in published reports.

Where your data goes

  • The agent’s MCP client sends what it reads (rows, columns, cached intel) to that client’s model provider, under your account and terms. pink-lemonade never sends case data anywhere on its own.
  • No pink-lemonade account or server. MCP binds to 127.0.0.1; workspaces, tags, sightings, watchlists, and the intel cache are local files. Online enrichment providers see indicators only when you start a lookup.

Next

→ Workspaces · Exploring data · Intel & watchlists