Pendium MCP Docs

For Agencies and Consultants

How AEO, SEO, and growth agencies use Pendium to prospect new clients with personalized cold outreach and then monitor, measure, and grow their AI visibility once they sign.

If you sell AEO, SEO, content strategy, or growth services, Pendium gives you two distinct capabilities most of your competitors don't have:

  1. An outbound enrichment engine that turns a list of store URLs into ready-to-send cold-email content grounded in each prospect's actual catalog and AI-visibility gaps.
  2. A measurement and management surface that lets you run real visibility scans across ChatGPT, Claude, Gemini, and AI Overviews for every client in your book — and prove the lift over time.

Same API key works for both motions. Both motions stay inside the agency's account, so you don't need each client on their own seat to get started.

The two motions

ProspectingServicing
GoalOpen the conversation with a real opinion, not a template.Move a client's score up and prove it.
EndpointPOST /api/visibility/cold-emailPOST /api/visibility/scan + GET /api/visibility/report + the MCP tools
Per-call cost profileCost-effective by design — built for batches in the tens of thousands.Premium models, multi-platform — the depth a paying client expects.
OutputIntro hook, competitive intel, fun facts, findings, and a 4-sentence email draft per URL.Full per-platform scores, raw LLM responses, citations, recommendations, a public report URL.
PersistenceEvery pitch persisted by uuid for CRM linkage and replay.Score history, action items, scan-over-scan deltas.

You don't have to pick one. The natural funnel is to use the cold-email endpoint to start the conversation, then run the full report on the prospects who reply.

Motion 1: Prospect with the cold-email endpoint

The endpoint takes a single store URL and returns five structured fields plus a ready-to-send email body. The Shopify path is the most fluent — it pulls the actual storefront catalog (best-sellers, collections, price band) and grounds the email in real product names so it doesn't read like a mailmerge. Non-Shopify URLs degrade gracefully to a generic-store prompt that uses Open Graph metadata.

curl -X POST https://pendium.ai/api/visibility/cold-email \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_xxxxxxxxxxxx" \
  -d '{"url": "https://allbirds.com"}'

What you get back:

{
  "uuid": "a1b2c3d4-…",
  "isShopify": true,
  "shopDomain": "allbirds.com",
  "introHook": "Your Tree Runners are everywhere on TikTok, but ChatGPT still recommends Veja first.",
  "competitiveIntel": {
    "competitor": "Rothy's",
    "angle": "Brands like Rothy's tend to dominate AI answers about sustainable everyday sneakers — if your store isn't surfacing for those queries, you're losing the consideration set before the shopper ever clicks."
  },
  "funFacts": ["..."],
  "findings": [{ "title": "...", "detail": "..." }],
  "email": { "subject": "...", "body": "...\n\n[Your name]" }
}

Replace [Your name] with the rep's name, drop scanLandingUrl into the email as the CTA, and the email is ready to send. See the full reference.

Tuning the output for your book

Three optional fields shape how the pitch reads — pick whichever combination fits your outbound style:

  • categorydefault auto-detects Shopify and falls back to a generic store. Force shopify when you know the row is Shopify, ecommerce for broader online retail, yelp for local services with strong review signal, or gbp for businesses where Map Pack visibility is the lever. Different categories swap in different base prompts and stop pulling Shopify catalog data when it doesn't apply (yelp / gbp).
  • voice — pick a named preset (founder, consultant, witty, warm, direct) for character + tone + vibe in one knob, or pass your own voice text in the same field and it gets injected verbatim. The voiceLabel in the response tells you which path ran.
  • notes — open-ended instructions injected at the top of the prompt with override priority over the brand voice and anti-slop guards. Use it for campaign context ("all going out the week before Black Friday — tilt toward urgency without using the word"), tone constraints ("do not name competitors in the email body"), or a specific angle to lean into for a particular batch.
