mcp server

VHGENGINE

Agents-first viral-hook engine: generate, score, and remix short-form hooks over MCP.

Description as published by the maintainer. Source

• version 2.3.0
• active

active — Registry entry last updated 2026-07-22.

What this server can do

44 functions, named and described by the server itself. Parameter names are shown because they say more about what a function does than its name usually does.

add_credits(amount, api_key, admin_key, idempotency_key)

Top up your credit balance (1-10000). Self-serve by default. 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. Required: amount.

cancel_job(job_id, api_key)

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. Required: job_id.

create_checkout(pack, api_key, cancel_url, success_url)

Get a Stripe hosted-checkout link for a credit pack. You never touch a card (WP-PAY). Hand the returned checkout_url to your human; the webhook credits you after they pay. Args: pack (a credits amount from pricing.credit_packs), success_url/cancel_url (optional), api_key (spend scope). Returns {checkout_url, pack, credits, usd_cents, expires_at}. Errors: unauthorized, forbidden, invalid_request (bad pack), payments_disabled (503; use add_credits), rate_limited. Required: pack.

create_creator_profile(stance, api_key, creator, audience, display_name, secondary_use, idempotency_key, authority_attested, first_person_facts, subject_relationship)

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. Required: display_name, subject_relationship, authority_attested.

create_key(name, scopes, api_key, daily_credit_cap)

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.

delete_account(api_key, confirm)

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. Required: confirm.

delete_creator_profile(api_key, confirm, profile_id, idempotency_key, expected_version)

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. Required: profile_id, expected_version, confirm.

delete_webhook(api_key)

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.

export_usage(tag, api_key, key_prefix)

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.

generate_hooks(mode, tags, count, style, topic, stance, api_key, clarify, creator, audience, language, platform, verbosity, archetypes, deadline_ms, idempotency_key, requested_market, requested_dialect, creator_profile_id, first_person_facts, footage_constraints, delivery_constraints, desired_viewer_action, creator_profile_version, hook_length_constraints, desired_audience_feeling, requested_content_format, caller_confirmed_constraints)

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 200,000 observed views, a canonical link, and an independently audio-verified exact opener. Errors: unauthorized; invalid_request with reason unsourced_hook_generation_archived. Required: topic.

generate_hooks_batch(mode, tags, stance, api_key, clarify, creator, audience, language, platform, requests, verbosity, idempotency_key, requested_market, requested_dialect, creator_profile_id, first_person_facts, footage_constraints, delivery_constraints, desired_viewer_action, creator_profile_version, hook_length_constraints, desired_audience_feeling, requested_content_format, caller_confirmed_constraints)

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. Required: requests.

get_account(api_key)

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.

get_activity(api_key, recent_limit)

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.

get_creator_profile(api_key, version, profile_id)

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. Required: profile_id.

get_estimates

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}}}.

get_hook(api_key, hook_id)

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. Required: hook_id.

get_job(job_id, api_key)

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. Required: job_id.

get_usage(tag, offset, api_key, key_prefix, request_id, recent_limit)

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.

get_webhook(api_key)

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.

getting_started

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}.

health

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, 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.

list_archetypes

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=...).

list_billing_events(limit, offset, api_key)

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.

list_creator_profiles(limit, offset, api_key)

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.

list_hooks(tag, mode, limit, since, topic, offset, api_key, request_id, unreported)

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.

list_jobs(limit, offset, api_key)

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.

list_keys(api_key)

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_outcomes(limit, since, offset, api_key, hook_id, platform)

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.

list_runs(limit, cursor, offset, api_key, operation, request_id, charged_only)

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.

list_webhook_deliveries(limit, offset, status, api_key)

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.

pricing

The machine-readable price list, with per-mode expected_wait. Free, no auth. Returns {unit, usd_per_credit (0 while credits are free), operations, pricing_modes:{instant:{base:0,per_hook:1},smart:{base:0,per_hook:2}, research:{base:10,per_hook:4}} each with a formula, expected_wait, signup_grant, low_balance_threshold}. A generate charge is base + per_hook * hooks_returned; these are the exact constants the charge path uses.

quote(mode, count, topic, api_key, platform, archetypes)

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. Required: topic.

redrive_webhook_delivery(api_key, delivery_id)

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. Required: delivery_id.

remix_hook(tags, text, count, topic, api_key, hook_id, platform, archetype, verbosity, idempotency_key, target_archetype)

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_outcome(url, likes, views, api_key, hook_id, platform, posted_at, retention_pct, idempotency_key)

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. Required: hook_id, platform, posted_at, views.

research_hook_evidence(depth, topic, locale, api_key, audience, freshness, must_exclude, must_include, allow_partial, viewer_action, desired_outcome, idempotency_key, requested_count, requested_format, problem_or_tension, requested_language, source_requirements, allowed_opener_states, minimum_acceptable_count, minimum_distinct_sources, accepted_source_languages)

Return a deterministic, unpadded portfolio of verified hook evidence. Hard evidence gates precede relevance and diversity selection. Every delivered item is independently audio_verified as the exact audible opener with a verified boundary and timestamps; transcript-contained evidence remains internal. Views are observed platform views, never an organic-views claim. The default runtime returns unsupported_cell without dispatch or charge until an approved provider runtime registers every required capability. Errors: unauthorized, forbidden, invalid_request, idempotency_conflict, insufficient_credits, rate_limited. Required: topic, requested_format.

revoke_key(prefix, api_key)

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. Required: prefix.

score_hook(tags, text, topic, api_key, platform, verbosity, idempotency_key)

Score any hook text on 5 dimensions with rewrite tips. 1 credit. 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. Required: text.

score_hooks_batch(sets, tags, texts, topic, api_key, compare, platform, verbosity, idempotency_key)

Score many hooks ranked with `best`, or compare named SETS. 1 credit per text. 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.

set_webhook(url, api_key)

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}. Required: url.

signup(name, email, idempotency_key)

Create an account and return your API key exactly once. No auth needed. The entry point: an agent with nothing calls this and is productive immediately (no CAPTCHA); new accounts get 500 credits. An idempotent replay returns the SAME account with replayed:true and a NULL api_key (the plaintext is never stored), so branch on `replayed`, never on the empty key. Cost: free. Errors: invalid_request, idempotency_conflict, rate_limited.

start_generate_job(mode, tags, count, style, topic, stance, topics, api_key, clarify, creator, audience, language, platform, archetypes, idempotency_key, requested_market, requested_dialect, creator_profile_id, first_person_facts, footage_constraints, delivery_constraints, desired_viewer_action, creator_profile_version, hook_length_constraints, desired_audience_feeling, requested_content_format, caller_confirmed_constraints)

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.

update_creator_profile(stance, api_key, creator, audience, profile_id, display_name, secondary_use, idempotency_key, expected_version, authority_attested, first_person_facts, subject_relationship)

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. Required: profile_id, expected_version, display_name, subject_relationship, authority_attested.

wait_for_job(job_id, api_key, timeout_seconds)

Block until a job is terminal, then return it. Free, bounded, no poll loop. Returns the EXACT get_job body plus timed_out, waited_ms and polls, so 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. Required: job_id.

Last successful function declaration observed on 2026-08-13. Source: https://engine-production-3bdc.up.railway.app/mcp. We list what the server declared; we do not call any of these functions.

Endpoint status observed on 2026-08-13. Source: https://engine-production-3bdc.up.railway.app/mcp.

Signals

These are separate measurements of different things. They are deliberately not combined into one score, because a popularity number that mixes website traffic with saves and stars cannot be checked or acted on.

Where to get it

• Website — https://engine-production-3bdc.up.railway.app/llms.txt
• Remote endpoint (streamable-http) — https://engine-production-3bdc.up.railway.app/mcp