@drip/crm-mcp-server

MCP server exposing Drip CRM's hosted-backend capabilities as agent tools: natural-language lead-search planning, server-side lead-search runs with ranked verified results, run bookkeeping, and managed inbox (domain + mailbox) provisioning.

This is separate from @drip/mcp-server (the billing MCP, under its own v2 rewrite). It copies that package's certified conventions — tool registry, problem/cause/fix error envelopes, untrusted-source fencing, DRIP_READ_ONLY gating — but wraps the CRM surface (/v1/cold-leads/*, /v1/email-outreach/*) instead of billing.

Install / run

pnpm --filter @drip/crm-mcp-server build
node packages/crm-mcp-server/dist/index.js   # stdio transport

Wire it into an MCP client (Claude Code shown; any stdio MCP client works the same way):

claude mcp add drip-crm \
  --env DRIP_API_TOKEN=sk_test_... \
  -- node /path/to/drip/packages/crm-mcp-server/dist/index.js

or in a JSON client config:

{
  "mcpServers": {
    "drip-crm": {
      "command": "node",
      "args": ["/path/to/drip/packages/crm-mcp-server/dist/index.js"],
      "env": {
        "DRIP_API_TOKEN": "sk_test_..."
      }
    }
  }
}

Auth + env vars

| Var | Required | Meaning | |---|---|---| | DRIP_API_TOKEN | yes | Drip secret API key (sk_test_* / sk_live_*), sent as Authorization: Bearer. Every wrapped route requires a secret key; pk_* is rejected client-side. Lead-search tools need the OPERATOR role, inbox provisioning needs ADMIN (key roles are managed in the dashboard under API keys). | | DRIP_API_BASE_URL | no | Hosted backend base. Default https://api.drippay.dev — the Production server in docs/openapi.json, the same base the desktop app's hosted calls use. | | DRIP_READ_ONLY | no | When truthy, every mutating tool is refused with a READ_ONLY_MODE envelope. Mutating = spends money/credits or creates hosted state: drip_run_lead_search, drip_provision_inbox. | | DRIP_ALLOW_LIVE_WRITES | no | On a sk_live_* key, mutating tools are default-denied (same certified posture as the billing MCP — protects against prompt-injected agents spending real budget). Set true to unlock all of them. | | DRIP_ALLOW_LIVE_WRITE_TOOLS | no | Granular per-tool live unlock, comma-separated (e.g. drip_run_lead_search). |

Getting a token: create an API key in the Drip dashboard (API keys page) with at least the role you need (OPERATOR for search, ADMIN for provisioning), or use the workspace's existing desktop key. drip_whoami validates the token and reports exactly which capabilities it can reach.

Tools

| Tool | Route(s) wrapped | Write? | What it does | |---|---|---|---| | drip_whoami | GET /v1/business/settings + capability probes (GET /v1/cold-leads/usage, GET /v1/email-outreach/mailboxes) | no | Validate the token; report business identity, key mode, active gates, and which capabilities the token can reach. | | drip_search_leads | POST /v1/cold-leads/plan | no | NL request → reviewable structured plan. Surfaces clauses, unresolvedRequirements (plan can't run as-is) and distilledRequirements (dropped as unprovable/preferences). No search budget spent. | | drip_run_lead_search | POST /v1/cold-leads/run + poll GET /v1/cold-leads/run/:idempotencyKey | yes | Execute the pipeline; returns ranked results (person/company, fit verdict + score, verified vs review-required, needs-review notes) and the funnel-diagnostics line. Waits up to waitSeconds with MCP progress notifications, then hands back the idempotencyKey for later pickup. Pass the plan from drip_search_leads as approvedPlan for exact reviewed execution. | | drip_get_lead_run | GET /v1/cold-leads/run/:idempotencyKey | no | Fetch a past/running run by its idempotency key (results replayed ~24h). | | drip_list_lead_runs | GET /v1/cold-leads/telemetry/summary | no | Aggregate run bookkeeping over a 1–90 day window (counts by status/source, funnel sums, spend, latency, outcomes). Honesty note: the backend has no per-run list endpoint — individual runs are addressable only by idempotency key. A true run list is roadmap (below). | | drip_list_inboxes | GET /v1/email-outreach/mailboxes + GET /v1/email-outreach/domains | no | Managed sender mailboxes + domains with provisioning/DNS/auth/pacing status. | | drip_provision_inbox | POST /v1/email-outreach/managed-orders | yes | Provision one managed domain + 1-50 sender mailboxes in a single billed order (Google Workspace / Microsoft 365 via Icemail). |

Known caveat (stated in the inbox tools too): mailbox health/status reporting has known gaps — app-side wave-2 fixes are in flight. Treat readiness flags as advisory until then.

Contract honesty

Every request body is validated against a mirror of the backend's actual route validators before it goes on the wire (src/contracts.ts, pinned to backend/src/routes/coldLeads.ts, emailOutreach.ts, coldLeadTelemetry.ts and services/coldLeads/searchPlan.ts). If the mirror rejects a body the tool built, the call fails loudly with CONTRACT_VIOLATION instead of drifting into a mid-run 400 — the drift class that bit the billing MCP (offset-vs-cursor, phantom fields, missing idempotency keys). The plan → run round-trip also strips the preview-only metadata fields the strict approved-plan schema rejects, and refuses plans that still carry unresolved requirements (the backend would refuse them mid-run anyway).

Security posture

• Untrusted-source fencing: every backend payload that can carry customer-entered or scraped-web text (lead names, titles, summaries, mailbox display names, business profile) is entity-escaped and wrapped in <untrusted source="drip_api"> fences before it reaches the agent.
• Secret scrubbing: sk_* / rk_* / whsec_* patterns are redacted from every escape path (success and error).
• Env-only gates: read-only and live-write gates are controlled by env vars, never by tool arguments (LLM-controlled args are trivially bypassed under prompt injection).

Errors

Every failure returns one JSON envelope: { error_code, problem, cause, fix, docs_url?, detected_key_type?, env_vars_to_set? } — same shape as the billing MCP. Status-mapped fixes cover 401 (bad token), 402 (managed-email subscription required), 403 (role too low), 404, 422 (validation details), 429 (mutation limiter / daily search cap), 5xx.

Tests

cd packages/crm-mcp-server
npx vitest run test/registry.test.ts test/gate.test.ts test/contracts.test.ts test/errors.test.ts test/tools.test.ts
pnpm typecheck

Covers: tool registration, args schema validation, error envelopes, read-only + live-write refusal, one happy path per tool with mocked fetch, and 401/402/403/404/422/429 paths.

Roadmap (deliberately out of scope for v0)

• App bridge (v1): campaign create/start, message drafts, autopilot toggles and sends live in the local desktop app (Tauri), not the hosted backend — they need a local MCP endpoint inside the app process (desktop-side bridge exposing the same registry/gate pattern over a localhost transport). This package intentionally does not fake them.
• True run list: needs a backend route over the per-run replay/telemetry rows (currently key-addressed + aggregate only).
• Lead-search monitors: recurring search-only monitors (/v1/cold-leads/monitors*) exist behind a feature flag; wrap once the flag is stable.
• Deferred email reveal: POST /v1/cold-leads/contacts/reveal (per-contact PDL spend) — wants a spend-confirmation UX before agents can trigger it.