prospector/docs/features/mcp.md

Prospector MCP — agent interface for the new backend

Installation (Claude Desktop + global claude CLI)

From the prospector checkout:

cd /path/to/@applications/@prospector
./run install:mcp

• This builds @packages/mcp-prospector, then merges a prospector entry into:
  • ~/Library/Application Support/Claude/claude_desktop_config.json (Claude Desktop)
  • ~/.claude/mcp-config.json (global claude / Claude Code CLI)
• It coexists with the legacy quinn-prospector (use name "prospector" for the new one).
• Safety: the script prefers a full quit of Claude Desktop before writing (Desktop clobbers the file on exit). Use SKIP_QUIT=1 NO_RELAUNCH=1 ./run install:mcp in automated contexts.
• Secrets: sources .env.local (dev) or ~/.vault/prospector.env (real tokens). See the script for VENV=... override.
• After install, (re)launch Claude Desktop or your claude session. The tools (prospector_submit_inbound, prospector_classify, prospector_activity, ... prospector_correction) become available.

Manual alternative: copy the snippets in mcp/*.snippet.json into the right file while the target app is fully quit.

Purpose

The MCP server lets an agent coworker (Claude cowork / the inbound-outbound operator) drive the new prospector backend, so it can switch off its legacy lilith cockpit_* tools and trial the new service — and fall back gracefully while vetting it.

It is a thin adapter: every tool is one HTTP call to the prospector service REST API. No business logic lives in the MCP — the backend owns classification, the Gate-2 safety holds, the kill-switch, dispatch, and the audit trail. This keeps the agent loosely coupled (it never talks to the DB or macsync directly).

coworker agent ──(MCP stdio)──▶ prospector-mcp ──(HTTP + service token)──▶ prospector service ──▶ people / macsync / mr-number

Tools

Tool	Maps to	What it does
prospector_submit_inbound(handle, text, channel?, hasCallSignal?)	POST /internal/inbound	Run one inbound through the whole pipeline (classify → Gate-2 safety + vendor/known/human floors → booking extract → MR auto-request on rate → mode → dispatch/hold). Returns {outcome, holdReason, outboxId, booking, qualified, takeoverReady}. Replaces the legacy stream→classify→draft→send sequence — the backend decides and sends.
prospector_classify(text, handle?, ...)	POST /prospector/classify	Structured raw-text classify + composition (gap #1,4,13). Returns {category, template, confidence, escalate, booking, takeoverReady, qualified, mrVerdict} — no blob parsing. Full signals/mr when handle given.
prospector_activity(limit?)	GET /prospector/activity	Recent decisions (sends + holds w/ reasons) — the audit feed for vetting.
prospector_held_queue(limit?)	GET /prospector/held-queue	Candidates held for human review (Gate-2 holds, paused, no-template).
prospector_digest(sinceHours?)	GET /prospector/digest	Sent/held/error counts + Mac-reachable health + sent bodies.
prospector_get_mode()	GET /prospector/settings	Current settings incl. the GO/PAUSE/AWAY kill-switch.
prospector_set_mode(mode)	PUT /prospector/settings	Flip the kill-switch (PAUSE = draft-only; GO/AWAY = auto-send allowed).
prospector_correction(...)	POST /prospector/corrections	Record teach-loop correction (vetting + OSS tuning data).

Configuration

Env (the MCP is a stdio process the agent launches):

• PROSPECTOR_BASE_URL — default http://127.0.0.1:3210
• PROSPECTOR_SERVICE_TOKEN — bearer for the guarded API

Register in the agent's .mcp.json alongside (not replacing) the legacy quinn-prospector server:

{
  "mcpServers": {
    "prospector": { "command": "node", "args": ["<path>/mcp/dist/index.js"],
      "env": { "PROSPECTOR_BASE_URL": "http://127.0.0.1:3210", "PROSPECTOR_SERVICE_TOKEN": "…" } }
    // "quinn-prospector": { … }   ← keep during the trial for fallback
  }
}

How the coworker switches (graceful trial)

The legacy flow was: cockpit_stream → cockpit_classify / classify_message → mr_number_* → cockpit_draft → cockpit_send → cockpit_correction / cockpit_mark_worked.

With the new backend that whole sequence collapses into one call — prospector_submit_inbound — because the service runs classify + Gate-2 + screening rule + dispatch internally and records the result. The coworker's trial protocol:

1. Both servers registered. Keep quinn-prospector (legacy) available.
2. Route new inbounds through prospector_submit_inbound. Read back the decision; if it errors or the outcome looks wrong, fall back to the legacy cockpit_* flow for that message.
3. Vet, don't trust blindly. Periodically prospector_activity / prospector_held_queue / prospector_digest to confirm the backend's holds and sends match what the coworker would have done. Disagreements are the vetting signal.
4. Safety is server-side. Even mid-trial, Gate-2 + the PAUSE default protect every send — a coworker mistake can't bypass them.

What this is NOT

• Not a second copy of the engine — it calls the service.
• Not the operator UI — that's the web control panel (web/). The MCP is for the agent.
• Not wired to macsync/mr-number directly — those are reached through the service.

Roadmap

• The generative draft/outbound path (when added) is served by an OSS uncensored LLM on a raw GPU droplet (see the engine roadmap) — never Claude. The MCP surface is unchanged; only the backend's draft engine swaps.
• Add prospector_correction once the teach-loop endpoint lands, so the coworker's corrections feed the OSS model tuning.

Addressing MISSING_REQUIREMENTS (the legacy quinn-prospector MCP gaps)

This new backend + MCP is the path to retire the Cowork stopgap autohandler. Current coverage of the 2026-06-29 gaps:

• #1 real raw-text classify: prospector_classify (and submit) now uses fast + booking extraction + composition when handle provided. (GPU atoms path per draft-engine.md is the follow-up.)
• #2/#3 booking triad + takeover verdict: parseBookingFromText + hasFullTriad + computeQual in runner + returned on submit/classify. takeoverReady = fullTriad && mrApproved.
• #4 real composition + confidence: inbound + classify pull people signals (mr, status), auto-request MR on rate, known/human gates, use fastConfidence + mr/booking for confidence. Structured return.
• #5 send-safety floor at boundary: extended Gate-2 (vendor_shortcode patterns for CVS/Moxy/electrolysis/telehealth etc), human_owned, known_contact pre-filters in inbound + gate. Cooldown/dedupe via macsync.
• #6 delivery: macsync enqueue returns id + deduped/notBefore; digest reports errors. Full poll surface can be added on macsync side.
• #7 channel: channelPref + signals; auto-record on bounce is follow-up (ties to macsync H06).
• #9 ownership: human_owned signal gate (ties to macsync H05).
• #13 structured: classify returns the exact shape agents need (no text blob).
• #14 canon: pastebin service already ingests live 🌹 note for all renders (no drift).
• New process_inbound parity: submit_inbound + classify give the autonomous loop primitives; scheduler + runner provide the AFK tick.

Use with the web/ control panel or the full PWA. Register the prospector MCP (this) for agent trials. Keep legacy during vetting.