Skip to content

Claude Integration

Askalot's MCP server enables Claude to manage surveys, campaigns, respondents, and data analysis directly through conversation. This guide covers setup for all Claude interfaces.

Overview

The integration provides 78 tools across 13 categories:

Category Tools Examples
Projects 5 Create projects, manage ownership
Campaigns 13 Create campaigns, assign pools, send invitations
Questionnaires 6 Create questionnaires, manage QML files
Respondents 8 Create/update respondents, generate tokens
Surveys 8 Execute surveys, mass fill with test data
Pools 9 Create pools, generate from strategies
Strategies 6 Define sampling strategies
Datasets 9 Extract, weight, export data
Users 2 List and get users
Audit 3 Query audit trail
Documentation 3 Search knowledge base
Documents 4 Search indexed documents
QML Analysis 1 Validate QML with Z3

Authentication

Askalot uses OAuth 2.1 with PKCE and Dynamic Client Registration (RFC 7591). Claude handles the entire flow automatically — you just log in with your Askalot credentials when prompted.

How It Works

  1. Claude discovers Askalot's OAuth endpoints via /.well-known/oauth-authorization-server
  2. Claude registers itself as an OAuth client via POST /register (one-time, automatic)
  3. A browser window opens for you to log in at oidc.platform.askalot.io
  4. After login, Claude receives an access token and connects to the MCP server

No API keys or manual token management required.

OAuth Endpoints

Endpoint Purpose
GET /.well-known/oauth-authorization-server Server metadata discovery
GET /.well-known/oauth-protected-resource/mcp Protected resource metadata
POST /register Dynamic Client Registration
GET /authorize Authorization (redirects to OIDC login)
POST /token Token exchange (authorization_code, refresh_token)
POST /revoke Token revocation

Supported features: Authorization Code with PKCE (S256), refresh tokens, scopes (mcp:read, mcp:write, mcp:admin).

Tenant URL

Replace <tenant> with your tenant identifier in all URLs below. Common tenants:

  • dev — Free trial and demo (ACME Corp organization)
  • eu1 — EU production (paying customers and universities)

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

Claude.ai (Web)

  1. Go to claude.ai and open Settings
  2. Navigate to Integrations (or Connectors)
  3. Click Add Custom MCP Server
  4. Enter:
    • Name: Askalot
    • URL: https://portor.<tenant>.askalot.io/mcp
  5. Click Connect — a browser window opens for OAuth login
  6. Log in with your Askalot credentials and authorize access

Claude Desktop

Add to your Claude Desktop configuration file:

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "askalot": {
      "type": "http",
      "url": "https://portor.<tenant>.askalot.io/mcp"
    }
  }
}

Restart Claude Desktop after saving. On first use, a browser window opens for OAuth login.

Claude Code (CLI)

claude mcp add --transport http askalot https://portor.<tenant>.askalot.io/mcp

On first use, Claude Code opens a browser for OAuth login. After authentication, the token is stored locally and refreshed automatically.

Usage Examples

Create a Survey Campaign

You: Create a customer satisfaction campaign with 50 test respondents.

Claude: I'll set up that campaign for you.

→ list_projects() — found "Customer Research" project
→ create_campaign("CSAT Q1 2026", project_id, questionnaire_id)
→ bulk_create_respondents(50, project_id)
→ create_respondent_pool("CSAT Pool", respondent_ids=...)
→ assign_pool_to_campaign(campaign_id, pool_id)

Done! Campaign "CSAT Q1 2026" is ready with 50 respondents.

Analyze Survey Results

You: Extract and weight the results from my latest campaign.

Claude: I'll create a weighted dataset from your campaign data.

→ list_campaigns(status="completed")
→ create_bronze_dataset("CSAT Results", campaign_id)
→ apply_raking(bronze_dataset_id)
→ compare_dataset_quality(bronze_id, silver_id)

The weighted dataset reduced RMSE from 0.08 to 0.02.
Gender distribution now matches targets within 1%.

Validate a Questionnaire

You: Check my new questionnaire for logical errors.

Claude: I'll run Z3 analysis on your QML file.

→ validate_qml_file("satisfaction.qml")

The questionnaire has 12 items across 3 blocks.
Found 1 issue: Item 'q_followup' is unreachable because
its precondition requires q_satisfied < 3, but q_satisfied
uses a scale of 1-5 with no path setting it below 3.

Tool Annotations

All tools include MCP annotations for safe AI interaction:

  • Read-only tools (list_*, get_*, search_*): Marked with readOnlyHint=true — Claude can call these freely
  • Write tools (create_*, update_*): Marked with destructiveHint=false — safe mutations
  • Delete tools (delete_*, remove_*): Marked with destructiveHint=true — Claude will confirm before executing
  • External tools (send_*_invitation): Marked with openWorldHint=true — sends real emails

Pagination

Listing tools support pagination to keep responses concise:

→ list_respondents(name="Smith", limit=10)
→ list_campaigns(status="active", limit=5)
→ list_surveys(status="completed", limit=20)

All listing tools default to limit=100 and return metadata:

{
  "items": [...],
  "count": 10,
  "limit": 100
}

Next Steps