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 | 81 workspace-user · 275 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
275 tools across 28 domains, auto-generated from the live server. Each is tagged by the smallest profile it appears in.
add_task | Admin | Insert a task into the plan (shape the breadth): bucket analyze|act|verify, a capability tag, consumes (DAG edges), optional gates. Returns the create | |
assess_progress | Admin | 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 | |
checkpoint_step | Workspace user | Append a completed step (task_id, bucket, key, evidence ids, 1-line summary) to the journal. | |
complete_task | Admin | Mark a ready task done. Verify tasks are gate-checked (breadth + gate judgment + artifacts/ sessions) and rejected until satisfied. | |
export_plan_md | Admin | Render the plan as a human-readable, bucketed plan.md (analyze/act/verify + status + gates). | |
finish_run | Workspace user | Mark the run finished/stopped. | |
get_plan | Workspace user | The project's research plan (analyze/act/verify task DAG + evidence refs + judgments). | |
inject_work | Admin | 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 | Admin | 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 | |
record_critic_round | Admin | Log one completeness-critic round on the run (loop-until-dry observability). | |
record_frame | Admin | Discharge an ANALYZE frame task: author research questions + hypotheses grounded in cited persona memory (>=1 question + >=1 memory_ref). Understand b | |
run_journal | Admin | 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, next_action, directive} → spawn | |
start_project | Workspace user | THE ENTRY POINT. Create a project + seed its research plan (methodology -> analyze/act/verify scaffolding; none -> one dischargeable root frame task); | |
start_run | Workspace user | Create (or resume) the run object — the SINGLE entry to the governed loop. Returns the run + its journal; pass an existing run_id to resume (idempoten |
add_artifact | Workspace user | 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 | Workspace user | 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 | Workspace user | 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). | |
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 | Admin | One recorded usability session by id — the full replayable trace (steps + outcome + statements). | |
list_usability_sessions | Admin | List recorded usability sessions, optionally filtered by project, persona and/or subject ({kind?, id?|url?}). | |
record_usability_session | Admin | 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 | Admin | 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 | Workspace user | 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 | Delete a persona + all its persona-scoped rows and rendered SOUL/avatar files. | |
delete_research_project | Admin | Delete a project container + its edges/open-questions. Syntheses (incl. reports) are kept. | |
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. | |
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). | |
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 | Admin | 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 | Admin | 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 | Admin | 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 | Admin | 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 | Admin | 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 | Admin | The full constellation spec for one methodology (steps, tags, consumes, produces, requires). | |
list_frameworks | Admin | 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 | Admin | List available methodologies (built-in + user-defined) and their step keys. | |
park_evidence | Admin | 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 | Admin | 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 | Admin | 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 | Admin | 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. |
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. | |
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 | |
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. Without the key this degrades gracefully (in-band note, no error). | |
get_persona | Workspace user | Full persona record + recent calendar/experience/pain points. | |
get_persona_soul | Admin | The persona's SOUL.md (authoritative identity + grown drift). | |
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 | |
prepare_persona_agent_context | Workspace user | Build the launch context for a persona subagent (SOUL + state + recent events). | |
record_persona | Workspace user | Validate + persist the persona profile you authored from brief_persona. This is the create path (no server-side text generation). | |
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 | Admin | 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 patch to a persona's profile; records a revision with the reason. A `capabilities` patch ({rungs:{see,walk,drive,login}, tech_co |
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 |
brief_consolidation | Admin | GATHER a simulated day + known entities. Returns instructions for you to author memory_deltas (entities/facts/threads/event_links); then record_memory | |
brief_day | Admin | 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 | Admin | GATHER a period for a consolidated digest (replaces hardcoded reflections). | |
brief_month | Admin | GATHER context to author a whole month bundle (period plan + sample days + digest), chained on the prior month. Then record_month_bundle. | |
brief_period | Admin | 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 | |
extract_pain_points | Admin | Surface a persona's pain-point observations over a date range. | |
get_activity | Admin | Fetch one simulated activity (block) by id. | |
get_calendar | Admin | A persona's calendar events for one day. | |
get_calendar_period | Admin | 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 | Admin | 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 | Render + return MEMORY.md: active projects (timelines), open threads, 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 | Admin | Persist + embed the digest you authored from brief_digest. | |
put_period_plan | Admin | 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 | Admin | 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 | Admin | Persist host-authored memory deltas: resolves/dedupes entities, writes bi-temporal facts (invalidating superseded status), opens/resolves threads, lin | |
record_month_bundle | Admin | 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 | Admin | 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 | Admin | GATHER a computed exhaustiveness snapshot for an INDEPENDENT critic: coverage + the generative breadth_candidates (segments/angles/concepts/risks/fide | |
brief_eval_critic | Admin | 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 | Admin | 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 | Admin | Persist the independent critic verdict {scores, passed, missing[{kind,what,why, suggested_action}], rationale, evidence_refs}. Honesty gate: cannot be | |
record_eval_critic | Admin | 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. |
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 | Admin | One asset record (by id or filename) — includes the text excerpt for documents. | |
list_assets | Admin | 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 | Admin | 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 | Workspace user | 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 | Admin | 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 | Admin | 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 | |
list_flows | Admin | Every defined flow on a project (id, title, step count). |
brief_grounding | Admin | 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 | Admin | 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 |
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}]} |
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 | Admin | One chat with its full turn history. | |
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 | Admin | Paginated lean chat rows (newest first), optionally scoped to one persona. | |
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. | |
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 | Workspace user | Create or update a structured automation recipe with trigger, nodes, edges and optional settings. | |
cloud_configure_automation | Workspace user | Save workspace-specific settings used by scheduled and manual automation starts. | |
cloud_start_automation | Workspace user | 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. |