How to build a per-client ad lead dashboard with Claude Code

Four pieces: an endpoint that receives the instances' webhook, a table linking each instance to a client, a leads table with status and value, and a page with the per-client query. The events come from ZapZap, the sale goes back through tracking/conversion, and the dashboard only reads your database. Avoid letting the code agent query the API on every page view.

For secure receiving, follow the guide on idempotent webhooks. For measurement, see measuring CPL with the conversion API. Here the focus is on orchestrating the agent.

Start with the project instructions file, with the base URL, the variable names and the rule to use only operations from the OpenAPI. Then install the MCP server. On 11/11/2026 the zapzap-mcp package does not appear on npm (npm view returned 404), so installation means cloning the github.com/zapzapapi/zapzap-mcp repository and building it. Recheck with npm view before using npx.

Register it with ZAPZAP_READ_ONLY=true, which exposes only the read tools (list instances, check status, query messages and webhooks). That way the agent queries and does not send a message by mistake. The server does not receive messages: receiving is the webhook in the next step.

# CLAUDE.md of the dashboard project (instructions for the agent)
- Stack: Node.js + Express + SQLite (or Postgres) + one HTML page.
- ZapZap API: base https://api.zapzapapi.com/api/v1, headers x-api-key and x-api-secret,
  read from ZAPZAP_API_KEY and ZAPZAP_API_SECRET. Never print or commit them.
- Spec: https://zapzapapi.com/openapi/zapzap-openapi.pt.json  Summary: https://zapzapapi.com/llms.txt
- Use only operations present in the spec. If something does not exist, say so.
- The zapzap MCP server is READ ONLY (ZAPZAP_READ_ONLY=true). Never ask to send messages.
- Webhooks: validate X-ZapZap-Signature on the raw body, dedupe by event_id or delivery_id.

# The zapzap-mcp package is not on npm yet (npm view zapzap-mcp returned 404 on 2026-11-11),
# so install from the repository. Check "npm view zapzap-mcp" again before using npx.
git clone https://github.com/zapzapapi/zapzap-mcp.git
cd zapzap-mcp && npm install && npm run build

# Register it in Claude Code in read-only mode (no send tools are exposed)
claude mcp add zapzap \
  -e ZAPZAP_API_KEY=your-api-key -e ZAPZAP_API_SECRET=your-api-secret -e ZAPZAP_READ_ONLY=true \
  -- node /full/path/to/zapzap-mcp/dist/src/index.js

Ask the agent for the schema below, which maps instance_id to a client (the key the event always carries) and stores the lead by phone. Mapping by the envelope's instance_id is sturdier than relying on extra fields. The instance's metadata serves as a cross-check. The query at the end feeds the page.

-- Minimal schema for the per-client lead dashboard
CREATE TABLE clients (id text PRIMARY KEY, name text NOT NULL);
CREATE TABLE instances (instance_id text PRIMARY KEY, client_id text NOT NULL REFERENCES clients(id));
CREATE TABLE leads (
  id integer PRIMARY KEY AUTOINCREMENT,
  client_id text NOT NULL, instance_id text NOT NULL,
  phone text NOT NULL, first_message text, first_seen_at text NOT NULL,
  status text NOT NULL DEFAULT 'open',          -- open | qualified | scheduled | won
  sale_value real, UNIQUE (instance_id, phone));
CREATE TABLE webhook_events (
  instance_id text NOT NULL, dedupe_key text NOT NULL, received_at text NOT NULL,
  PRIMARY KEY (instance_id, dedupe_key));

-- The page query: leads by client in the last 30 days
SELECT c.name, COUNT(*) AS leads,
       SUM(l.status = 'won') AS sales, COALESCE(SUM(l.sale_value), 0) AS revenue
FROM leads l JOIN clients c ON c.id = l.client_id
WHERE l.first_seen_at >= date('now', '-30 days')
GROUP BY c.id ORDER BY leads DESC;

Prompt 1: "Create the POST /webhook endpoint with express.raw, validate X-ZapZap-Signature (HMAC SHA-256 over t.body, 5-minute tolerance), store the event_id or delivery_id key in webhook_events and answer 200. Write tests for a valid, expired and tampered signature." Prompt 2: "Use the MCP to list the instances and fill the instances table; show me what you will write before writing." Prompt 3: "Record each first received message as a lead, unique per instance and phone. Before modeling, save the first real payload and show it to me." That last request keeps the agent from inventing the shape of the data field.

Prompt 4: "Create the /clientes page with the query, ordered by leads, and an instance status column." Prompt 5: "Call POST /{instanceId}/tracking/conversion when I mark a sale in the dashboard and handle 404 and 409 as documented." At every step, require the agent to cite the OpenAPI operation it used.

Review three things before going live: secrets only in environment variables, never in the repository or the prompt; end-customer text treated as untrusted input (the MCP reads messages and they may contain instructions); and a login on the page, because it shows phone numbers. Keep read-only mode, and only think about enabling sending after a volume lock and an allow-list.

Evolve in order: a number health dashboard, then the monthly report (automating reports), then the client portal link. For the general context, see the AI agents page and AI agencies.