curl -X POST https://pendium.ai/api/visibility/cold-email \
  -H "x-api-key: pk_live_xxxxxxxxxxxx" \
  -d '{
    "url": "https://localdentist.com",
    "category": "gbp",
    "voice": "warm",
    "notes": "Lead with the GBP photo recency observation; do not mention review count."
  }'

Suggested workflow

  1. Source URLs however you already do — Shopify directories, ad-library scrapes, retail-tech LinkedIn lists, your existing book's referrals.
  2. Enrich each row by calling the endpoint. Sync response, no polling. Built for batch — if your list has 10,000 stores, run it in a single overnight job and store the uuid next to the row in your CRM.
  3. Spot-check the output, not every row. The Shopify-grounded path is reliable when the catalog is healthy; samples will tell you fast if a niche needs prompt tuning before you ship the batch.
  4. Send personalized emails from your existing tool (Instantly, Smartlead, Apollo, lemlist). Use email.subject and email.body as-is, or pull introHook / findings[0].detail into your tool's merge fields if you want to A/B against your existing template.
  5. When a recipient engages, pivot to the polished public report (motion 1.5).

Brand-identity grounding is on by default

Every call fires one live web search to ground the brand identity (catches the boreal.com-shaped wrong-brand confusion where a domain matches multiple companies) before the LLM call. The per-call cost is negligible and the accuracy lift is meaningful, so there's no opt-in flag — the response carries grounded: true when it fired and grounded: false (with a groundingFallbackReason) on the rare occasion the search backend is unavailable.

What not to do

  • Don't rewrite the email body to match your existing template. The body is intentionally specific — every product reference and finding is grounded in the store's actual data. Generic-template wrapping defeats the point.
  • Don't skip the spot-check. The fastest way to find a prompt-edge case is to read 10 outputs from a fresh batch before you ship.

Motion 1.5: Polish the click-through

When someone replies "tell me more," send them to a public report URL — not back to your homepage. The Visibility Scan Preview endpoint is the right tool: one call, runs in 30–90 seconds, returns a slug-canonical URL like https://pendium.ai/visibility-scan-preview/allbirds.com that's polished, branded, and includes the depth your prospect needs to take you seriously.

curl -X POST https://pendium.ai/api/visibility/scan-preview \
  -H "x-api-key: pk_live_xxxxxxxxxxxx" \
  -d '{"url": "https://allbirds.com"}'

You can pre-warm these the moment a prospect engages so the page is ready when they click. See Trigger a Visibility Scan Preview for the full flow.

Motion 2: Manage and grow the clients you've signed

Once a client says yes, the work shifts from generating outbound to measuring and improving real visibility across ChatGPT, Claude, Gemini, and AI Overviews. The full visibility scan endpoint is the workhorse here.

Account structure

Add each client as their own brand agent inside your agency's Pendium account. Every brand agent gets a syntheticId you reference everywhere — scans, reports, topics, personas, recommendations. The agency owns the account; the clients are agents inside it. Same API key works across every client; you don't need a separate seat per brand to get started.

When a client wants their own login (read-only dashboard, score-history view), invite them to a team account so they can see their own data without the surrounding book.

The monthly servicing loop

A typical monthly cadence per client:

Week 1 — Trigger a fresh scan.

curl -X POST https://pendium.ai/api/visibility/scan \
  -H "x-api-key: pk_live_xxxxxxxxxxxx" \
  -d '{"syntheticId": 1234, "mode": "batch", "maxQueries": 30}'

mode: "batch" is the recommended default — covers all four AI platforms with cost-effective models. mode: "full" swaps in premium models when accuracy matters more than budget (quarterly check-ins, before a big content release, when a score regression needs investigation). See Trigger a Scan.

Week 1 — Pull the report.

curl https://pendium.ai/api/visibility/report?syntheticId=1234 \
  -H "x-api-key: pk_live_xxxxxxxxxxxx"

