MCP Interface
Askalot supports the Model Context Protocol (MCP)—an open standard that enables AI assistants to interact directly with the platform. This allows AI agents to create surveys, manage campaigns, execute questionnaire flows, and analyze results through natural language conversations.
What is MCP?
Section titled “What is MCP?”MCP is a standardized protocol that lets AI systems like Claude interact with external tools and data sources. With Askalot’s MCP interface, you can:
- Automate survey workflows - Create projects, questionnaires, and campaigns through AI conversations
- Execute surveys programmatically - Navigate questionnaire flows and submit responses
- Manage respondents - Import, organize, and assign survey targets to campaigns
- Query audit trail - Track changes and ensure compliance
- Access documentation - AI agents can read platform documentation for context
Connecting to the MCP Interface
Section titled “Connecting to the MCP Interface”Endpoint
Section titled “Endpoint”https://portor.<tenant>.askalot.io/mcpReplace <tenant> with your organization’s tenant name.
This is the connector for you and your team. Respondents never connect here: a Campaign that offers the AI assistant gives each respondent a separate connector, https://portor.<tenant>.askalot.io/respond/mcp, reached with a pairing code from their survey page. It holds only their own survey. See AI-Assisted Self-Interview.
Authentication
Section titled “Authentication”The MCP interface authenticates with OAuth 2.1, not a pasted API token. On the first tool call, Portor returns 401 with an OAuth discovery hint and your MCP client (for example, the Askalot plugin for Claude Code) walks you through a browser sign-in against the platform OIDC provider. The client then stores the resulting access + refresh tokens and sends the access token as Authorization: Bearer on every call — you never handle the bearer value yourself.
Configuring the endpoint (URL only):
The only thing you configure is the server URL. The Askalot plugin reads it from the ASKALOT_MCP_URL environment variable; a plain .mcp.json entry carries the same URL and nothing else — no token field:
{ "mcpServers": { "askalot": { "type": "http", "url": "https://portor.<tenant>.askalot.io/mcp" } }}Signing in (first use):
- Point the client at your tenant (
export ASKALOT_MCP_URL=https://portor.<tenant>.askalot.io/mcp). - Trigger any MCP tool. The client opens your browser to Portor’s
/authorizeendpoint, which redirects to the platform OIDC login. - Sign in. Above the form, the sign-in page names the application that is asking and the address your access will be sent to; continue only if you started this connection from that application. The client exchanges the code for tokens and retries the original call.
- The browser handshake happens once; the refresh token is exchanged transparently afterward.
Your Active Organization
Section titled “Your Active Organization”Your MCP session is always in exactly one organization at a time — its active organization — and every tool call resolves against it. Projects, questionnaires, campaigns, respondents and datasets are all organization-scoped, so this is the single most important thing to know about where a tool is looking.
Where you start. A fresh session lands in your home organization, the one your account belongs to. Nothing asks you to choose during sign-in.
Seeing it. list_organizations returns every organization the session may act in, marks which one is active, and flags any that are sealed. The list is exactly what the Switch Organization menu offers you in the browser — if you belong to one organization, that is the whole list and there is nothing to manage.
Changing it. switch_organization moves the session to another organization from that list. Every later call resolves in the new one, and the change persists: restart your MCP client and you resume where you left off. The tenant is fixed when you sign in and never changes, so switching only ever moves you between organizations inside one tenant.
Being able to enter versus being able to act. The list holds the organizations you are a member of — memberships an administrator grants and removes, never the session itself (an Askalot operator’s list is every organization in the tenant). Membership lets the session move in; which tools it can use there comes from your roles in that organization, and a role you hold elsewhere does not carry over. In an organization where you are a member but hold no role, the tool list shrinks to the session tools — list_organizations, switch_organization, list_toolsets, get_my_entitlements and your model settings — until an administrator grants you a role there, so you can always switch back out. If an administrator removes you from the organization the session is in, the connection ends; sign in again and the new session starts in your home organization.
Sealed Organizations
Section titled “Sealed Organizations”Some organizations are sealed — a curated demo, or a former customer’s data kept available for its retention window. list_organizations marks them, so you can tell before you act.
What is sealed is that organization’s research record — its projects, questionnaires, campaigns, respondents, pools, surveys, datasets and Research Papers. Reading is untouched: listing and fetching all of those keeps working, as do the documentation and methodology-library tools. The audit tools keep their usual rules (see Audit & Compliance). Creating, updating and deleting them is refused with org_sealed. Each tool declares whether it reads or writes, and that declaration is what the refusal is driven by — so the boundary is a property of the tool, not a guess about its name.
Trying an instrument out still works, because a preview changes nothing in the record. create_survey given no campaign starts a preview rather than a survey, and get_survey_current_item, submit_survey_response and finish_survey will walk it — so you can review a questionnaire end to end in a sealed organization. Give create_survey a campaign and it is refused: that walk would be a real case, and real cases enter the dataset.
list_organizations and switch_organization both keep working there, so a session can always see where else it may go and leave.
Sealing also disables API tokens for that organization: you cannot generate one, and an existing one stops working. The OAuth sign-in above is unaffected.
Your AI Model Settings
Section titled “Your AI Model Settings”Askalot runs three kinds of AI call on your behalf, and each picks its provider
and model separately: embedding (fixed to the platform’s local model — index
and search must use the same one, so it is not configurable), direct LLM (a
single raw completion: keyword extraction on a document search, and the
extraction pass when a document is ingested) and reasoning, which runs the
agents and carries a high / medium / low tier.
get_model_configuration reports what is in effect for your own account and,
per slot, where the value came from:
| Source | Meaning |
|---|---|
user |
you chose it |
org |
inherited from your organization |
platform |
Askalot’s default (the embedding slot only) |
mixed |
the provider and the model came from different places |
unconfigured |
nothing is set, and there is no platform default |
The direct-LLM slot and every reasoning tier read unconfigured until you or
your organization choose a provider, and it is the answer to a common confusion:
those slots have no platform default on purpose, because the calls are billed to
your own provider account. A document search or an ingest that refuses with
“requires an LLM provider — none is configured”, or an agent that asks you to
set up a provider, is this state, not a broken key. An unconfigured reasoning
tier reads null in effective_config.
update_model_configuration changes your own slots. It merges: name
direct_llm and your reasoning tiers stay as they were, name
reasoning: {"high": …} and medium and low are untouched. Pass null for a
tier — or clear_direct_llm: true — to hand a slot back to your organization’s
value. The three reasoning tiers must end up on one provider, and an unset tier
counts as a mismatch, so a first write names all three: setting high alone is
refused, because medium and low would be left unset. For the same reason,
clearing reasoning when your organization sets none means passing null for
all three tiers at once.
direct_llm and reasoning each take anthropic_api or bedrock. Ask
get_model_configuration for the accepted values
and the default model per provider rather than guessing; a refused write changes
nothing and names what was wrong.
Always use the latest model
Section titled “Always use the latest model”The direct-LLM slot and the reasoning tiers each form a panel with an Always use the latest model box, on unless you turned it off. While it is on, Askalot keeps the panel’s own slots on the newest Sonnet (direct LLM) or Opus / Sonnet / Haiku (high / medium / low), switching only after a test call with that slot’s credential succeeds; how this works is on AI Functions & Model Options. Through the tools:
get_model_configurationanswersauto_latest(per panel,direct_llmandreasoning: whether the box is on) andauto_status(per slot: when it was last checked, the result, and the last model whose test call failed). Results includeok,no_newer_model,pending_verification,no_credential,catalog_unreadable,session_expired, or the test call’s own refusal reason.- In
update_model_configuration, naming amodel_idfor any slot of a panel is a hand pick: that panel’s box turns off in the same write, and the other panel is untouched. Naming only a provider for a panel whose box is on (direct_llm={"provider": "bedrock"}, or every reasoning tier as{"provider": …}) fills its slots with the newest model of each slot’s family that the provider offers, leaves the box on, and marks the slots for testing on the next check. The answer includes the resultingauto_latest. - The tool never turns a box back on; that is done on the profile page.
Both tools act on your account only. The same settings are on the AI Models section of your profile page, and a change through either door is recorded in the audit trail.
Choosing MCP or REST
Section titled “Choosing MCP or REST”The MCP server is one of two surfaces over the same capabilities, and it cannot tell you when you picked the wrong one: the wrong lane is slow and context-expensive, not an error.
- MCP is for one semantic action, a query, or anything that needs the server’s judgement. Most work belongs here.
- REST (
https://portor.<tenant>.askalot.io/api/v1) is for bulk work and anything whose payload or result is large. Loop and filter outside your context, and keep only a summary.
Which credential, and it depends on who is calling. The OAuth access token that
authenticates your MCP session is accepted on /api/v1 as
Authorization: Bearer <token>. A Personal Access Token goes in the X-Api-Token
header instead, never as Bearer; see Authentication.
- A program that holds its own token — an SDK agent managing its OAuth session — may reuse it on REST. It already has the credential in hand, and one session is one identity on both lanes.
- Code you generate for a sandbox, or anything that outlives the turn, uses a PAT. Not a preference: a sandbox holds no credential of its own that reaches this API. A PAT is also separately revocable, which a session token is not.
- A model driving a chat client never sees the token at all — the client holds it. If you are writing code, you are in the case above.
Facts that are easy to get backwards:
bulk_create_respondentscaps at 100 per call on both lanes. REST validates the same input, so 500 respondents is five calls either way. REST wins on round trips and context, never on batch size.- The pipeline-job verbs
code_open_endsandderive_silverare MCP-only. There is no REST equivalent to look for. - Datasets are not MCP-only.
list_datasets,get_dataset,delete_datasetandexport_datasetall have routes under/api/v1/datasets, and listing or exporting is exactly the large-result work REST is for. - Large content comes back as a link.
export_dataset, andget_qml_contentabove 32 KB, return a short-lived signeddownload_url; fetch it over plain HTTPS. - A QML save names the version it was written from. Read with
get_qml_content, then pass itsversion_idasbase_version_idtosave_qml_fileorfinalize_upload. After a save, name theversion_idthat save returned. Onoverlap, read again and re-apply your change; never resend the same content. Details: Questionnaire tools. - Poll rather than loop. Without a code sandbox, do not hand-write hundreds of sequential tool calls: start the job and poll
get_task_statusfor a task id, orget_datasetfor a dataset stage.
Narrowing the Tools a Connection Sees
Section titled “Narrowing the Tools a Connection Sees”The full surface is over 120 tools, which is more than any single piece of research needs in front of it. A connection can name the areas it wants, in the URL:
https://portor.<tenant>.askalot.io/mcp?toolsets=analysis,campaignThe values are comma-separated toolset names. A connection that names none gets everything, which is the default and stays the default.
Nine toolsets can be filtered this way:
| Toolset | What it holds |
|---|---|
project |
Projects and their ownership |
questionnaire |
Questionnaires and the QML lifecycle |
sampling |
Respondents, pools and sampling strategies |
campaign |
Campaigns and their configuration |
fielding |
Surveys, invitations, interviewers, the response flow |
analysis |
Bundles, datasets and the Bronze/Silver/Gold pipeline |
documents |
Your uploaded reference documents |
methodology |
The shared survey-methodology library |
audit |
The audit trail |
Eight more are admitted on every connection whatever you name, because
taking them away would leave an agent unable to correct its own course: your
session and organization tools, conversation history, entitlements,
documentation, the list_toolsets tool itself, the research paper, the
composite tools below, and get_task_status — so a composite you start on a
narrowed connection can always be polled from it.
Two things this is not, both worth being clear about:
- It is not a permission boundary. You choose your own URL, so naming a toolset keeps nobody out of anything. What you are allowed to do is decided by your subscription tier, your role, and project ownership — none of which this changes. It narrows what is in front of you, not what you may do.
- It is not a role. The parameter takes these toolset names and nothing
else; there is no
?toolsets=analystshorthand.
Call list_toolsets at any time to see every toolset, which tools each holds,
what your connection named, and any names it did not recognise. If you call a
tool your connection scoped out, the refusal names the toolset that holds it and
the URL parameter that would admit it — so a wrong guess is recoverable without
reading this page.
Changing the scope means reconnecting, since it lives in the connection URL. This is an HTTP-transport feature; a stdio connection has no URL and is always unscoped.
Doing a Whole Sequence in One Call
Section titled “Doing a Whole Sequence in One Call”Three common sequences are each available as a single tool. They are not shortcuts that skip steps — every step is the same tool you would call by hand, writing the same records and leaving the same audit trail:
| One call | What it runs |
|---|---|
prepare_campaign_fielding |
Sampling strategy → respondent pool → assign the pool → publish the questionnaire version → create the surveys |
simulate_campaign_responses |
Create the surveys → generate synthetic responses over them |
run_bundle_pipeline |
Bronze extraction → Silver (coding + weighting) → Gold |
Three things to know before using them:
prepare_campaign_fieldingstops before the invitations go out. It never sends; that stays a separate, deliberatesend_campaign_invitationscall you make after reviewing what the chain built. Email cannot be unsent.- If a chain stops partway, what it already built stays. Nothing is undone.
The response names the step in
stopped_at_step; a non-null value means the chain did not finish, and you continue from there with the individual tools.run_bundle_pipelinereports a stop in its{success: false, error, detail}envelope; the other two return their normal result witherroranddetailfilled in and nosuccesskey. - A chain checks the whole sequence up front. If your subscription does not cover a later step, you are told so before anything is built, rather than being handed a half-finished result.
simulate_campaign_responses and run_bundle_pipeline hand back a task id to poll with get_task_status.
run_bundle_pipeline reports the step its run reached and, once finished, each
stage’s dataset; simulate_campaign_responses hands back the same fill task the
raw mass_fill_surveys tool would, so its poll reports progress rather than
steps.
Available Tools
Section titled “Available Tools”The MCP interface provides tools organized by functionality.
Session and Organizations
Section titled “Session and Organizations”| Tool | Description |
|---|---|
list_organizations |
List the organizations this session may switch into, marking the active one and flagging sealed ones |
switch_organization |
Move the session’s active organization — every later call resolves against it |
Project Management
Section titled “Project Management”| Tool | Description |
|---|---|
list_projects |
List all your projects |
get_project |
Get project details |
create_project |
Create a new project |
add_project_owners |
Add users as project owners (targets must be members of the project’s organization) |
remove_project_owners |
Remove users from project ownership (same membership rule applies) |
update_project |
Update a project’s name or description |
delete_project |
Soft-delete a project |
Questionnaire Operations
Section titled “Questionnaire Operations”| Tool | Description |
|---|---|
list_questionnaires |
List all questionnaires |
get_questionnaire |
Get questionnaire details |
create_questionnaire |
Create a new questionnaire from QML content or from a library template (template, copied in language with the library’s other languages as translations); with content it may also take the inventory the content was generated from, stored with version 1 (an inventory that does not validate refuses the whole create) |
list_questionnaire_templates |
List the questionnaire template library in one of its languages (language; yours by default, English flagged language_fallback when the library does not offer yours), by category and a search over name and description |
rename_questionnaire |
Rename a questionnaire (address unchanged) |
update_questionnaire |
Update a questionnaire’s name, description, status, language or estimated duration |
delete_questionnaire |
Soft-delete a questionnaire |
restore_questionnaire |
Restore a recently soft-deleted questionnaire |
list_qml_files |
List the organization’s QML questionnaires |
inspect_qml_file |
Quick summary of a questionnaire’s current version |
preview_qml_item |
Show one questionnaire item as a respondent sees it; a host that renders MCP Apps shows its real controls in a read-only panel |
get_qml_content |
Retrieve a questionnaire’s current QML and its version_id, the base a save names (returns a short-lived download link instead of inline content above 32 KB) |
validate_qml_file |
Run Z3 SMT validation on a questionnaire’s current version (reachability, consistency) |
qml_quality_report |
Compute the D2–D8 design-quality scorecard for a questionnaire’s current version |
save_qml_file |
Save QML written against a version you name (base_version_id, from get_qml_content): merged with a newer save on different lines, refused as overlap on the same lines. Never blocks on broken drafts (content over 32 KB is refused; use the upload handle below) |
request_upload_url / finalize_upload |
Two-step handle for saving QML content over save_qml_file’s 32 KB limit; finalize_upload names base_version_id too |
request_import_upload_url |
Get a single-use link to upload a printed questionnaire (PDF or Markdown) into a project for import; PUT the file to it |
import_questionnaire |
Import the uploaded file as a new draft questionnaire. Long-running and costly: it runs on your own AI provider and counts against your monthly import limit. Answers filled in on the source are discarded and the upload is deleted. Returns a task_id for get_task_status. Needs the designer or manager role (or an operator) and write access to the project |
get_questionnaire_inventory |
Read the inventory a questionnaire was built from: the version it describes, each printed question number with its item id, and the checks that were added rather than printed (invented), with the import report |
get_questionnaire_import_source |
Read the source a PDF import read, as Markdown: what was found and removed (answers, running headers and footers, printed page numbers), then whole pages from from_page up to about max_chars (default 32,000), with next_page for the next call. Each page opens with a marker naming its page in the file, the number printed on it and whether it was read by text or by vision; the inventory’s page numbers are the file’s. A questionnaire not imported from a PDF answers import_source_not_found |
list_qml_translations |
Per language, whether a version’s translation is complete, which texts are untranslated, and whether it is frozen or human-edited |
get_qml_translation |
One language’s translation of a version, with every source text to draft from and the updated_at a save names |
save_qml_translation |
Save translated text for one language (partial, merged over what is stored; names base_updated_at). Text only: unknown ids or codes and partial positional lists are refused |
delete_qml_translation |
Delete one language’s translation of a version (refused once frozen) |
publish_qml_file |
Publish a questionnaire to a campaign — formally validates and pins the exact version (the only gated door) |
move_qml_to_project |
Move a questionnaire to another project (version history preserved) |
unpublish_qml_file |
Soft-delete a questionnaire, retaining its version history (blocked if active campaigns) |
Parameter Reference — parameters, return schemas, QML lifecycle, Z3 output structure
Document Discovery
Section titled “Document Discovery”| Tool | Description |
|---|---|
list_indexed_documents |
List all documents indexed for AI semantic search, each with its document key (for example projects/<project-id>/report.pdf) |
get_document_summary |
Get the stored Markdown summary for a document, named by its document_key |
get_document_chunk |
Retrieve a specific chunk of an indexed document (document_key, chunk_index) |
search_document_chunks_by_keyword |
Search indexed document chunks by keyword, optionally limited to document_keys |
list_methodology_papers |
List the peer-reviewed papers in the shared methodology library, each with the paper_id the other methodology tools take |
get_methodology_chunk |
Retrieve the passage of one methodology paper (paper_id) that best matches a topic phrase, for a verbatim quote |
Research Paper
Section titled “Research Paper”| Tool | Description |
|---|---|
read_paper |
Read a project’s Research Paper — the assembled chapters, plus each unit’s current edit token |
edit_paper_unit |
Replace an exact passage inside one unit of the paper, leaving everything else byte-for-byte unchanged |
read_paper_translation |
Read the paper’s translations into one language: without a unit, every unit’s state (current, behind, missing) and edit tokens; with a unit, its source text and translation side by side |
edit_paper_translation |
Write one unit’s translation into one language, anchored like edit_paper_unit; a translation made from an older source is replaced whole |
answerability_chain |
Read-only: a graded verdict on whether the questionnaire and the data can answer a project’s research goals, so a broken link surfaces before fielding |
The paper is written in its source language (English). A translation is a
separate text beside each unit, shown to readers who read the paper in that
language, and is never written into the source unit. The translate-paper
skill of the Askalot plugin walks an agent through a translation pass.
Campaign Management
Section titled “Campaign Management”| Tool | Description |
|---|---|
list_campaigns |
List campaigns (optionally by project) |
get_campaign |
Get campaign details |
create_campaign |
Create a new campaign |
update_campaign |
Update campaign fields (name, dates, status, volunteer admission, the AI assistant offer and its texts) |
delete_campaign |
Delete a campaign |
add_interviewers_to_campaign |
Add interviewers (Users with interviewer role) |
remove_interviewers_from_campaign |
Remove interviewers from a campaign |
update_campaign_questionnaire |
Change the questionnaire assigned to a campaign |
assign_pool_to_campaign |
Assign a respondent pool to a campaign |
get_campaign_pool |
Get the respondent pool assigned to a campaign |
send_campaign_invitations |
Send survey invitation emails to respondents |
Respondents are not added to a campaign directly — assign a respondent pool with assign_pool_to_campaign, then bulk_create_surveys creates a survey per pool respondent.
Parameter Reference — parameters, return schemas, batch patterns, invitation eligibility
Respondent Management
Section titled “Respondent Management”| Tool | Description |
|---|---|
list_respondents |
List all respondents (survey targets) |
get_respondent |
Get respondent details |
create_respondent |
Create a new respondent |
update_respondent |
Update respondent information |
delete_respondent |
Remove a respondent |
bulk_create_respondents |
Create multiple respondents at once |
bulk_delete_respondents |
Delete respondents by filter (two-step dry_run workflow) |
generate_survey_access_token |
Mint a magic-link token for a respondent’s survey |
send_survey_invitation |
Email a respondent a magic-link survey invitation |
Parameter Reference — parameters, return schemas, bulk creation, demographics
Respondent Pools
Section titled “Respondent Pools”Respondent pools let you organize respondents into reusable groups for campaigns.
| Tool | Description |
|---|---|
list_respondent_pools |
List all respondent pools |
get_respondent_pool |
Get pool details including respondent list |
create_respondent_pool |
Create a new respondent pool |
add_respondents_to_pool |
Add respondents to an existing pool |
remove_respondents_from_pool |
Remove respondents from a pool |
generate_pool_from_strategy |
Draw a pool from a sampling strategy at a requested size; the pool stores its draw settings |
preview_pool_generation |
Preview a draw without creating the pool |
get_sizing_evidence |
Read-only: what a sample-size proposal may draw on: each paper goal with its passage, the population and sampling text, the measured yield of past closed campaigns and the campaign that counts, the recorded design effect, and with a strategy its factor shares and eligible frame. Also POST /api/v1/projects/{project_id}/sizing-evidence |
plan_sample_size |
Read-only: size a draw from a Project’s goal targets (margin of error or two-group power, two-sided, normal approximation), eligibility, response and design effect; returns completes needed, oversample factor and the number to invite, with the saved targets’ revision. Also POST /api/v1/projects/{project_id}/sample-size-plan |
save_sizing_targets |
Save the Project’s size plan, naming the revision you read: every goal’s target, the planning context and each value’s source, then the paper’s Sample size block (the same save the Size Planner page makes). The eligibility and response rates, every group share and any value marked check this need confirmed_via: "agent", set only on the user’s stated or accepted answer and recorded with the user’s id; otherwise nothing is saved. A stale revision is a conflict (REST 409). Also PUT /api/v1/projects/{project_id}/sizing-targets |
refresh_pool_from_strategy |
Redraw an existing pool with the draw settings it stores |
delete_respondent_pool |
Delete a respondent pool |
Parameter Reference — parameters, return schemas, duplicate handling, strategy generation
Sampling Strategies
Section titled “Sampling Strategies”Sampling strategies define target demographic distributions for creating representative respondent samples. A strategy carries no size or selection settings — those are inputs to each pool draw — so one strategy can feed pools of any size.
| Tool | Description |
|---|---|
list_sampling_strategies |
List all sampling strategies |
get_sampling_strategy |
Get strategy details including factors |
create_sampling_strategy |
Create a strategy with custom respondent factors |
create_default_strategy |
Create a strategy with standard gender and age factors |
update_sampling_strategy |
Update an existing strategy |
delete_sampling_strategy |
Delete a sampling strategy |
Example: Creating a Custom Sampling Strategy
AI Assistant: I'll create a sampling strategy targeting your demographics.
→ create_sampling_strategy( name="Urban Millennials", project_id="...", factors=[ {"name": "Gender", "attribute_path": "gender", "target_distribution": {"male": 0.48, "female": 0.50, "other": 0.02}}, {"name": "Age Group", "attribute_path": "age", "target_distribution": {"25-34": 0.60, "35-44": 0.40}} ] )
Strategy created! Now generating a representative pool...→ generate_pool_from_strategy(strategy_id, pool_name="Urban Millennials Pool", requested_size=200)Parameter Reference — parameters, return schemas, factor schema, distribution validation
User Management
Section titled “User Management”| Tool | Description |
|---|---|
list_users |
List users in your active organization (including interviewers) — call switch_organization to see another organization’s users |
get_user |
Get user details |
Note: Interviewers are Users with the interviewer role. They are managed as Users, not as Respondents.
Interviewer Workload
Section titled “Interviewer Workload”For campaigns with interviewers (Users with interviewer role), manage workload distribution:
| Tool | Description |
|---|---|
assign_respondents_to_interviewer |
Assign respondents to a specific interviewer (User) |
unassign_respondents_from_interviewer |
Remove interviewer assignments |
get_interviewer_workload |
View assigned respondents and completion status |
get_unassigned_respondents |
Find respondents not yet assigned |
Survey Execution
Section titled “Survey Execution”| Tool | Description |
|---|---|
list_surveys |
List surveys (filter by campaign or respondent) |
get_survey |
Get one survey, with its questionnaire, interviewer, respondent and campaign |
create_survey |
Start a new survey session |
update_survey |
Update a survey’s status and flow state (bound entities are immutable) |
bulk_create_surveys |
Create surveys for all respondents in a campaign |
bulk_delete_surveys |
Delete surveys by filter (two-step dry_run workflow) |
delete_survey |
Soft-delete one survey |
get_survey_current_item |
Get the current question with its options folded in |
submit_survey_response |
Submit an answer and advance (next step folded in) |
finish_survey |
Explicitly complete a survey |
mass_fill_surveys |
Enqueue an asynchronous background task to fill surveys with synthetic test responses (returns {task_id, status}) |
get_task_status |
Poll an async task by task_id: a mass_fill_surveys run, a simulate_campaign_responses or run_bundle_pipeline chain, or an import_questionnaire run (dataset coding jobs are polled via get_dataset instead) |
Parameter Reference — parameters, return schemas, state machine, distribution modes, personas
Data Analysis
Section titled “Data Analysis”A Bundle binds a Project, Questionnaire, and Campaign subset to one linear Bronze → Silver → Gold dataset chain. Bundle tools manage that binding and carry the Bundle’s quality story; dataset tools run each Bundle-scoped stage — extraction, coding + weighting, refinement, and export.
| Tool | Description |
|---|---|
create_bundle |
Create a pipeline Bundle |
list_bundles |
List Bundles, optionally filtered to one project |
get_bundle |
Bundle detail, including its stage recipes (Silver Calibration Targets, Gold operations) |
clone_bundle |
Deep-copy a Bundle’s ready datasets + recipes into an independent variant |
delete_bundle |
Delete a Bundle and its dataset chain |
get_bundle_quality |
The Bundle’s Representativeness story (selection, fielded, weighted, fielding shift, response) |
compare_bundle_quality |
Bronze vs Silver improvement against the Bundle’s current Strategy |
get_bundle_coding |
Open-end coding state — the candidates the Bronze offers, the analyst’s answer kind for each (descriptive, nominal or identifier; absent = unclassified), the question selection, and per question the proposed dimensions, their categories and which are selected |
set_coding_selection |
Set which open-text units the Bundle codes (manager role, identified user required); refuses an unclassified or identifier unit, and no tool classifies one |
assign_bundle_strategy |
Assign (or clear) the Bundle’s current Sampling Strategy |
set_calibration_targets |
Edit the Bundle’s Calibration Targets — the Silver weighting spec — each raked (weighted on) or benchmark (graded only); every save checks answer codes against the Bundle’s questionnaire |
preview_calibration_targets_copy |
Preview copying another Bundle’s Calibration Targets into this one: which fit (with their role) and which do not, with the reason; writes nothing |
list_datasets |
List datasets scoped to a Bundle’s chain |
get_dataset |
Get dataset details, metrics and status — the bounded surface pipeline steps say to poll |
get_dataset_schema |
Get a dataset’s column schema, or just its column names and control types, optionally narrowed to named columns |
create_bronze_dataset |
Extract a Bundle’s Bronze dataset |
code_open_ends (alias derive_silver) |
Code open-ended text, then weight against Calibration Targets, producing the Bundle’s Silver |
create_gold_dataset |
Refine a Bundle’s Silver into its Gold, using the Gold operation catalog |
export_dataset |
Export a ready dataset (CSV, XLSX, SPSS, Parquet, R, JSON) |
delete_dataset |
Delete a dataset |
Bundle Tools Reference — Bundle lifecycle and quality parameters, return schemas
Dataset Tools Reference — stage parameters, return schemas, export formats
Audit & Compliance
Section titled “Audit & Compliance”| Tool | Description |
|---|---|
query_audit_events |
Search audit trail with filters |
get_entity_history |
View complete history of any entity |
get_audit_stats |
Event counts by entity type |
All three read only your tenant and your active organization. To read another organization’s trail, switch into it first. Events recorded without an organization, such as system and service actions, are not returned.
Within the organization, what you see depends on your role:
| Who | What the audit tools return |
|---|---|
Administrator (org_admin of the organization, or an Askalot operator) |
The whole organization’s trail, including get_audit_stats |
manager |
Your own actions, plus the full history of projects, questionnaires, campaigns and surveys in projects you own |
| Anyone else | Your own actions only |
Asking for another user’s actions, or for the history of an entity outside your reach, is refused. get_audit_stats is administrator-only, and a connection acting for no user reads no audit at all. In an organization where every member reads every project, such as the public Askalot Demo organization, the audit trail is administrator-only: reading the research does not extend to reading who did what, because audit events carry details such as IP addresses.
The audit viewer in the browser applies the same roles, but an Askalot operator and a regular user reach further there:
| Who | What the browser audit viewer shows |
|---|---|
Askalot operator (tenant_admin) |
Every event in the tenant, across all organizations |
Organization administrator (org_admin) |
Every event of the active organization |
manager |
Within the active organization: your own actions, plus the history of projects, questionnaires, campaigns and surveys in projects you own |
| Anyone else | Your own actions only, including your sign-ins |
A sign-in is recorded in the organization the session starts in, and a sign-out or password change in the organization the session is working in, so they are part of that organization’s trail like any other action.
Documentation Access
Section titled “Documentation Access”| Tool | Description |
|---|---|
list_documentation |
List available documentation |
get_documentation |
Load a specific document |
search_documentation |
Search documentation by keyword |
Not Documented on Purpose
Section titled “Not Documented on Purpose”start_run, append_conversation_event, end_run and get_conversation also appear in the tool list. They are internal plumbing: the Askalot plugin’s agents use them to record the conversation of each agent run. They are not meant to be called directly and are not documented here.
MCP Resources
Section titled “MCP Resources”Resources provide read-only access to platform data:
| Resource URI | Description |
|---|---|
repository://overview |
Platform statistics and counts |
repository://schema |
Entity relationships and structure |
qml://files |
The organization’s QML questionnaires |
docs://primer |
Platform overview |
docs://qml-syntax |
QML language reference |
docs://getting-started |
Quick start guide |
Additional documentation resources mirror the knowledge base (docs://guide, docs://glossary, docs://campaign-management, docs://survey-execution, docs://creating-surveys, docs://data-analysis, docs://quality-metrics).
Example Workflows
Section titled “Example Workflows”Creating a Survey Campaign with AI
Section titled “Creating a Survey Campaign with AI”AI Assistant: I'll help you set up a customer satisfaction survey.
1. First, let me create a project... → create_project("Customer Research 2026", "Annual satisfaction study")
2. Now I'll register your questionnaire... → create_questionnaire("CSAT Survey", qml_content, project_id)
3. Creating the campaign... → create_campaign("Q1 CSAT", project_id, questionnaire_id, admits_volunteers=false, offers_ai_channel=false)
4. Adding your respondent list... → bulk_create_respondents(100, generate_demographics=true) → create_respondent_pool("CSAT Sample", respondent_ids=[...]) → assign_pool_to_campaign(campaign_id, pool_id) → bulk_create_surveys(campaign_id)
Your campaign is ready! 100 respondents have surveys waiting.Importing a Printed Questionnaire
Section titled “Importing a Printed Questionnaire”AI Assistant: I'll import your paper questionnaire into the project.
1. Getting an upload link for the PDF... → request_import_upload_url(project_id, "application/pdf") PUT the file to upload_url with Content-Type: application/pdf
2. Starting the import (this takes a few minutes)... → import_questionnaire(project_id, upload_id, "visitor-survey.pdf") → get_task_status(task_id) # until completed or failed
3. Reading what it built... → get_questionnaire_inventory(result.questionnaire_id) Each printed question number maps to its item id; the checks marked invented were added and are worth reviewing before you publish.
4. Checking a question against what the import read (PDF only)... → get_questionnaire_import_source(result.questionnaire_id, from_page=12)A refused import starts nothing and says what clears it: unsupported_type
(only PDF and Markdown are read today), too_large, invalid_request,
no_ai_slot (connect an Anthropic API key or Amazon Bedrock, and a Direct LLM
model, in Profile Settings) or fair_use_exceeded (the monthly import limit).
A refused import needs a new upload, because the file is deleted either way.
Creating a Representative Sample
Section titled “Creating a Representative Sample”AI Assistant: I'll create a demographically balanced sample for your study.
1. Creating a sampling strategy with your target demographics... → create_sampling_strategy( name="National Representative", project_id, factors=[ {"name": "Gender", "attribute_path": "gender", "target_distribution": {"male": 0.49, "female": 0.51}}, {"name": "Age", "attribute_path": "age", "target_distribution": {"18-34": 0.30, "35-54": 0.40, "55+": 0.30}} ] )
2. Generating a pool that matches your targets... → generate_pool_from_strategy(strategy_id, pool_name="Q1 Sample Pool", requested_size=500)
3. Assigning the pool to your campaign... → assign_pool_to_campaign(campaign_id, pool_id)
Done! Your campaign now has 500 respondents balanced to matchnational demographics.Executing a Survey Programmatically
Section titled “Executing a Survey Programmatically”AI Assistant: I'll walk through the survey and show you each question.
→ create_survey(questionnaire_id, respondent_id)→ get_survey_current_item(survey_id)
Question 1: "What is your age?"Type: Integer input (18-100)
User: 35
→ submit_survey_response(survey_id, "q_age", 35)→ get_survey_current_item(survey_id)
Question 2: "How satisfied are you with our service?"Type: Scale (1-5)...Managing Interviewer Workload
Section titled “Managing Interviewer Workload”AI Assistant: Let me distribute the 50 respondents among your 5 interviewers (Users with interviewer role).
→ get_unassigned_respondents(campaign_id) Found 50 unassigned respondents
→ assign_respondents_to_interviewer(campaign_id, interviewer_user_1, respondents[0:10])→ assign_respondents_to_interviewer(campaign_id, interviewer_user_2, respondents[10:20])...
→ get_interviewer_workload(campaign_id, interviewer_user_1) Assigned: 10 respondents Completed: 0 In Progress: 0Platform Concepts
Section titled “Platform Concepts”Understanding the entity model helps when working with the MCP interface:
Entity Hierarchy
Section titled “Entity Hierarchy”Project├── Questionnaire (owns a QML version chain)└── Campaign ├── Respondents (survey targets) ├── Interviewers (Users with interviewer role, optional) └── Surveys (individual sessions)Every questionnaire belongs to a project, and every user has a default project (is_default: true). When a request names no project, find the default with list_projects and use its id.
Respondents and Interviewers
Section titled “Respondents and Interviewers”- Respondents: Survey targets with demographic data. Their survey completions determine campaign progress. They access surveys via magic links (no platform authentication required).
- Interviewers (optional): Users with the
interviewerrole who facilitate surveys for respondents. They have platform login and help respondents complete surveys but don’t fill in surveys themselves.
Interviewers can be assigned to help respondents in person or by phone. When interviewers are assigned, surveys track which interviewer facilitated each respondent’s survey.
Respondents vs Users
Section titled “Respondents vs Users”- Respondents are survey targets with demographic data (age, gender, location). They don’t have platform accounts.
- Users are platform accounts for authentication and management. Users with the
interviewerrole can facilitate surveys. - Respondents and Users are separate entities. Interviewers are Users, not Respondents.
Error Handling
Section titled “Error Handling”MCP tools return structured error messages. Two apply across every category:
not_found— the entity is not in the session’s active organization. The message names the organization it searched; see Your Active Organization.org_sealed— the active organization is sealed. Reads succeed; this refusal only ever comes from a tool that would have changed its research record.
Detailed error patterns are documented per category:
- Campaign Tools — batch patterns (added/skipped/reasons), invitation eligibility
- Survey Tools — state machine transitions, flow errors
- Dataset Tools — stage validation, format errors
- Pool Tools — duplicate handling, strategy validation
- Sampling Tools — factor schema validation, default strategy protection
- Questionnaire Tools — lifecycle constraints, active campaign checks
- Respondent Tools — bulk creation errors