VHGENGINE MCP Server

Create an owned, versioned creator profile. Free; admin scope. At least one creator/audience/stance/fact is required. Returns the exact version, deny-by-default secondary-use decisions, receipts, and an unverified-attestation warning. Optional idempotency_key replays safely. Errors: unauthorized, forbidden, invalid_request, conflict, idempotency_conflict, configuration_unavailable, rate_limited.

Erase profile facts and consent history; retain a retraction marker. Admin scope. Already committed customer hook outputs are not silently deleted. No profile data is used for secondary learning or cross-customer retrieval today. One-way replay-key tombstones prevent delayed keyed writes from recreating the profile. Requires the current expected_version and confirm="delete". Errors: unauthorized, forbidden, not_found, conflict, idempotency_conflict, invalid_request, configuration_unavailable, rate_limited.

Get the current or one exact historical creator-profile version. Read scope. Foreign, deleted, and unknown ids all return the same not_found envelope. Returns the same profile object as REST. Errors: unauthorized, forbidden, not_found, invalid_request, rate_limited.

List current creator-profile versions, newest changed first. Free; read scope. Returns {profiles, limit, offset, total}. Each profile carries its immutable version, declarations, current secondary-use decisions, consent receipts, and unverified-attestation warning. Errors: unauthorized, forbidden, invalid_request, rate_limited.

Append a full immutable profile version with compare-and-swap. Admin scope. expected_version prevents lost updates. Returns version+1, or unchanged:true when the normalized full snapshot is identical. Optional idempotency_key replays safely. Errors: unauthorized, forbidden, not_found, conflict, idempotency_conflict, invalid_request, configuration_unavailable, rate_limited.

Remove this account's webhook (WP-M). Admin scope. Args: api_key (admin scope). Cost=free. Returns {deleted: true}. Errors: unauthorized, forbidden, not_found (none registered), rate_limited.

This account's webhook (url + last delivery status; never the secret). Free read. Args: api_key (read scope). Cost=free. Returns {url, created_at, last_delivery_status, last_delivery_at, events}. Errors: unauthorized, not_found (none registered), rate_limited.

List this account's webhook deliveries, newest first. Free read (WP-HOOKS). Verify your receiver end-to-end (a webhook.test ping is enqueued at registration) and diagnose failures without waiting out a real event. Args: status (pending|retrying| delivered|dead|retired), limit (1-200, default 50), offset (>=0), api_key. Each row has {delivery_id, event_type, status, attempts, last_status_code, error, timestamps, next_attempt_at, payload_preview (200 chars; the full body is never returned)}. Dead rows are kept 7 days. Errors: unauthorized, invalid_request, rate_limited.

Register (or replace) this account's webhook; the secret is returned ONCE. Admin scope. Hook Detector POSTs signed job.succeeded/job.failed/credits.low (WP-M). `url` https, no creds, public host; re-registering ROTATES the secret (a repeat call is not a no-op). Verify via X-VHG-Signature: sha256=HMAC_SHA256(secret, raw_body); a webhook.test pings. Args: url (1-2048), api_key (admin). Cost=free. Errors: unauthorized, forbidden, invalid_request, rate_limited. Returns {url, secret, created_at, events, note, test_delivery_id}.

Permanently delete this account. TERMINAL, not reversible. Admin scope (WP-LIFE). Pass confirm="delete" (guards accidents). Revokes ALL keys and deletes live profile facts/consent, hooks, webhooks, deliveries, jobs and idempotency; KEEPS bounded profile retraction markers, the immutable financial ledger, and de-associated outcome rows. Export FIRST with export_usage: ledger, every hook/immutable instance/outcome/profile, plus every retained job, commission and request tag in one call. Paged: get_usage/list_hooks/list_outcomes/list_jobs. Backup aging: GET /v1/legal. Errors: unauthorized, forbidden, invalid_request, rate_limited.

Return this account's state + remaining rate-limit budget. Free read. `rate_limit` carries {limit, remaining, reset_epoch, reset_at, window_seconds} for the per-account window, the same budget REST clients read from X-RateLimit-* headers. Pace a fleet off `remaining` instead of discovering the ceiling by taking a rate_limited mid-run; this read itself consumes one of those calls. No API key is ever echoed back. Errors: unauthorized, rate_limited.

Archived source-free writer. Use research_hook_evidence instead. Always fails before model, template, provider, storage, or billing work. Research requires a real public source video with at least 50,000 observed views, a canonical link, and an independently audio-verified exact opener. Errors: unauthorized; invalid_request with reason unsourced_hook_generation_archived.

Archived source-free batch writer. Use research_hook_evidence instead. Always fails before model, template, provider, job, storage, or billing work. It cannot pad research supply with generated or paraphrased hooks. Errors: unauthorized; invalid_request with reason unsourced_hook_generation_archived.

