Prelink MCP — Overview

Prelink turns a Google Maps listing or business website into a mobile customer action page: services, reviews, hours, tap-to-call, messaging, directions, and an enquiry form.

Who this is for

AI agents (Cursor, Claude Desktop, custom MCP clients) acting on behalf of a Prelink account owner — typically agencies or operators managing local-business pages.

Capabilities

• Create draft pages from Maps / website URLs
• List and inspect owned sites
• Publish / unpublish (plan limits apply)
• Read and update the enquiry inbox
• Check plan usage and entitlements

First steps

1. Confirm auth: call whoami or read prelink://docs/auth
2. Prefer reading prelink://docs/workflows before multi-step tasks
3. Never invent siteId / enquiryId / jobId — only use values returned by tools

Response format

Successful tools return JSON text with "ok": true (or success fields).

Failures return JSON with "ok": false and "error": "…" and isError: true.

Dates are ISO-8601 strings.

Prelink MCP — Authentication

API keys

• Create keys in the Prelink app: API & MCP (/app/settings)
• Format: plk_… (shown once at creation)
• Max 5 active keys per account
• Scopes (least privilege):

- read — whoami, docs, list/get sites & enquiries, usage, job status

- write — publish, unpublish, update enquiry status

- generate — generate_site (write/generate also imply read)

• Expiry — default 90 days; options: never / 30d / 90d / 1y. Expired keys are rejected and soft-revoked.
• Revoke anytime; revoked keys fail auth immediately
• Send as: Authorization: Bearer plk_…
• Secrets are stored as SHA-256 hashes only

Client config (Cursor / Claude)

{
  "mcpServers": {
    "prelink": {
      "url": "https://YOUR_HOST/api/mcp",
      "headers": {
        "Authorization": "Bearer plk_YOUR_KEY"
      }
    }
  }
}

Replace YOUR_HOST with the Prelink origin (e.g. prelink.co or localhost:3000).

Verify

Call whoami. You should get account email, plan, and the MCP endpoint.

Security rules for agents

• Do not print full API keys in logs or user-visible chat unless the user just created one and asked to copy it
• Do not store keys in repo files
• Prefer read-only keys when the task does not need publish/generate
• If auth fails, tell the user to create/revoke keys at /app/settings
• If a tool fails with a missing scope, ask the user to mint a key with that scope

Prelink MCP — Tools

Account

`whoami`

Verify the API key. Returns account, plan, and MCP URLs.

• Annotations: read-only
• Use when: connecting for the first time or debugging auth

`get_usage`

Plan name, published-site count/limit, enquiry allowance, entitlement flags.

• Annotations: read-only
• Use when: before publish if you might hit plan limits

`get_docs`

Return a documentation section (overview | auth | tools | workflows | errors | limits | full).

• Annotations: read-only
• Use when: resources are unavailable or you need a refresher mid-task

Sites

`list_sites`

List owned sites: id, name, slug, status, public URL, new enquiry count.

• Annotations: read-only

`get_site`

Full site: sections, actions, sources, profile fields, needsReviewSections, editorUrl.

• Input: siteId
• Annotations: read-only
• Use when: after generate, before publish, or when editing guidance is needed

`generate_site`

Create a draft from a Google Maps listing URL or business website URL. Site is owned by the authenticated user immediately (no claim token).

• Input: url (required), wait (optional boolean, default true)
• Behavior:

- wait=true (default): block until COMPLETED / PARTIAL / FAILED (often 30–120s)

- wait=false: return jobId immediately; poll get_generation_job

• Annotations: open-world (fetches external URLs)
• Prefer: Maps listing URLs for local businesses

`get_generation_job`

Poll job state: PENDING → … → COMPLETED | PARTIAL | FAILED.

• Input: jobId
• Annotations: read-only

`publish_site`

Publish a draft. Fails on reserved/taken slug or plan published-site limit.

• Input: siteId
• Returns: public url
• Annotations: idempotent

`unpublish_site`

Revert to draft; public URL stops working.

• Input: siteId
• Annotations: destructive, idempotent

Enquiries (inbox)

`list_enquiries`

List submissions for a site (plan history + monthly visibility rules apply).

• Input: siteId, optional status (NEW | READ | REPLIED | ARCHIVED), optional limit (1–100, default 25)
• Notes: internal notes only included on Starter+

`get_enquiry`

One enquiry by id.

• Input: siteId, enquiryId

`update_enquiry_status`

Set status to NEW | READ | REPLIED | ARCHIVED.

• Requires: Starter+ (enquiryStatusesNotesEnabled)
• Input: siteId, enquiryId, status

Prompts

`create_and_publish`

Guided multi-step: generate → review → publish for a given URL.

Prelink MCP — Workflows

A. Create and publish a page

1. whoami — confirm auth + note plan
2. get_usage — check publishedSites vs siteLimit
3. generate_site with Maps or website url (wait=true unless the client may time out)
4. If failed → read error, fix URL, retry once
5. get_site — summarize name/category; mention needsReviewSections
6. publish_site — return the public url to the user
7. If publish fails on limit → explain plan limit; leave as draft and share editorUrl

B. Async generation (slow clients / timeouts)

1. generate_site with wait=false
2. Poll get_generation_job every few seconds until COMPLETED, PARTIAL, or FAILED
3. Continue from step 5 in workflow A

C. Triage enquiries for a business

1. list_sites — find the site (or ask user for name/slug)
2. list_enquiries with status=NEW
3. get_enquiry for details when needed
4. update_enquiry_status → READ or REPLIED after the user handles it
5. If status update is denied → tell user Starter+ is required

D. Audit an existing account

1. whoami + get_usage
2. list_sites
3. For each published site of interest: get_site, list_enquiries (limit 10)

Do / Don't

Do

• Use real IDs from tool results
• Prefer Maps URLs for salons, cafés, trades, clinics
• Tell the user the public URL after publish

Don't

• Invent profile copy beyond what get_site returns unless the user asks to draft edits (edits via MCP are limited — use the web editor for deep content changes)
• Publish without checking usage if the account may be on Free/Starter (1 published site)
• Retry generate in a tight loop on rate-limit errors — honor retryAfterSec

Prelink MCP — Errors

All tool failures return JSON like:

{ "ok": false, "error": "Human-readable message" }

Auth

Generation

Publish

Enquiries

General recovery

1. Re-read the error string — it is meant for users
2. Call get_docs with errors or workflows if stuck
3. Prefer one retry with a corrected input over spamming tools

Prelink MCP — Limits & plans

API / MCP rate limits

• generate_site: about 10 requests / minute / user (also capped per API key) — in-memory blunt force
• generate_site: hard cap 50 generations / user / UTC day — durable (counts GenerationJob rows)
• Other tools: use reasonable pacing; avoid parallel generate storms
• Missing scope → error with requiredScope; do not retry with the same key

Plan entitlements (high level)

Exact numbers come from get_usage — always prefer live data over this summary.

Beta / grace periods may temporarily grant Business-level access — trust get_usage.

Generation notes

• Generate itself is not plan-gated, but publish is
• Generated sites start as DRAFT
• Partial generation may still produce a usable draft — check state and get_site

Key limits

• Max 5 active API keys per user
• Default key expiry: 90 days (configurable at creation)
• Prefer scoped keys (e.g. read only for inbox triage agents)