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

Authenticate using the same API token used for the REST API:

Authorization: Bearer your_api_token

Generate tokens from your Roundtable Profile Settings.

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

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_participants_to_campaign	Add respondents or interviewers (Users with interviewer role)
remove_participants_from_campaign	Remove respondents or interviewers

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

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
get_survey_current_item	Get the current question
submit_survey_response	Submit an answer and advance

Audit & Compliance

Tool	Description
query_audit_events	Search audit log 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_participants_to_campaign(campaign_id, respondent_ids, "respondent")

Your campaign is ready! 100 respondents have been assigned.

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