Aetherya MCP Server

SECONDARY TOOL. Pose a question to a SINGLE synthetic persona and get one predicted, in-character response — good for an open-ended 'would this confuse someone like this?' sounding-out. The answer is SIMULATED (one persona's predicted reaction), not a real person, and ONE persona is not an audience: it carries no distribution and no disagreement, so never report it as what 'users' or 'the audience' think. For a finding you can act on, use aetherya_test_copy (compare variants) or aetherya_run_study / aetherya_plan_study (a panel with a spread of reactions).

Run a behavioral simulation: a synthetic audience visits a URL and predicts where real users would hesitate, get confused, or drop off, plus messaging-clarity and UX friction findings with concrete fixes. Ideal for evaluating a freshly built or changed page and getting actionable UX/messaging improvements in the same loop. To find out how people experience a flow (sign-up, onboarding, checkout), pass tasks and start_url: the simulated visitors then walk the flow step by step instead of touring the site. By default they stop before the final submit, so nothing is created or bought; pass allow_test_signups only when the user explicitly allows test sign-ups. Payment is never submitted. For pages behind a login, pass credentials for a dedicated test account the user gave you. Results are SIMULATED (predicted behavior of a synthetic audience), not feedback from real users.

Stop a study, instant read, plan, audit or post simulation that is still running. Use it when the user changes their mind or a run was started with the wrong inputs. Finished runs are not affected.

Compare 2+ image creatives (thumbnails, display banners, social images) against a synthetic audience. Creates the experiment, uploads the images, attaches the audience and drafts the comparison (free). It then returns status 'needs_price_confirmation' with the quoted simulation sessions; nothing is spent until you re-call with accept_sessions >= the quote (pass accept_sessions up front to skip the pause). To confirm a draft already created, pass comparison_id + accept_sessions only. Cost scales with creatives x personas; an audience group is capped at 10 personas per segment. choice_task adds a forced-choice round (choiceCost in the quote). Collect the ranking with aetherya_get_result kind 'creative_comparison'. Results are simulated, not real-user data.

Respond to a plan from aetherya_plan_study. Use action 'confirm' with accept_sessions to approve the quoted cost and start the run — this is the point at which simulation sessions are spent, so check with the user first. Use 'answer' to reply to the clarifying questions (answers with the option ids the user picked, or answer for one free-text reply), 'cancel' to abandon the plan, or 'retry' after a failure. After confirming, the run continues and returns its decision brief when it finishes.

Create synthetic-audience personas to simulate against. Describe who you want to model and get back personas (with ids) you can then target as the 'audience' in aetherya_audit_site, aetherya_test_copy, or aetherya_ask_audience. These are SIMULATED personas (engine-generated), not real people. Returns the created personas inline.

Create a secret upload link to send a client so they can drop creative files (images, video) for pretesting. Returns the url and expiry; treat the url as a secret and share it only with the client. Needs a workspace admin or manager, and the feature must be enabled for the workspace (otherwise a clear 'not enabled' message).

Quote how many simulation sessions a run would cost, and roughly what share of your plan it would consume, before committing to it. Free — this never starts a simulation. Use it to size an audience or shorten a study when headroom is tight.

Fetch the result of an audit started by aetherya_audit_site, using its job_id. Returns the full simulated behavioral findings once complete, or a 'running' status to poll again. Results are SIMULATED predicted behavior, not real users.

Turn a finished study, audit, read or post simulation into a short decision brief: the question, a direct answer, the reasoning with supporting simulated reactions, the risks, and what to do next. This is what you hand a human — use it instead of relaying raw metrics. Reuses the stored brief when one exists, so repeat calls are free (unless language, register or regulated is given: that writes a new brief with a model call). Everything in it comes from SIMULATED behaviour, not real-user research.

Fetch the findings of a run started by aetherya_run_study, aetherya_test_copy, aetherya_audit_site, aetherya_plan_study, aetherya_read, aetherya_simulate_post, aetherya_compare_creatives, aetherya_pretest_video or aetherya_test_flow, using the kind and id from that tool's response. Simulations run longer than a single tool call, so this is the normal way to collect results. All results are SIMULATED predicted behaviour, not real-user data.

List the synthetic audiences (simulated personas) in this workspace: their overall shape (where they are, what they do, how much is actually filled in) plus a sample with ids. These are simulated personas, not real people, and a stored persona pool is usually narrower than the audience a decision is about — read the distribution before targeting by id, and prefer describing the audience you want in aetherya_plan_study when the pool does not match it.

List the research methods this workspace can run — with the exact stimulus fields each one requires — plus remaining plan headroom and simulation-session balance. Call this before aetherya_run_study or aetherya_test_copy to pick a method and check cost headroom. Everything Aetherya runs is a SIMULATION of a synthetic audience, not real-user research.

List the files a client uploaded through an intake link (name, type, size, status, set label, a short-lived download url). The feature must be enabled for the workspace.

List the workspace's recent simulations across studies, instant reads, plans, audits and post simulations, newest first, with the kind and id to pass to aetherya_get_result or aetherya_get_brief. Use it to find earlier work instead of re-running it.

Give Aetherya a decision you need to make, in plain English, and it designs the study, picks or builds the audience, prices it, and runs it — then writes a decision brief. Use this when you do not already know which research method fits; use aetherya_run_study when you do. It can also simulate a whole funnel (an ad leading to a landing page, and which call to action people take there): describe the ad, the page URL and the goals in the objective. It always stops for your approval at a price before spending anything: expect status 'needs_price_confirmation' and answer it with aetherya_confirm_study. Call it again with autopilot_id to check on a plan already running. Results are SIMULATED predicted behaviour, not real-user research.

Assemble a markdown pretest report (how we worked, one section per set, what the results mean, sealed predictions appendix) from finished simulations. Deterministic unless generateFixes is true (then the model drafts fixes and a one-line summary per set, if enabled on the account); otherwise the recommended fixes are left as placeholders for the analyst. Returns the markdown plus claim-lint warnings to resolve before sending. Seals each set's prediction as a side effect. Results are simulated, not real-user data. For a branded PDF, open the same report in the app at /dashboard/ad-lab/pretest and use Download PDF.

Pretest a short video (mp4, mov, webm; max 512 MB, 10 minutes) against a synthetic audience: hook score, attention curve, drop-off points. Uploads the file (video_path on this machine, or video_url), splits it into scenes, then returns status 'needs_price_confirmation' with the quote. The quote exists only after preparing, and the draft is free EXCEPT speech-to-text: when you pass no transcript_srt, preparing charges 0.25 to 6 simulation sessions for transcription up front. Analysis cost is personas x 5 + scenes x 0.5 sessions, minimum 10, max 60 personas. Nothing more is spent until you re-call with accept_sessions >= the quote (pass it up front to skip the pause). If preparing is still running the tool returns 'preparing' with experiment_id, video_id and prepare_job_id: call again with those. Collect with aetherya_get_result kind 'video_analysis'. Results are simulated, not real-user data.

Myrias instant read. Reads 2-5 variants against a census-weighted synthetic population for a market, in seconds, and returns each variant's predicted action propensity, its lift over the control, and which demographic archetypes favour it. A variant can be copy (text), a live page (url), an image (image_path, image_url or image_base64) or a video (video_path). Media reads are single-kind: images or videos cannot be mixed with copy, pages or each other. The first read of a new image takes about 30-45 s and may come back running (collect it with aetherya_get_result). A video is uploaded and prepared first, about 1-2 min. Much cheaper and faster than aetherya_test_copy, which is the deeper follow-up. Counts against the monthly read allowance, not simulation sessions. Results are SIMULATED, not real-user data.

Attach what actually happened to a sealed prediction (append-only) and get the evaluation. creative_comparison actual: {metric:'ctr', values:[{creativeId?|variant?, value, impressions?, clicks?}]}; impressions and clicks let Aetherya record the result for calibration (see calibrationRecorded). video_analysis actual: {threeSecondHoldPct?, biggestDropSec?, watchedFullPct?}. Other kinds: any object.

Run a Research Lab study — pricing sensitivity, message testing, concept testing, focus groups — against a synthetic audience and get a structured verdict with segment breakdowns, objections and representative reactions. Call aetherya_list_capabilities first to pick a method and see the inputs it needs. Results are SIMULATED predicted behaviour, not feedback from real users.

Lock a prediction (a creative comparison ranking, a video analysis, a study or a manual payload) with a SHA-256 hash and timestamp, so it can later be compared with what really happened. Pass source_id to seal a finished simulation, or payload for a manual prediction. Returns the id, hash and sealed payload.

Mint a shareable URL for a completed study, audit or creative comparison so someone without an Aetherya account can read the findings. Use it after aetherya_get_brief when the user wants to send the results to a colleague or client, or post them. The link is PUBLIC to anyone who has it. A study shared without options gets its public link plus a preview card for posting; pass expires_in or a password for a private, expiring link instead.

Run a post (X, LinkedIn, Instagram, Facebook) or email through a synthetic audience and get predicted engagement, sentiment and representative reactions before publishing. Starts the run and waits briefly; collect with aetherya_get_result kind 'post_simulation'. Results are SIMULATED reactions, not real engagement.

Compare 2-5 copy variants — headlines, value propositions, ad or email copy — against a synthetic audience, and get a ranked verdict with predicted action propensity, comprehension and trust per variant, plus the objections each raises. Results are SIMULATED predicted reactions, not feedback from real users.

Simulate people who arrive from an ad (image, video or copy), land on a page, and take one of several exits (for example book a consultation, open the plan form, or leave). Reports the exit split per arm. Pass rewrites to compare a changed ad and page copy against the original on the same audience. The first call quotes the cost and starts nothing; call again with accept_cost true once the user agrees. Collect results with aetherya_get_result kind 'flow'. Results are SIMULATED, not real-user data.

Recompute the hash of a sealed prediction and report whether it still matches the stored one.