Skip to content
Knowledge Base

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.

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
https://portor.<tenant>.askalot.io/mcp

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

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):

  1. Point the client at your tenant (export ASKALOT_MCP_URL=https://portor.<tenant>.askalot.io/mcp).
  2. Trigger any MCP tool. The client opens your browser to Portor’s /authorize endpoint, which redirects to the platform OIDC login.
  3. 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.
  4. The browser handshake happens once; the refresh token is exchanged transparently afterward.

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.

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.

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.

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_configuration answers auto_latest (per panel, direct_llm and reasoning: whether the box is on) and auto_status (per slot: when it was last checked, the result, and the last model whose test call failed). Results include ok, no_newer_model, pending_verification, no_credential, catalog_unreadable, session_expired, or the test call’s own refusal reason.
  • In update_model_configuration, naming a model_id for 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 resulting auto_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.

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_respondents caps 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_ends and derive_silver are MCP-only. There is no REST equivalent to look for.
  • Datasets are not MCP-only. list_datasets, get_dataset, delete_dataset and export_dataset all 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, and get_qml_content above 32 KB, return a short-lived signed download_url; fetch it over plain HTTPS.
  • A QML save names the version it was written from. Read with get_qml_content, then pass its version_id as base_version_id to save_qml_file or finalize_upload. After a save, name the version_id that save returned. On overlap, 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_status for a task id, or get_dataset for a dataset stage.

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

The 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=analyst shorthand.

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.

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_fielding stops before the invitations go out. It never sends; that stays a separate, deliberate send_campaign_invitations call 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_pipeline reports a stop in its {success: false, error, detail} envelope; the other two return their normal result with error and detail filled in and no success key.
  • 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.

The MCP interface provides tools organized by functionality.

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

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

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

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

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.

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

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

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.

Tool Description
list_documentation List available documentation
get_documentation Load a specific document
search_documentation Search documentation by keyword

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.

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

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

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 match
national demographics.
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)
...
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: 0

Understanding the entity model helps when working with the MCP interface:

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: 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 interviewer role 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 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 interviewer role can facilitate surveys.
  • Respondents and Users are separate entities. Interviewers are Users, not Respondents.

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: