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

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¶

Endpoint¶

https://portor.<tenant>.askalot.io/mcp

Replace <tenant> with your organization's tenant name.

Authentication¶

The MCP interface uses the same API tokens as the REST API—one token provides access to both interfaces.

Using Your Token with MCP:

Authorization: Bearer your_api_token

Generating a Token:

Log in to https://roundtable.<tenant>.askalot.io
Navigate to Profile Settings
Scroll to "API Tokens" section
Click "Generate New Token"
Copy the token (shown only once)

Unified Authentication

The same API token works for both REST API and MCP. The only difference is the header format:

REST API: X-Api-Token: your_token
MCP: Authorization: Bearer your_token

Available Tools¶

The MCP interface provides tools organized by functionality.

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
`remove_project_owners`	Remove users from project ownership

Questionnaire Operations¶

Tool	Description
`list_questionnaires`	List all questionnaires
`get_questionnaire`	Get questionnaire details
`create_questionnaire`	Create a new questionnaire
`list_qml_files`	List available QML definitions
`load_qml_file`	Load and parse a QML file

Campaign Management¶

Tool	Description
`list_campaigns`	List campaigns (optionally by project)
`get_campaign`	Get campaign details
`create_campaign`	Create a new campaign
`add_respondents_to_campaign`	Add respondents to a campaign
`remove_respondents_from_campaign`	Remove respondents from 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

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

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`	Create a pool using a sampling strategy
`preview_pool_generation`	Preview pool generation without creating it
`refresh_pool_from_strategy`	Re-run selection algorithm on existing pool
`delete_respondent_pool`	Delete a respondent pool

Sampling Strategies¶

Sampling strategies define target demographic distributions for creating representative respondent samples.

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 demographic 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="...",
    target_size=200,
    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, "Urban Millennials Pool")

User Management¶

Tool	Description
`list_users`	List platform users (including interviewers)
`get_user`	Get user details

Note: Interviewers are Users with the interviewer role. They are managed as Users, not as Respondents.

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¶

Tool	Description
`list_surveys`	List surveys (filter by campaign or respondent)
`create_survey`	Start a new survey session
`bulk_create_surveys`	Create surveys for all respondents in a campaign
`get_survey_current_item`	Get the current question
`get_question_options`	Get available options for a question
`submit_survey_response`	Submit an answer and advance
`finish_survey`	Explicitly complete a survey
`mass_fill_surveys`	Fill surveys with synthetic test responses

Data Analysis¶

Dataset extraction, weighting, and export through the medallion architecture (Bronze → Silver → Gold).

Tool	Description
`list_datasets`	List datasets with optional stage/source filters
`get_dataset`	Get dataset details including schema and metrics
`create_bronze_dataset`	Extract survey responses into a Bronze dataset
`apply_raking`	Apply post-stratification weighting to create Silver dataset
`create_gold_dataset`	Create refined Gold dataset from Silver or Bronze
`export_dataset`	Export dataset (CSV, XLSX, SPSS, Parquet)
`get_dataset_quality`	Get quality metrics against sampling strategy
`compare_dataset_quality`	Compare Bronze vs Silver quality improvement
`delete_dataset`	Delete a dataset

Audit & Compliance¶

Tool	Description
`query_audit_events`	Search audit trail with filters
`get_entity_history`	View complete history of any entity
`get_audit_stats`	Get audit statistics

Documentation Access¶

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

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
`docs://primer`	Platform overview
`docs://qml-syntax`	QML language reference
`docs://getting-started`	Quick start guide

Example Workflows¶

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", "satisfaction.qml", project_id)

3. Creating the campaign...
   → create_campaign("Q1 CSAT", project_id, questionnaire_id)

4. Adding your respondent list...
   → bulk_create_respondents(100, generate_demographics=true)
   → add_respondents_to_campaign(campaign_id, respondent_ids)

Your campaign is ready! 100 respondents have been assigned.

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,
       target_size=500,
       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, "Q1 Sample Pool")

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.

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¶

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

Platform Concepts¶

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

Entity Hierarchy¶

Project
├── Questionnaire (references QML file)
└── Campaign
    ├── Respondents (survey targets)
    ├── Interviewers (Users with interviewer role, optional)
    └── Surveys (individual sessions)

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

Error Handling¶

MCP tools return clear error messages:

Error: Campaign not found: 550e8400-e29b-41d4-a716-446655440000
Error: Respondent already assigned to this campaign
Error: Invalid questionnaire status: must be 'active' to create surveys

Next Steps¶

REST API

Traditional REST endpoints for integration

REST Docs
QML Syntax

Learn the questionnaire markup language

QML Guide
Campaigns

Configure and manage survey campaigns

Campaign Guide