Returns the full per-platform scores, raw LLM responses for every query tested, the citations each platform pulled, and a prioritized list of recommendations. The raw responses are the gold — they're the actual language ChatGPT and the others use about your client. Read them. They tell you what you're competing against in a way no aggregate score can.

Week 2–3 — Work the recommendations. Each recommendation comes with a rationale tying it back to a specific gap in the report. Pick the highest-leverage two or three and execute — your existing content + outreach + on-page work, but pointed at the AI-visibility gaps the scan surfaced. Mark items complete via POST /api/visibility/actions/{id}/complete as you ship.

Week 4 — Rescan and show the lift.

Same scan command. Pull the score deltas via GET /api/visibility/scan-history or directly from the agent dashboard at pendium.ai/{syntheticId}/visibility/history. The per-platform breakdown is what a client wants to see — "we moved from 38 to 51 on ChatGPT, 22 to 35 on Claude" is a real number you can put in a monthly report.

Topics and personas — the levers most agencies miss

Pendium tests how AI platforms answer specific queries. Out of the box, those queries come from the brand's category and a few default personas. The leverage move is to add the queries your client's customers actually type and add the personas they actually sell to.

# Add a topic with custom queries
curl -X POST https://pendium.ai/api/visibility/topics \
  -H "x-api-key: pk_live_xxxxxxxxxxxx" \
  -d '{
    "syntheticId": 1234,
    "name": "Competitive comparisons",
    "queries": [
      "Allbirds vs Rothy's for everyday wear",
      "best sustainable sneaker brand 2026",
      "what shoes do startup employees actually wear"
    ]
  }'

The next scan tests those queries. The next report tells you exactly how each platform answered them — including which competitors got named and which sources got cited. This is where you find the thin spots.

Same idea for personas. The "Technical Startup Founder" persona will get a different answer to the same query than "Suburban Mom of Three" — Pendium injects the persona's context into the system prompt during scans. Add the personas your client actually sells to and you'll see scores break down by buyer type. See Add Personas and Add Topics.

Use MCP if your team is in Claude Code or Cursor

If your team works in coding agents day-to-day, skip the curl and connect Pendium via MCP. Same data, same auth, but your agent discovers tools automatically. A typical Claude Code session looks like:

"Pull the latest visibility report for Allbirds and tell me which three recommendations would have the biggest score impact. Then add the queries from Wirecutter's 2025 sustainable-sneaker roundup as a new topic and trigger a rescan."

The agent calls get_report, ranks recommendations by projected impact, calls add_topic with the right queries, then scan_visibility to kick off the next scan. You read the report. The agent does the keystrokes.

Pricing and credits

Both motions consume credits from the agency account's balance. The cold-email endpoint is intentionally cheap — built so a 100k-row batch fits in a normal monthly budget. The full visibility scan is more expensive per call because it actually queries every AI platform with premium models. See Pricing for plan tiers and credit packs; agency-tier accounts get volume pricing on credit topups.

A practical rule of thumb: budget the cold-email endpoint as part of your outbound stack (alongside Apollo or Clay credits), and budget the visibility-scan endpoint as part of your client-servicing cost (alongside SEMrush or Ahrefs).

Common questions

Do I need each client to have their own Pendium account? No. Brand agents live inside your agency account. Invite the client to a team account only when they want their own login.

Can I white-label the public Visibility Scan Preview URL? Today the public URL is pendium.ai/visibility-scan-preview/{slug}. Custom-domain hosting for agency reports is on the roadmap; talk to us if it's a deal-breaker.

Do you have a referral program for agencies? Yes. Email partners@pendium.ai and we'll set you up.

What about non-DTC clients (B2B SaaS, professional services, local businesses)? The cold-email endpoint takes any URL and gracefully degrades to a generic-store prompt for non-Shopify sites. The visibility-scan endpoint is fully category-agnostic — the personas and topics layer is what tunes it to a specific industry. B2B SaaS, agencies, healthcare, legal, local — all work.

Next steps