Score any hook text on 5 dimensions with rewrite tips. Free during beta. Deterministic heuristic scorer (no LLM). Args: text (3-300), platform, topic (optional, reproduces generate's score via the verbatim-echo penalty), tags (1-5 fleet slugs, WP-J), verbosity (full keeps per-dimension attribution), api_key, idempotency_key (replay not re-charged). Returns {score:{...,total}, verdict, suggestions, confidence, disclaimer, credits_charged, credits_remaining, request_id}. Errors: unauthorized, invalid_request, insufficient_credits, rate_limited.

Score many hooks ranked with `best`, or compare named SETS. Free during beta. All-or-nothing charge. Plain: texts (1-25, each 3-300 chars). Self-test (E13): compare=true + sets (2-4 named lists, <=25 texts total) INSTEAD of texts -> per-set rankings + avg_score + winner + an honest winner_summary (same heuristic scorer on every set, never view prediction). Also: platform, tags, verbosity, api_key, idempotency_key. Returns {results, best, ...} or {sets, winner, winner_summary, ...}. Errors: unauthorized, invalid_request, insufficient_credits, rate_limited.

See what this account's agents are doing: in-flight ops + recent ops. Free. `in_flight` merges the live-ops registry (real stage/pct/eta mid-run) with your queued/running jobs; `recent` is the last completed charged ops. Every row has a human-readable message. The REST surface also offers an SSE feed at GET /v1/activity/stream. Args: recent_limit (1-100, default 20), api_key. Errors: unauthorized, rate_limited.

List the hook archetypes with psychology, platforms, and templates. Free, no auth. Returns {archetypes:[{id, name, description, psychological_trigger, best_for, templates}]}. Use an id for generate_hooks(archetypes=[...]) or remix_hook(target_archetype=...).

Recent billing events (usage.recorded, credits.granted, credits.low). Free. Newest first, paged with limit/offset like list_hooks and list_outcomes. Returns {events:[{id, event_type, payload, created_at}], limit, offset, total}. Errors: unauthorized, invalid_request, rate_limited.

Cancel a job that is STILL QUEUED. Free, repeatable, never refunds. ALWAYS branch on `cancelled`; reason + next_action say what to do. A queued job was never charged (the worker charges), so credits_refunded is always 0. A RUNNING job cannot be stopped: it finishes, CHARGES and persists. Cancelled reads as status "failed" with error.error.details.cancelled true; to re-run, resubmit with a FRESH idempotency_key (reusing the cancelled one replays the cancelled result). Errors: unauthorized, forbidden (key lacks the spend scope), not_found, rate_limited.

Get a hosted-checkout link outside beta. Disabled while beta pricing is free. The REQUIRED idempotency_key creates or replays one durable order and Stripe is called under an order-derived key, so a retry never mints a second order or session. Args: pack (from pricing.credit_packs), idempotency_key, success_url/cancel_url, api_key (spend). Returns {checkout_url, pack, credits, usd_cents, expires_at, order_id, order_state, replayed}. Errors: unauthorized, forbidden, invalid_request, idempotency_conflict, payments_disabled, rate_limited.

Compatibility credit grant (1-10000); beta customer operations are already free. When VHGENGINE_ADMIN_KEY is configured on the deployment this requires a matching admin_key argument; otherwise it stays self-serve (unless VHGENGINE_FREE_CREDITS is off). Idempotent on idempotency_key (replay does NOT grant twice). Returns {credits (new balance), granted}. Errors: unauthorized (missing/wrong admin key or self-serve disabled), invalid_request (amount range / balance ceiling), idempotency_conflict, rate_limited.

The measured/expected wait per generation mode. Free, no auth. Size a call before spending. Returns {op, modes:{instant|smart|research: {p50_ms, p90_ms, samples, source ("measured" once enough samples, else "default"), advice}}}.

Export ledger, hook, instance, lineage, outcome, profile, and retained-job data. Free; run BEFORE delete_account. Same JSON body as GET /v1/usage/export; CSV has events. UNBOUNDED: prefer paged reads on big accounts. Email is masked without admin scope. Returns account/email/count, ledger, hooks, instances, lineage, outcomes, jobs, profiles, source_evidence, and corrupt markers. Jobs and profiles retain their bounded receipts. Source evidence includes metrics, retractions, and separate research/extraction results. Filters narrow ledger events only; all retained data categories stay complete. Errors: unauthorized, forbidden (key lacks read scope), rate_limited.

The 5-step agent quickstart: modes, wait guidance, links. Free, no auth. Written to be parsed and acted on. Returns {what_this_is, five_steps, modes (cost + live latency + when to use), wait_guidance (expected_wait, estimates, progressToken, jobs), links}.

Deep health: DB read+write probe, worker/queue, backup + integrity. Free. Uses the same DB, backup, offsite, and integrity probes as GET /health; status is "ok" only when the DB reads and writes. Returns status/time/LLM, outcome, queue, backups, integrity, running synthesis and delivery postures, commission/source/extract readers, profile readiness, and source writer state. Readable schema 3 proves codec support only; readiness separately proves this process has the exact authorization, private queue, deletion, and immutable-lineage substrate. llm_configured never calls an LLM; check job_worker_alive before start_generate_job.

Fetch one bought hook in full, including its parsed score. Free (WP-G). Account-scoped: a foreign or unknown id is not_found (no existence leak). Args: hook_id (from a generate/batch/remix response or list_hooks), api_key. Returns {hook_id, text, archetype, claim_type, mode, platform, topic, score_total, score, prompt_version, request_id, created_at, outcomes:[...], outcome_summary:{count, max_views, avg_views}}. Report results with report_outcome. Errors: unauthorized, not_found, rate_limited.

List the hooks this account has bought, newest first. Free (WP-G). Retrievable for 90 days. Args: mode (instant|smart|research|remix, or a generate alias such as template/search), since (ISO timestamp), tag (exact fleet-tag match), topic (substring), request_id (recover one charged call's hooks), unreported (only hooks a first outcome report can reward), limit (1-100), offset, api_key. Returns {hooks:[{hook_id, text, archetype, mode, score_total, created_at, request_id}], limit, offset, total}. Errors: unauthorized, invalid_request, rate_limited.

Poll an async job: status, real engine stage, progress, ETA, result/error. Poll after poll_after_seconds until status is "succeeded" (result holds the full generate body) or "failed" (error holds the typed envelope). Only the owning account can read a job; a foreign/unknown id is not_found (no existence leak). Returns {job_id, status, stage, progress_pct, eta_seconds, elapsed_ms, poll_after_seconds, result, error}. Errors: unauthorized, not_found, rate_limited.

List this account's jobs, newest first (summaries without the result blob). Args: limit (1-200, default 50), offset (>=0), api_key. Returns {jobs:[{job_id, status, stage, progress_pct, created_at, started_at, finished_at}], limit, offset, total}. Errors: unauthorized, rate_limited.

Mint a new named API key; the plaintext is returned ONCE. Requires admin scope. Delegate safely (WP-SCOPE): optional scopes (subset of read|spend|admin; omit for full power) + daily_credit_cap (credits/day; omit for uncapped) hand a sub-agent a key that can only do what you allow. Args: name (1-100), api_key (an admin-scoped key). Returns {api_key (store it), prefix, name, scopes, daily_credit_cap, created_at}. Errors: unauthorized, forbidden, invalid_request, rate_limited.

List this account's API keys as PREFIXES only (never the raw key). Admin scope. Returns {keys:[{prefix, name, scopes, daily_credit_cap, spent_today, created_at, revoked_at}]}, oldest first; revoked_at is null for an active key, scopes lists the key's grant (WP-SCOPE), spent_today is its credits spent since UTC midnight. Your signup key shows as name "default". Errors: unauthorized, forbidden, rate_limited.

List the posted outcomes THIS account has reported, newest first. Free (WP-LIFE). Retrieve submitted telemetry in bulk. Args: platform (tiktok|instagram|youtube|x|linkedin|other), since (ISO timestamp), hook_id, limit (1-200, default 50), offset (>=0), api_key. Rows include the feature snapshot. Returns {outcomes:[...], limit, offset, total}. Errors: unauthorized, invalid_request, rate_limited.

The machine-readable price list, with per-mode expected_wait. Free, no auth. Every customer operation is zero-priced during private beta. Returns {unit, usd_per_credit:0, beta, operations, pricing_modes with zero base/per_hook, expected_wait}. Internal provider-credit ceilings are separate from this list.

Read archived generation price and wait metadata without spending. Free. Validates the retained input schema and computes its historical price ceiling, balance, cap blocker, and wait metadata. It does not authorize or predict a runnable operation: generate_hooks is archived and always fails before work or billing. Errors: unauthorized, invalid_request, rate_limited.

Requeue a dead-lettered webhook delivery: reset to pending, due now. Admin scope. Valid ONLY on a `dead` delivery (a live receiver that exhausted its retries); any other status is a 409 conflict and a delivery you do not own is not_found. It re-attempts through the normal pipeline and, if it dies again, dead-letters normally. Args: delivery_id (from list_webhook_deliveries), api_key. Returns the refreshed row. Errors: unauthorized, forbidden, not_found, conflict, rate_limited.

Archived source-free remix writer. Use research_hook_evidence instead. Always fails before rewriting, model, storage, or billing work. An extracted source hook cannot be replaced by generated or paraphrased copy. Errors: unauthorized; invalid_request with reason unsourced_hook_generation_archived.

Report what a bought hook actually did once posted. FREE (WP-H). Caller-supplied, unverified, and not used by generation/scoring/retrieval today. Retained for possible future calibration; no view prediction. Args: hook_id, platform (tiktok|instagram|youtube|x|linkedin|other), posted_at, views/likes (0..1e11), retention_pct?, url?, api_key, idempotency_key. Caps 20/hook, 500/day; an exact duplicate is a conflict. Returns outcome + aggregate + reward. Errors: unauthorized, not_found, invalid_request, conflict, rate_limited.

Return an unpadded portfolio selected deterministically from verified evidence. Hard gates precede relevance and diversity; views are observed platform views. Openers are audio_verified, or transcript_grounded with explicit caveats when enabled. Each item has a grounded idea and later exact payoff, bound by content_arc_receipt to one request, media and transcript. Exact-audio items carry first_audible_speech and leading_segments; transcript-grounded items carry first_transcribed_spoken_unit and leave both audio-only fields null. New calls default to exact delivery; allow_partial accepts a shortfall at or above the declared minimum. Retained terminals may replay legacy shapes. Where the provider runtime is bound this DISPATCHES and SPENDS credits under a 600-second authorization for synchronous calls: allow at least 610 seconds. A 502 after about 300 seconds is the transport cutting a silent response, not the commission failing: replay the same idempotency_key for the completed result at no additional charge. Counts 11-30 require an idempotency key and return a durable job; poll get_job. Their execution budget is 1200 seconds, not a measured latency promise. Use result_view=compact for source evidence without the operational ledgers; full preserves the complete audit result. Errors: unauthorized, invalid_request, idempotency_conflict, rate_limited.

Revoke the key with `prefix` (from list_keys): it stops working, others keep working. Use to kill a leaked or old key. Args: prefix (the 12-char key prefix, e.g. vhg_sk_ab12), api_key (a DIFFERENT active key to authenticate this call). Returns {prefix, name, revoked, revoked_at, already_revoked}. You cannot revoke your LAST active key (create a replacement first). Requires the admin scope. Errors: unauthorized, forbidden, invalid_request (last key), not_found, rate_limited.

Every call this account was charged for, newest first. Free read. Recover a lost response in two calls, never re-charged: list_runs(request_id=...) for the receipt, then follow `hooks_url` for the hooks it produced. Page with `cursor` (one pass total) or `offset`; stop only when `exhausted` is true, never on a short page. Same composed read GET /v1/runs makes, so the two can never disagree. Errors: unauthorized, invalid_request, rate_limited.

Redeem a private-beta code and create an account. No API key needed. Standard codes are single-use with ten product requests. Owner codes are reusable and unlimited. Signup retains 500 credits as a compatibility balance, while customer pricing is zero during beta. An exact idempotent replay returns the same account and same derived API key without a second redemption. Errors: beta_access_denied, invalid_request, idempotency_conflict, rate_limited.

Archived source-free writer job. Use research_hook_evidence instead. Always fails before a job, model, provider, storage, or billing work. Async execution cannot bypass source-video, view, link, and excerpt proof. Errors: unauthorized; invalid_request with reason unsourced_hook_generation_archived.

Write original hooks derived from verified viral source evidence. Each hook cites one admitted source: verbatim opening, timestamps or explicit nulls for untimed transcript evidence, observed views with observation time and a versioned virality receipt whose caveats say views correlate with, not prove, quality. A lexical novelty guard rejects copied source wording; quality stays unmeasured; never padded. idempotency_key is REQUIRED; a replay returns the exact stored terminal, uncharged. Live posture: GET /health hook_synthesis_enabled; evidence and LLM gates also apply. Errors: unauthorized, invalid_request, idempotency_conflict, conflict, rate_limited.

Return the credit balance, per-operation totals, and recent ledger. Free. Args: recent_limit (1-200, default 50), offset (>=0, pages `recent` past the newest rows), request_id (scope recent to that call's charges), tag + key_prefix (WP-J fleet filters), api_key. Returns {credits, totals:{by_operation}, recent:[...]} (each row carries key_prefix; tags in metadata). Errors: unauthorized, invalid_request, rate_limited.

Block until a job is terminal, then return it. Free, bounded, no poll loop. Returns the chosen get_job result_view plus timed_out, waited_ms and polls; branch on `status` exactly as you would with get_job. timed_out:true is NOT a failure, it means the budget ran out: call again with the SAME job_id. Waiting neither cancels nor charges; the worker charges when it runs the job either way. It returns IMMEDIATELY with worker_alive:false + `warning` when no worker exists here. Errors: unauthorized, not_found (unknown or foreign job_id), rate_limited.