Remote MCP · api.sonaloop.com
Sonaloop’s API is a hosted Model Context Protocol server: the same toolkit as the local install — curated persona catalog, persona lifecycle & chat, the governed research loop, councils, hypotheses, surveys and synthesis — exposed at a single endpoint and bound to your workspace. Connect Claude Code, Claude.ai, ChatGPT, Cursor or any MCP host; every tool call runs in your workspace’s data.
| Endpoint | https://api.sonaloop.com/mcp |
|---|---|
| Transport | Streamable HTTP (JSON-RPC 2.0, stateless) |
| Auth | Workspace-bound bearer token · OAuth 2.0 |
| Surface | 164 workspace-user · 327 tools total |
Get started
Three steps from zero to a connected host.
https://api.sonaloop.com/mcp as a custom connector in Claude.ai / ChatGPT.Get started
Call the live endpoint straight from this page. It is same-origin with /mcp, so requests run in your own workspace — no proxy, no setup. Sign in and your token loads itself.
// Run a request to see the live JSON-RPC response.Calls run live in your workspace. Reads (tools/list, list_*, get_*, search) are safe to poke at; write tools (record_*, start_*) persist real data.
Connect
Every request authenticates itself — the endpoint is stateless, so there is no session to share across tenants. Two ways to present credentials:
A workspace-bound token (an HMAC-signed claim, purpose mcp), self-service on your workspace page. Send it as an Authorization: Bearer <TOKEN> header. The token carries the workspace and the tool profile; membership is re-checked live on every call, so revoking access takes effect immediately.
OAuth-capable hosts (Claude.ai connectors, ChatGPT Apps) connect without a copy-pasted token. An unauthenticated request answers 401 with a WWW-Authenticate challenge that points at the protected-resource metadata (RFC 9728); the host discovers the authorization server, runs the consent flow, and is issued the same kind of access token. Dynamic client registration and PKCE are supported.
Connect
The same server, role-scoped surfaces — chosen by a claim baked into your token. Normal users get the curated workspace surface; admins can explicitly mint a full token.
The curated, task-shaped surface: catalog browse/pull, persona lifecycle & chat, the governed loop, councils, hypotheses, decisions, surveys, synthesis, and the key cloud automations. Recommended for Claude Code, Claude.ai & ChatGPT.
The entire server, including methodology registration, prototype internals, calibration, eval critics and the low-level substrate. Explicit admin use only.
Both one-liners live on your workspace page; the profile rides the token, so the claude mcp add command is identical — only the token differs.
Connect
The endpoint speaks Streamable HTTP, so any compliant MCP host connects with the same URL and bearer token.
One command — use a Workspace user token for normal work.
Add a custom connector pointing at https://api.sonaloop.com/mcp. OAuth-capable hosts run the consent flow automatically; otherwise paste a Workspace user token. In ChatGPT Deep Research, the search & fetch tools are what the researcher calls.
Any host with Streamable-HTTP MCP support: same URL, same Authorization: Bearer header.
Protocol
Everything is JSON-RPC 2.0 over a single POST to https://api.sonaloop.com/mcp. The endpoint is stateless and returns JSON, so each request stands alone (include both application/json and text/event-stream in Accept). The three methods you need:
| POST | initialize | Handshake; advertises protocol version & capabilities. |
| POST | tools/list | The tools your token’s profile can see, with JSON Schemas. |
| POST | tools/call | Invoke a tool by name with arguments. |
Protocol
Two tools are always present, in every profile, because ChatGPT Deep Research requires them by name. search returns matching records (personas, projects, councils, syntheses…) as id + title + url; fetch returns one record’s full content by id. Together they let a researcher host read your workspace without learning the rest of the surface.
Protocol
Transport-level auth failures are HTTP errors with a JSON body that explains the problem and links to your token. Everything past the auth wall is delivered in-band as an MCP tool result with isError: true — a denied or gated tool never breaks the transport.
| 401 | Invalid, expired or missing bearer token — carries the OAuth discovery challenge. |
| 403 | Membership in the token’s workspace was revoked. |
| 503 | MCP transport not started (misconfigured host). |
Reads and exports always pass — your data is never held hostage. When a workspace’s plan lapses, only write tools answer the in-band billing note; reads keep working.
Tool reference
327 tools across 30 domains, auto-generated from the live server. Each is tagged by the smallest profile it appears in.
add_task | Workspace user | Insert a task into the plan (shape the breadth): bucket analyze|act|verify, a capability tag, consumes (DAG edges), optional gates. Returns the create | |
archive_project | Admin | Explicitly archive one project without deleting evidence. Active runs fail closed; recover or stop them first. Reuse the same operation_id on transpor | |
assess_progress | Workspace user | Record an evidence-backed assessment of progress toward the HMW goal. `delta` is a free host judgment (never a number); a non-binding coverage snapsho | |
assess_project | Workspace user | Project-level meta-assessment (read-only, computed — no LLM verdict): coverage, open evidence gates, open questions, a saturation hint, structural gap | |
brief_cohort_preflight | Workspace user | Gather the versioned server-owned cohort gate: per-persona memory/event/evidence depth, source/age provenance, deterministic hypothesis/profile lexica | |
brief_product_understanding | Workspace user | Gather the evidence-bound PRODUCT UNDERSTANDING preflight contract for a Reaction Test. Inspect and attach the actual app/screens first; do not fill u | |
checkpoint_step | Workspace user | Checkpoint a completed step (task_id, bucket, key, evidence ids, 1-line summary). Governed projects require the dispatch_token issued by run_step. Nor | |
complete_task | Workspace user | Mark a ready task done. Verify tasks are gate-checked (breadth + gate judgment + artifacts/ sessions) and rejected until satisfied. Governed runs must | |
export_plan_md | Admin | Render the plan as a human-readable, bucketed plan.md (analyze/act/verify + status + gates). | |
finish_run | Admin | Stop/cap a run, or validate an already complete run. `finished` fails closed while plan, finish work, or the two persisted completeness-critic passes | |
get_cohort_preflight | Workspace user | Read the current or historical cohort gate, its thresholds/features, remediation lineage and any persisted report limitation caused by an explicit ove | |
get_plan | Workspace user | The project's research plan (analyze/act/verify task DAG + evidence refs + judgments). | |
get_product_understanding | Workspace user | Read the current Product Understanding artifact, its immutable version history and capability posture counts. Pass version_id to inspect an older vers | |
inject_work | Workspace user | Turn one critic `missing` item {kind, what, ...} into a real plan task/open-question (the driver does this automatically; exposed for manual gap-filli | |
iterate_task | Admin | Open the NEXT iteration round on a done-or-ready task with a `loop_back` target (HOST-judged — the engine never loops on its own): clones the loop-bac | |
link_evidence | Workspace user | Attach an evidence ref (kind=council|synthesis|artifact|session, id) to a task (usually the act task whose run-council/scaffold/session just produced | |
next_action | Workspace user | The ready task FULLY loaded for a lean autonomous loop: analyze→grounding (prior syntheses + open questions); act→the consumed frame's framed question | |
project_health | Workspace user | Read the canonical Job health projection: running/stalled/engine-finished/unverified, the first unmet invariant, Product Understanding coverage, evide | |
record_cohort_preflight | Workspace user | Persist an immutable cohort-integrity result. Status is exactly pass|needs_deepening| needs_reselection|overridden. Failed gates inject required plan | |
record_critic_round | Workspace user | Bind one persisted completeness-critic report to its deterministic run dispatch. Retry the same report id + key safely; passed/missing is derived from | |
record_frame | Workspace user | Discharge an ANALYZE frame task: author research questions + hypotheses grounded in cited persona memory (>=1 question + >=1 memory_ref). For a govern | |
record_manifest_product_understanding | Workspace user | Weak-host-safe Reaction Test Product Understanding. First execute every serialized inspect_reaction_test_screen action returned by the same run. Then | |
record_product_understanding | Workspace user | Persist one immutable Product Understanding version. Every capability must declare one posture: observed_present|observed_absent|inferred|unknown. Obs | |
resume_project_run | Workspace user | Resume exactly the named ACTIVE run. This never creates a project/run, reopens a terminal run, or marks anything finished. It verifies project/run/ope | |
run_journal | Workspace user | The run's journal (steps + critic rounds + cursor + status) — the source of truth for resume. | |
run_step | Workspace user | The ESV driver's brain (deterministic). Returns the next dispatch to execute: {kind: analyze|act|verify, step_id, key, dispatch_token, next_action, di | |
select_reaction_test_cohort | Workspace user | Repair an empty Reaction Test cohort with at least two EXISTING persona IDs. Use list_personas or catalog_search/catalog_recommend -> catalog_pull fir | |
start_project | Admin | THE ENTRY POINT. Create a project + seed its research plan (methodology -> analyze/act/verify scaffolding; none -> one dischargeable root frame task); | |
start_run | Admin | Create (or resume) the run object — the SINGLE entry to the governed loop. Returns the run + its journal. For initial creation pass a stable operation | |
supersede_project | Admin | Explicitly declare that project_id supersedes another project in this workspace. Preserves every artifact, records old→new lineage, and marks only the |
add_artifact | Admin | Bring a REAL artifact into a project's council pool so personas react to what is ACTUALLY there — a live URL/website, a prototype link (kind='prototyp | |
brief_ask | Admin | Gather one persona's loaded context (SOUL + recent events + task-keyed memory) so you can author an honest, in-character answer. No server-side genera | |
brief_council | Workspace user | Gather a council. A council is scoped to a research project, so `project_id` is REQUIRED (create one first with create_research_project; personas are | |
brief_head_to_head | Workspace user | Gather a HEAD-TO-HEAD (X vs Y) — run the panel on a DIRECT comparison of two (or more) concrete options and get a reasoned, segmented preference, NOT | |
brief_price_ladder | Admin | Gather a PRICE LADDER (pricing Job protocol — willingness-to-pay): a FIXED ascending ladder of price points every persona reacts to, one van-Westendor | |
brief_red_team | Workspace user | Gather a RED-TEAM (falsification) — run the panel to ATTACK the idea instead of flattering it ("why would this segment NOT adopt / NOT pay / churn?"), | |
brief_synthesis | Workspace user | GATHER an ordered chain of councils (their exec_summaries/votes) so you can author a cross-council synthesis (arc, gesamtbild, recommendations, positi | |
delete_artifact | Admin | Remove an artifact (by id or label) from a project's pool. | |
export_council_session | Admin | Export one council session as a document (md|json) for sharing. | |
export_synthesis | Admin | Export a report (synthesis). format: `md`|`json` returned inline · `pdf`|`pptx` rendered as a presentation-grade file and attached to the owning proje | |
export_synthesis_html | Admin | Export a report (synthesis) as a SHAREABLE read-only static HTML bundle — `data/export/share/<token>/index.html`: the exact inspector document minus a | |
get_artifact | Admin | One artifact (by id or A/B label) with its full captured snapshot. | |
get_council | Workspace user | Fetch one council session by id (prompt, turns/statements, votes, summary). | |
get_head_to_head | Workspace user | Fetch one head-to-head result by session id — its options, per-persona preferences, the deterministic aggregate (preference + margin + abstentions + s | |
get_price_ladder | Admin | Fetch one price-ladder result by session id — the ladder, the raw per-persona/per-rung banded responses (persona, price point, band, quote) and the de | |
get_red_team | Workspace user | Fetch one red-team result by session id — its stance, adversarial roles, per-persona objections and the deterministic case-against (themes grouped by | |
get_synthesis | Workspace user | Fetch one report (synthesis) by id — its findings/sections/scope and metadata. | |
list_artifacts | Workspace user | List every artifact ingested into a project (id, label A/B/…, kind, url, capture status). | |
list_councils | Workspace user | List council sessions (id, prompt, persona count, votes), newest first. Paginated per the shared convention (docs/pagination.md): `limit` (default 25) | |
list_syntheses | Workspace user | List all reports (syntheses) — id, title, scope, date — for browsing. | |
price_ladder_analysis | Admin | The analytics shape of a recorded price ladder: acceptable-price range + cliff points, overall and one row per segment (pricing protocol step range_an | |
record_council | Workspace user | Persist a host-authored council. Shape it by what you pass (the UI derives the mode): DISCOVERY = `questions` (open user-research questions), NO propo | |
record_head_to_head | Workspace user | Persist a host-authored HEAD-TO-HEAD (stored as a CouncilSession with a `head_to_head` block). Pass the labelled `options`, each persona's `preference | |
record_price_ladder | Admin | Persist a host-authored PRICE LADDER (stored as a CouncilSession with a `price_ladder` block). `responses` is the structured willingness-to-pay payloa | |
record_red_team | Workspace user | Persist a host-authored RED-TEAM (stored as a CouncilSession with a `red_team` block). Pass the per-persona `objections` ([{persona_id, theme (a short | |
record_synthesis | Workspace user | Persist/UPDATE a host-authored synthesis. A synthesis is DECOUPLED from councils: `council_ids` is OPTIONAL (may be empty — affinity over notes, a syn | |
suggest_finding_kinds | Admin | SUGGESTED Finding kinds (summary/key_problem/pain_solver/open_question/recommendation/ cluster/segment/shortlist/ranking/pain_point) for a `findings` | |
suggest_stances | Admin | The CANONICAL stance vocabulary — call this before authoring statement stances, votes, or head-to-head/red-team reactions. Every stance is {value -2.. |
brief_prototype_session | Admin | GATHER persona context + how-to-drive + anti-steering before a persona uses the app. | |
delete_prototype | Admin | Delete a prototype artifact record (files on disk are kept). | |
get_prototype | Admin | One prototype artifact by id or slug. | |
list_proto_sessions | Admin | List live browser sessions. | |
list_prototypes | Admin | List registered prototype artifacts (optionally for one project). | |
proto_act | Admin | Act on the latest snapshot: {type: click|type|select|scroll|key|wait, ref?, text?, value?}. | |
proto_close | Admin | Close a browser session. | |
proto_open | Admin | Open a real running app in a headless browser session; returns {session_id, snapshot}. Without the optional browser harness this degrades gracefully ( | |
proto_read | Admin | Re-read the current snapshot of a session. | |
record_prototype_session | Admin | Persist a persona's grounded prototype use as an experience + memory + artifact; rejects claims with no matching observed state in the session log. `r | |
register_prototype | Admin | Register a hand-authored app under prototypes/ as a runnable artifact (fidelity tag, e.g. lofi|midfi|hifi). | |
register_remote_prototype | Workspace user | Register a hosted HTTP(S) app as a first-class prototype without fetching or executing it. Optionally pair the concept `note_id`. In a governed run pa | |
run_prototype | Admin | Start the app on an ephemeral localhost port; returns {url, pid}. Local-only. | |
scaffold_prototype | Admin | Generate a real, minimal, runnable web app from a host-authored concept and register it. The app is genuinely clickable (real DOM) for Playwright. The | |
stop_prototype | Admin | Stop a running prototype. |
brief_usability_session | Admin | GATHER persona context (SOUL + state + task-keyed memory) + anti-steering framing + the friction vocabulary + the subject's context (prototype how-to- | |
get_session_funnel | Admin | Aggregate ALL usability sessions of one subject into a step-indexed funnel: per step the entered/continued/dropped counts plus the drop reasons — the | |
get_usability_session | Workspace user | One recorded usability session by id — the full replayable trace (steps + outcome + statements). | |
list_usability_sessions | Workspace user | List recorded usability sessions, optionally filtered by project, persona and/or subject ({kind?, id?|url?}). | |
record_usability_session | Workspace user | Persist a host-authored usability session — the durable, REPLAYABLE trace (the session is the deliverable). `steps` is the ordered dual timeline: {ind | |
suggest_friction_levels | Workspace user | The CANONICAL per-step friction vocabulary for usability sessions — call this before authoring step friction. Each item is {term, value, label_key, al |
record_actuation_gate | Admin | The fidelity-vs-theater head-to-head: compare a rung-1 artifact walkthrough against a rung-2 live drive of the SAME flow on derived evidence-quality d | |
walk_open | Admin | Open a LIVE walkthrough session on a real SaaS URL under the WalkPolicy safety contract (docs/live-walkthrough-safety.md): origin allowlist (off-origi | |
walk_own | Admin | Rung 2 — drive a live surface WE OWN: pass `prototype_id` (the scaffolded app is started on localhost) or a loopback/declared-staging `url` (SONALOOP_ | |
walk_policy_defaults | Admin | The safe default WalkPolicy walk_open applies when none is passed — origin-locked to the opening URL, ALL denylist categories enabled (payment/destruc |
attach_survey_evidence | Admin | Loop the imported REAL responses back onto a persona as Evidence (source_type='survey') for calibration — a compact JSON of the per-question aggregate | |
brief_survey | Workspace user | GATHER everything needed to author a survey that is answerable against the graph: the project's open questions, its contested findings (councils whose | |
export_survey | Admin | Render the survey as a SENDABLE, self-contained static HTML form (spa-min template) — works from file://, host it anywhere. Submissions produce a JSON | |
get_survey | Workspace user | One survey by id or slug — the instrument document + its live response_count. | |
import_survey_responses | Workspace user | Ingest a batch of REAL responses — a JSON list (the export form's payload shape: {respondent_key?, submitted_at?, answers: [{question_id, value}], sou | |
list_surveys | Workspace user | List surveys (optionally per project), each with its live response_count. | |
record_survey | Workspace user | Persist a host-authored survey. `questions` = [{id?, text, kind: single|multi|scale|text, options (>= 2 for non-text), stance_mapped (scale only)}] — | |
survey_results | Workspace user | Per-question aggregates of the imported responses — and for stance_mapped questions the PREDICTED-VS-ACTUAL strip: the persona stance distribution fro |
brief_hypothesis | Workspace user | GATHER what is worth betting on: the project's contested findings (councils whose statements span support AND opposition), the predicted behaviors rec | |
drop_hypothesis | Admin | Retire an OPEN bet without scoring it (the question became moot, the metric unmeasurable). Dropped bets stay on the record but never enter the scoreca | |
eval_scorecard | Admin | Aggregate the hit-rate across RESOLVED hypotheses (per project, or global with a per-project breakdown) and write the sim-vs-reality calibration recor | |
get_hypothesis | Workspace user | One hypothesis by id — the bet, its prediction, and (once resolved) the recorded result with both raw values. | |
list_hypotheses | Workspace user | List hypotheses (optionally per project and/or status: open|validated|refuted|inconclusive|dropped). | |
record_hypothesis | Workspace user | Persist a host-authored hypothesis with status=open — the bet stamped BEFORE reality answers. `prediction` = {metric, expected_value (+tolerance?) OR | |
record_hypothesis_result | Workspace user | Attach the REAL-WORLD observation and flip the status. `source` is a Ref that must RESOLVE: a survey's imported responses ({kind:'survey', id}), attac |
get_decision | Workspace user | One decision record by id — what was decided, the evidence cited (based_on), the rejected alternatives (+ why-not notes), and the supersede links (bot | |
list_decisions | Workspace user | List decision records (optionally per project and/or status: proposed|adopted|superseded). | |
record_decision | Workspace user | Persist a host-authored decision record — "we decided X, based on syntheses A and B, rejecting alternative C". `based_on` = Refs to the evidence it re | |
update_decision | Admin | Flip a decision's status (proposed|adopted) — or supersede it: `superseded_by` names the SUCCESSOR decision and records the link in BOTH directions (t |
add_to_section | Admin | Add node ids to a section's membership (validated against the project graph). | |
create_note | Workspace user | Create a lightweight NOTE node — the ONE note entity (from a raw observation to a worked-out solution idea; there is no separate 'concept'). For a sol | |
create_section | Admin | Create a labeled overlay grouping of graph nodes (e.g. 'Initial user research', 'Problem exploration'). `member_ids` must reference real nodes (counci | |
delete_note | Admin | Delete a note node from the project. | |
delete_section | Admin | Delete a section. Member nodes are kept (reference, not containment). | |
derive_sections | Admin | Auto-organize: derive persisted SECTION overlays from the plan — one per methodology phase (fan + its converging waist; label from the step name), a P | |
export_section | Admin | Self-contained export of a section (md|json): its members' summaries, for a downstream agent. | |
get_section | Admin | Get one section by id. | |
get_section_members | Admin | Resolve a section's members into {kind,title,summary,href} records (section-scoped view). | |
list_notes | Workspace user | List a project's note nodes in creation order. Paginated per the shared convention (docs/pagination.md): `limit` (default 25) + opaque `cursor`; answe | |
list_sections | Admin | List a project's sections (ordered). | |
remove_from_section | Admin | Remove node ids from a section's membership (nodes themselves are untouched). | |
reorder_sections | Admin | Set the display/outline order of a project's sections. | |
scaffold_synthesis | Workspace user | Seed a project REPORT outline from the project's phases so the conclusion hand-off is one author step (brief_synthesis_section → record_synthesis_sect | |
set_note_data | Admin | Merge keys into a note's `data` — e.g. set a concept note's `prototype_id` once you build it, so the completeness critic stops flagging it as un-proto | |
set_section_members | Admin | Bulk-set a section's membership — the 'promote this cluster into a named section' move. | |
suggest_section_kinds | Admin | Suggested section kinds + presentation (data-driven; adopt/tweak/invent). | |
update_section | Admin | Update a section (title/kind/parent_id/order/presentation/note/member_ids). |
available_project_icons | Admin | Existing regular icons that Projects/Jobs can choose at initialization or edit time. | |
brief_synthesis_outline | Workspace user | GATHER the whole project graph + study content so you can author the project REPORT outline. | |
brief_synthesis_section | Workspace user | GATHER one section's source studies (+ councils) so you can author it with citations. | |
create_research_project | Admin | Create a research Project: a themed GRAPH of studies (syntheses). Distinct from the memory get_project (a persona's own work project). `icon` may be a | |
delete_council | Admin | Delete a council session. | |
delete_persona | Workspace user | Permanently remove a persona only with the exact token from persona_deletion_impact(persona_id). Re-preview after any persona/project change. | |
delete_research_project | Admin | Delete a project and its project-scoped outputs; personas and their memory remain. | |
delete_synthesis | Admin | Delete a synthesis (study) and detach it from any project graphs. | |
generate_project_icon | Admin | Create a fitting custom SVG icon for a Project/Job from its title/goal plus an optional prompt, save it as an SVG file, and assign it. | |
get_project_graph | Admin | The core navigation call: nodes (studies + theme tags + sentiment), typed edges, themes, build order, and open questions for one research project. | |
get_research_frontier | Admin | The anti-explosion surface: the project's still-open questions + structural notes. | |
list_research_projects | Workspace user | List research projects (graph containers) with study/edge/theme counts. | |
persona_deletion_impact | Admin | Preview persona deletion: memory removed, project detachments, preserved historical artifacts, and an exact state-bound confirmation token. This call | |
record_open_questions | Admin | Promote open questions raised by a study into first-class graph nodes. | |
record_synthesis_outline | Workspace user | Persist the host-authored report outline (sections derived from the graph). A body-empty scaffold is reused; pass report_id to target a draft, reuse o | |
record_synthesis_section | Workspace user | Persist one authored report section. `content`: {markdown, citations:[{study_id|council_id}], figures:[…]}. Figures can embed a chart — {kind:'chart', | |
set_project_icon | Admin | Replace a Project/Job icon. Use `icon=<existing name>`, `randomize=True`, or pass a custom `svg` string; custom SVGs are sanitized, saved under data/p | |
suggest_chart_kinds | Admin | Which report CHART to use when (bar, pie, stacked_bar, diverging_bar, gauge, dot_plot, heatmap, line, effort_impact) + each one's author payload shape |
get_job_preset | Workspace user | One Job preset by stable taxonomy id (e.g. 'positioning'): framework + framework_options + formats (each with its brief/record tools) + coverage. A st | |
get_result_schema | Admin | One domain-neutral result schema by id, e.g. stimulus_reaction.v1. | |
list_job_presets | Workspace user | The Job presets — one per named research Job (positioning, pricing, jtbd_demand, ideation_hmw, continuous_discovery, churn_reasons), each a recipe car | |
list_result_contracts | Admin | List the output contracts declared for Jobs and methodologies. | |
list_result_schemas | Admin | List domain-neutral result schemas plus registry validation errors. | |
project_result_contract_state | Admin | Show which expected result schemas are recorded or still missing for a project. | |
record_job_outcome | Admin | Persist one project-owned schema outcome as a job completion milestone. | |
result_contract_for_job | Admin | The expected result schemas for one Job. | |
result_contract_for_methodology | Workspace user | The expected result schemas a methodology usually produces. | |
set_project_result_schemas | Admin | Set the project-owned result schema contract that must be satisfied before the job is done. | |
sharpen_question | Admin | Turn a FUZZY goal into a well-formed study — deterministically (no server-side text-LLM). Returns the well-formed-study checklist (decision at stake, | |
start_job_study | Admin | Start a study FROM a Job preset: seeds the plan through the preset's default Framework (or any `framework` override — presets never constrain) and sta |
brief_next | Workspace user | GATHER what the plan's ready frontier needs now: the primary ready task (+ the full ready set), its bucket/capability, consumed frames, and unmet gate | |
describe_framework | Workspace user | One Framework's plain-language description by stable id (e.g. 'double_diamond'): {id, name, what, when, stages:[{id, name, what}]}. The structured com | |
get_methodology | Workspace user | The full constellation spec for one methodology (steps, tags, consumes, produces, requires). | |
list_frameworks | Workspace user | The Frameworks (the methodologies that seed a study's plan) in PLAIN LANGUAGE, as one clean list the user — and the website / job presets — can read: | |
list_methodologies | Workspace user | List available methodologies (built-in + user-defined) and their step keys. | |
park_evidence | Workspace user | Explicitly park evidence that should remain visible but should NOT flow into a downstream gate/decision. Use this instead of leaving produced evidence | |
record_judgment | Workspace user | Record an evidence-backed LLM gate judgment on a plan TASK (usually a verify task). `gate_tag` is a FREE tag (e.g. divergence_complete, or whatever th | |
register_methodology | Admin | Register a USER-DEFINED methodology — author your own constellation and it becomes a Framework any study can run through (start_project(methodology=<k | |
set_project_methodology | Workspace user | Bind an existing research project to a methodology by (re)seeding its plan from the constellation. The plan is the single engine; drive it via the pla | |
suggest_artifact_types | Admin | SUGGESTED artifact-type tags for produces.artifact_type / requires.*_tags (matched by tag-equality, no string is special-cased). Recommendations only. | |
suggest_capabilities | Admin | SUGGESTED capability tags (explore/cluster/decide/build/test/synthesize, …) for a step's `tags`. Recommendations only — adopt, tweak, or invent your o | |
suggest_methodologies | Workspace user | SUGGESTED whole-constellation templates to copy and adapt (the registered methodologies + any extra templates). Tags are free; nothing here constrains | |
suggest_roles | Admin | SUGGESTED role tags for a step's produces.role. Recommendations only. | |
unpark_evidence | Admin | Correct a prior parking decision for exact refs and scope. The evidence becomes gate-eligible again while the plan retains an audit record of the corr |
assess_coverage | Admin | Coverage / diversity check over a study's PERSONA SET — a deterministic analysis that flags when the panel is too narrow to be trustworthy (a homogene | |
attach_evidence | Workspace user | Attach a real-world SOURCE (doc/url/note) to a persona to ground its claims. | |
begin_persona_build | Workspace user | Start or idempotently resume the governed profile→grounding→memory→critic lifecycle. Execute the returned dispatch, then call persona_build_step. | |
begin_persona_enrichment | Workspace user | START HERE when the user wants to adopt hobbies, routines, relationships or concrete private/work experiences into an existing persona. Optionally loa | |
brief_persona | Workspace user | Gather the prompt + frame to AUTHOR one persona profile from a source description. You write the profile JSON from `instructions`, then call record_pe | |
brief_persona_memory_onboarding | Workspace user | Plan the gather→author→write-back sequence that turns a static persona profile into a critic-checked lived-memory baseline. No memory is fabricated by | |
export_persona | Admin | Export one persona (profile + SOUL/memory) as json/markdown. | |
generate_avatar | Workspace user | Generate (or regenerate) the persona's avatar image — needs OPENAI_API_KEY. Optionally pass up to four personas whose existing portraits define the sh | |
get_persona | Workspace user | Full persona record + recent calendar/experience/pain points. | |
get_persona_build | Workspace user | Inspect one resumable persona build and its current dispatch/readiness. | |
get_persona_context_snapshot | Workspace user | Re-open one immutable persona/task context exactly as it was prepared. | |
get_persona_soul | Admin | The persona's SOUL.md (authoritative identity + grown drift). | |
list_persona_builds | Workspace user | List the governed build history of one persona. | |
list_persona_context_snapshots | Workspace user | Lean history of frozen task contexts for one persona. | |
list_personas | Workspace user | Lean one-line overview of personas (slug/name/age/role/segment) — drill in with get_persona for the full profile. Pass compact=False for full profiles | |
persona_build_step | Workspace user | Re-assess durable outputs and advance a persona build to its next exact tool. | |
persona_readiness | Workspace user | Structural readiness of one persona: profile specificity, independent grounding, lived events/facts, calendar continuity and authored capabilities. | |
persona_task_readiness | Workspace user | Read-only readiness for one exact assignment: global quality plus relevant lived memory, independent grounding, cohort membership and capability rung. | |
prepare_persona_agent_context | Workspace user | Build the launch context for a persona subagent (SOUL + state + recent events). | |
prepare_persona_for_task | Workspace user | Freeze the exact SOUL, memory cutoff, loaded refs, capabilities and limitations used for one assignment. Re-open later with get_persona_context_snapsh | |
preview_persona_update | Workspace user | Validate a persona patch without writing. Returns its field diff, affected artifact counts, history guarantees and — for identity-changing fields — a | |
record_persona | Workspace user | Validate + persist the persona profile you authored from brief_persona. This is the create path (no server-side text generation). | |
record_persona_enrichment | Workspace user | Validate and persist one host-authored persona enrichment: a MINIMAL routine profile patch plus up to eight concrete dated lived days. Identity change | |
record_persona_voice_check | Workspace user | Persist the semantic authenticity verdict without retaining the raw candidate text. A green check requires all four dimensions >=4 and no open issue. | |
refresh_persona_from_source | Workspace user | Refresh a persona from where it came from. Catalog-pulled personas re-pull from their recorded catalog ref (drift-safe: a locally modified profile is | |
suggest_tech_comfort | Workspace user | The CANONICAL tech-comfort vocabulary for a persona's capability profile (capabilities.tech_comfort) — call this before declaring/patching one. Each i | |
update_persona | Workspace user | Apply a host-authored MINIMAL patch to a persona's profile; never replay the full profile and never call brief_persona for edits. Records a revision w | |
validate_persona_output | Workspace user | Gather a semantic authenticity check for persona-authored wording. Returns the exact persona context and warning signals; the host authors the verdict | |
view_persona_avatar | Admin | Return the persona's actual PNG portrait. Use this only when a report, design, canvas or document needs the visual; use get_persona for profile text. |
catalog_pull | Workspace user | Pull catalog personas (by slug and/or archetype `pack`) into the CURRENT store — profiles, SOUL/MEMORY, lived memories, avatars — with `provenance.cat | |
catalog_recommend | Workspace user | Deterministic, explainable persona-SET recommendation over the catalog (no LLM): spec = {keywords?: [...], facets?: {facet -> [values]}, n?: int, seed | |
catalog_search | Workspace user | Browse the curated persona catalog (github:jhoetter/sonaloop-data): slugs, names, roles + a facet summary over the filtered set. `query` is a free-tex | |
catalog_status | Workspace user | The `git fetch && git status` of the catalog: for every catalog-pulled persona in the CURRENT store (optionally filtered by `persona_slugs`), report f |
begin_persona_month_simulation | Workspace user | START HERE when the user asks to simulate one calendar month such as 2026-08. Returns all context and the exact host-authored bundle contract in one c | |
brief_consolidation | Workspace user | GATHER a simulated day + known entities. Returns instructions for you to author memory_deltas (entities/facts/threads/event_links); then record_memory | |
brief_day | Workspace user | GATHER context for planning ONE day (active projects, open threads, recall, world). Returns instructions for you to author a day plan; then put_day_pl | |
brief_digest | Workspace user | GATHER a period for a consolidated digest (replaces hardcoded reflections). | |
brief_month | Workspace user | GATHER context to author a whole month bundle (period plan + sample days + digest), chained on the prior month. Then record_month_bundle. | |
brief_period | Workspace user | GATHER context for a week|month|quarter|year plan, incl. candidate sample days. Author a period plan (with sample_days) then put_period_plan. Trends o | |
export_persona_memory | Admin | Explicitly write the rendered MEMORY.md projection to disk. | |
extract_pain_points | Admin | Surface a persona's pain-point observations over a date range. | |
get_activity | Workspace user | Fetch one simulated activity (block) by id. | |
get_calendar | Workspace user | A persona's calendar events for one day. | |
get_calendar_period | Workspace user | A persona's calendar for a day|week|month|year view — LEAN event rows (id/timestamp/event_type/task/tool/summary, capped to the newest 400 with an in- | |
get_current_state | Workspace user | A persona's live state — what they're doing now / at a given time. | |
get_day_plan | Admin | Fetch the stored day plan for a persona on a given date. | |
get_open_loops | Admin | A persona's unresolved threads / open loops (filter by status). | |
get_period_plan | Admin | Fetch a stored period plan (week|month|quarter|year) for a persona. | |
get_persona_memory | Admin | Pure read of MEMORY.md content: active projects, threads and digests. | |
get_project | Workspace user | Full fact/status timeline of one project (use `as_of` for how it looked then). | |
get_state_at | Admin | Time-travel: entities + facts + open threads + world valid at a given date. | |
get_timeline | Admin | Chronological facts + experience events for a persona over a date range (optionally one entity). Capped to the newest `max_facts`/`max_events` rows — | |
list_active_projects | Workspace user | Compact list of the persona's open projects with status + open-loop counts. | |
list_digests | Admin | List a persona's consolidated digests (optionally filtered by scope). | |
list_period_plans | Admin | List a persona's period plans (optionally filtered by scope). | |
put_day_plan | Admin | Persist the day plan you authored from brief_day. | |
put_digest | Workspace user | Persist + embed the digest you authored from brief_digest. | |
put_period_plan | Workspace user | Persist a period plan (its sample_days drive which days you simulate concretely). | |
recall_memory | Admin | Hybrid (semantic + keyword/entity + recency + importance) recall over episodes, facts, digests, threads. USE when you want to check if the past has so | |
record_day | Workspace user | Persist a host-authored SINGLE day end-to-end (put_day_plan -> simulate the authored blocks/activities -> optional consolidation). See brief_day's `da | |
record_memory_deltas | Workspace user | Persist host-authored memory deltas: resolves/dedupes entities, writes bi-temporal facts (invalidating superseded status), opens/resolves threads, lin | |
record_month_bundle | Workspace user | Persist a host-authored month bundle through the full loop (plan->sample days-> simulate->consolidate->digest->embed). | |
resolve_entity | Admin | Resolve a free-text mention to an existing entity (dedup), or null if new. | |
search_entities | Admin | Find a persona's memory entities by kind and/or name substring. | |
summarize_persona_period | Workspace user | Gather a persona's experience over a date range (optional lens) for summarisation. |
brief_cohort_critic | Admin | GATHER compact per-persona records across the cohort so you can judge which personas fall OUT of the cohort's range (relative outliers / clones). Then | |
brief_completeness_critic | Workspace user | GATHER a computed exhaustiveness snapshot for an INDEPENDENT critic: coverage + the generative breadth_candidates (segments/angles/concepts/risks/fide | |
brief_eval_critic | Workspace user | GATHER source+SOUL+sampled activities+arcs for a semantic critique. Author a verdict (anti_steering/in_character/dialogue/arc/mundane 0-5 + flags) the | |
brief_evidence_check | Admin | GATHER profile claims + attached evidence to validate synthesis against reality. | |
brief_persona_revision | Admin | GATHER evidence (digests/facts) to propose SLOW identity drift. Change is the exception. | |
cohort_memory_depth | Admin | How deep is the cohort's simulated memory (avg facts+events/persona)? A thin cohort should be deepened (simulate-cohort) before a run so councils are | |
evaluate_cohort_diversity | Admin | Structural bulk-generation gate: flag near-duplicate personas and implausibly uniform cohorts (Jaccard over segment/role/pains/goals/tools). No author | |
evaluate_simulation | Admin | Run the quality harness (uniformity, repetition, continuity, project movement, consistency, anti-steering). Returns green/warn/red — the measurable 't | |
evaluate_simulation_full | Workspace user | Combined 'top' verdict: structural harness + latest LLM critic (definition v2). | |
get_language | Workspace user | Read the active content language (host-authored text) and UI language. | |
get_world_context | Workspace user | The shared world context (macro facts personas live in) valid at a given date. | |
list_memory_anomalies | Admin | Flagged memory anomalies (contradictions / integrity issues), optionally per persona. | |
list_persona_revisions | Admin | The history of evidence-backed identity revisions for a persona. | |
record_cohort_critic | Admin | Persist the host-authored cohort critique (outliers + cohort_note) as an eval report + an anomaly per flagged outlier persona. | |
record_completeness_critic | Workspace user | Persist the independent critic verdict {scores, passed, missing[{kind,what,why, suggested_action}], rationale, evidence_refs}. Bind it to the run and | |
record_eval_critic | Workspace user | Persist the host-authored critic verdict; flags low dimensions + items as anomalies. | |
record_evidence_check | Admin | Persist provenance verdict: confirmed/contradicted/unsupported; flags contradictions. | |
record_persona_revision | Admin | Persist evidence-backed identity drift (re-renders SOUL); source identity preserved. | |
score_run | Admin | Persist a RunScore (critic rubric scores + finish + novelty + groundedness + memory depth) so output quality is tracked over time — a regression signa | |
set_language | Workspace user | Set the content language (de|en) for generated text and/or the web UI language. By default content is authored in the language the user writes in; use | |
set_world_context | Workspace user | Set exogenous backdrop facts (season, regulation, market...). Not shared persona knowledge. |
brief_presentation | Admin | Gather the report, cohort, evidence, visuals, result schemas and the selected methodology's data-authored deck profile. Author a presentation_plan.v1 | |
get_design_handoff | Workspace user | Read a provider-neutral research-to-design bundle for Figma, canvas, code or document MCPs: evidence-linked findings/voices, decisions, concepts, mock | |
record_presentation_plan | Admin | Persist an evidence-linked, brand-neutral presentation plan with core slides, appendix and speaker notes. The deterministic PPTX export reuses this re |
admit_remote_screenshot | Workspace user | Secure Remote-MCP screenshot admission. Upload bytes directly as canonical base64; there is deliberately NO URL or filesystem-path input. The server b | |
attach_asset | Admin | Attach a file/image/screenshot to a project as citable evidence. Pass EITHER `path` (a local file, e.g. a screenshot you just captured) OR `content_ba | |
attach_prototype_shot | Admin | Screenshot a registered prototype (Playwright) and attach the shot to the project as image evidence — the capture path for artifacts produced during t | |
get_asset | Workspace user | One asset record (by id or filename) — includes the text excerpt for documents. | |
inspect_reaction_test_screen | Workspace user | Execute the ONE current multimodal Reaction-Test setup action. The server validates the active Product Understanding dispatch, immutable manifest/dige | |
list_assets | Workspace user | Every asset attached to a project (lean records; excerpt via get_asset, pixels via view_asset). | |
remove_asset | Admin | Detach an asset from a project (by id or filename). | |
view_asset | Workspace user | LOOK at an asset. For an image/screenshot this returns the actual image — view it before authoring persona reactions so they are grounded in what is r |
brief_calibration | Admin | Gather the MISSES (refuted bets, high-error predictions, each with its evidence trail) so YOU author corrections: persona patches where a trait drove | |
calibration_report | Admin | Measure calibration NOW (mean Brier + hit rate + the reliability curve over scored predictions, plus the hypothesis hit rate) and persist the snapshot | |
calibration_trend | Admin | Calibration quality OVER TIME: the persisted report series, the Brier delta first→last, and whether the loop is improving — the first-class trend metr | |
record_calibration_round | Admin | Stamp one authored correction round ({persona_id, text, refs?} each) and snapshot a fresh calibration report — the before/after marker that makes 'cor | |
record_prediction_outcome | Admin | Match ONE real outcome to one predicted behavior and score it. prediction_ref: {kind: session|council|synthesis, id, anchor: <pb id>}. observed: bool |
list_examples | Workspace user | The example projects shipped with Sonaloop: slug, title, one-line tagline, and whether each is currently loaded into this database. Load one with load | |
load_example | Admin | Load one shipped example project end-to-end (empty slug = list what's available). Idempotent: re-loading updates the same stable ids — no duplicates. | |
remove_example | Admin | Remove ONE example project's entities — and nothing else. Every id is re-derived from the shipped fixture; personas are matched by their provenance.ex |
brief_flow_walkthrough | Workspace user | GATHER one persona's artifact walkthrough: loaded persona context + the ordered screens (view_asset each — real pixels) + the authoring contract. YOU | |
define_flow | Admin | Define an ORDERED flow from the project's screenshot assets — each step is {asset_id, caption?} (attach the screenshots first via attach_asset / attac | |
flow_funnel | Workspace user | The segment funnel of one flow: per step entered/continued/dropped with the drop reasons, the dropping personas and the step captions — where the coho | |
get_flow_manifest | Workspace user | Read one exact flow-manifest version by manifest_id or flow_key + version. | |
list_flow_manifests | Workspace user | List immutable admitted screenshot-flow versions in the active workspace/project. | |
list_flows | Workspace user | Every defined flow on a project (id, title, step count). | |
record_flow_manifest | Workspace user | Append one immutable, versioned Remote-MCP screenshot-flow manifest. `steps` is ordered and each entry is {asset_version_id, label}; every id must be | |
record_reaction_test_capture_review | Workspace user | Review the exact currently admitted Reaction-Test screen inventory before a flow is frozen. Set capture_complete=false and name concrete known_missing |
brief_grounding | Workspace user | Gather the chunks + authoring contract to ground a persona in real material. WITHOUT persona_id: author a NEW persona from the corpora (description + | |
get_corpus | Admin | One corpus record; include_chunks=True adds a PAGE of chunks (`chunk_list`, shared pagination convention: `limit` default 25 + opaque `cursor`, with c | |
ingest_corpus | Admin | Ingest one REAL document (interview transcript, support-ticket export, review dump, survey verbatims) as a corpus of citable chunks. `content_or_path` | |
list_corpora | Admin | Every ingested corpus (id, title, source_type, chunk count). | |
record_grounding | Workspace user | Persist authored grounding: optional profile patch + the provenance map (claim → chunk ids; validated against the corpora). Links the corpora as perso | |
search_corpus | Admin | Keyword search over corpus chunks — pull the real signal relevant to a task (deterministic token-hit scoring, no embeddings needed). | |
trace_evidence | Admin | Resolve a cited evidence chunk id back to its source: the chunk text, its corpus, and every persona claim grounded on it — how synthesis claims trace |
list_hooks | Admin | All durable hook registrations (id, event pattern, kind, target, label). | |
list_lifecycle_events | Admin | The documented lifecycle-event catalogue the core emits (persona.created, council.recorded = 'session finished', run.finished, …) with each event's st | |
register_hook | Admin | Subscribe a durable hook to a lifecycle event. `event` is an exact name, 'domain.*', or '*'. `kind='command'` runs `target` as a shell command with th | |
test_hook | Admin | Fire a sample envelope through one registered hook and report delivery success — the verification step right after register_hook. | |
unregister_hook | Admin | Remove one durable hook registration by id. |
get_ideation | Admin | Fetch one ideation summary by session id — problem, HMW questions, idea pool, ranked shortlist, and the ready-made cite_as ref for record_decision. | |
list_ideas | Admin | The project's idea records, filterable by HMW question, source persona, or cluster tag — the synthesis surface for the diverge output. | |
record_hmw_reframe | Admin | REFRAME (ideation_hmw protocol step 1): persist your How-Might-We reframe of a raw problem — 3 to 5 host-authored HMW questions, each a string or {que | |
record_ideas | Admin | DIVERGE (step 2): persist council-generated ideas as first-class, queryable idea records. Each idea is {text, persona_id (the source voice — must exis | |
record_ideation_summary | Admin | CONVERGE (step 3): persist the FORCED ranking as an ideation summary. `shortlist` is your ordered picks — [{idea_id, rationale}], rank = position — ev |
generate_persona_surface_avatar | Admin | Generate the native portrait for this exact profile. This can incur provider cost. Preserve the operation ID; inspect unknown outcomes instead of retr | |
get_persona_surface | Admin | Read the current native Persona as an editable MCP App card or plain text. Use a real ID/slug obtained from list_personas. This read writes nothing. | |
get_persona_surface_operation | Admin | Inspect a native Persona operation without repeating it or generating an image. | |
record_persona_surface | Admin | Create one native Persona and return its editable MCP App card. First call brief_persona and author its complete native profile. This writes the recor | |
update_persona_surface | Admin | Save explicit card edits against the current native version; exact retry is safe. |
aggregate_predictions | Admin | The segment roll-up of every predicted behavior in a project — grouped by (action, step, subject) with persona attribution, mean likelihood, evidence | |
suggest_likelihood_levels | Admin | The CANONICAL likelihood vocabulary for predicted behaviors (rare → certain, each with the numeric midpoint calibration scores against) — call before |
fetch | Workspace user | Fetch ONE research record by id (a project/council/synthesis/hypothesis/persona id, e.g. from a `search` result). Returns {id,title,text,url,metadata} | |
search | Workspace user | Find the workspace's research records (projects, councils, syntheses, hypotheses, personas) matching `query`. Returns {results:[{id,title,url,text}]} |
brief_memory_from_chat | Workspace user | Gather exact chat turns for a proposed continuity note. Chat output is synthetic conversation, never independent evidence or lived memory. | |
chat_with_persona | Workspace user | Chat with ONE persona, durably. Returns the loaded agent context + prior turns; YOU author the in-character reply, then persist it with record_chat_tu | |
get_chat | Workspace user | One chat with its full turn history. | |
get_memory_proposal | Workspace user | Read one chat-continuity proposal and its review status. | |
get_study_result | Admin | ONE structured study result: lean project row + run state + council rows + the FULL syntheses in the project's graph + open questions. The shape recur | |
list_chats | Workspace user | Paginated lean chat rows (newest first), optionally scoped to one persona. | |
list_memory_proposals | Workspace user | List continuity proposals for one persona, optionally by review status. | |
query_councils | Admin | Paginated lean council rows; filter by project, participant, free text, `since`. | |
query_personas | Workspace user | Paginated lean persona rows, filterable by free text. Stable ordering + next_offset. | |
query_projects | Admin | Paginated lean research-project rows; filter by status, free text, and `since` (ISO lower bound on updated_at). Newest first. | |
query_syntheses | Admin | Paginated lean synthesis rows (the answer/report nodes); filter by status, text, `since`. | |
record_chat_turn | Workspace user | Persist one authored chat exchange (the durable, queryable artifact). Emits the `chat.recorded` lifecycle event. This does NOT change the official pro | |
record_memory_proposal | Workspace user | Persist a pending chat-continuity proposal. It affects no persona context until explicitly approved with review_memory_proposal. | |
review_memory_proposal | Workspace user | Approve or reject a pending continuity note with an auditable reason. Approval only changes future chat continuity, never facts or identity. | |
substrate_schema | Admin | The versioned substrate contract (envelope, row schemas, filters, the chat flow, the access-guard seam) — what an external automation pins to before q |
get_form | Admin | Inspect one registered primitive form by canonical id or compatibility alias. | |
list_forms | Admin | List registered primitive forms, optionally filtered by primitive id. | |
list_primitives | Admin | List registered Library primitives with family, icon, color and purpose metadata. | |
suggest_forms | Admin | Show the registered forms, schemas, renderers, aggregators and alias policy for one primitive. |
cloud_list_automations | Workspace user | List automation definitions in the active workspace. | |
cloud_create_automation | Admin | Create or update a structured automation recipe with trigger, nodes, edges and optional settings. | |
cloud_configure_automation | Admin | Save workspace-specific settings used by scheduled and manual automation starts. | |
cloud_start_automation | Admin | Start one concrete automation run from API, MCP, CRON, email or webhook input. | |
cloud_get_automation_run | Workspace user | Fetch one automation run with its append-only event trace. |