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.

Two ways to connect Claude to Askalot

• Claude Code (CLI) can install the Askalot plugin — agents, skills, slash commands, and the MCP tools — from the marketplace (/plugin marketplace add askalot-io/askalot-plugin). This is the richest surface.
• Claude Desktop and Claude.ai (web) connect to Askalot as a remote MCP custom connector: you get the tools / API surface only — no agents, skills, or commands. There is no desktop extension (.mcpb) to install; Portor is a remote OAuth server you add by URL.

Overview

The integration exposes 117 tools. Grouped by area:

Category	Tools	Examples
Projects	7	Create projects, manage ownership
Campaigns	15	Create campaigns, assign pools, interviewers, send invitations
Questionnaires & QML	16	Create/manage QML files, validate with Z3, publish
Respondents	8	Create/update respondents, generate access tokens
Surveys	12	Execute surveys, mass fill with synthetic data
Pools	9	Create pools, generate/refresh from strategies
Sampling strategies	6	Define and update sampling strategies
Datasets & bundles	16	Bundle campaigns, extract/weight/export data, quality metrics
Research Brief	2	Read and anchor-edit the project's Research Brief
Methodology library	4	Search 24 peer-reviewed methodology papers
Indexed documents	4	Search and read indexed research documents
Knowledge base	3	Search the Askalot documentation
Audit	3	Query the audit trail
Users	2	List and get users
Conversation, uploads & utilities	10	Conversation runs, uploads, answerability, entitlements, task status

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

Claude Desktop connects to Askalot as a remote custom connector — you get the MCP tools / API only (no agents, skills, or commands), and there is no desktop extension (.mcpb) to install because Portor is a remote server.

Add a custom connector (recommended)

1. Open Settings → Connectors (in some builds this is under Customize → Connectors)
2. Click Add custom connector
3. Enter:
   • Name: Askalot
   • Remote MCP server URL: https://portor.<tenant>.askalot.io/mcp
4. Click Add — a browser window opens for OAuth login
5. Log in with your Askalot credentials and authorize access

The OAuth consent is interactive and one-time; Claude Desktop stores and refreshes the token for you. After connecting, the survey, campaign, dataset, and analysis tools appear in the connector's tool list. There is no API key or static token to paste — Askalot uses OAuth 2.1.

Configuration-file alternative

If you prefer editing the config file directly, add the remote server under mcpServers:

macOSWindows

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 Code can connect in two ways.

Install the Askalot plugin (full surface)

/plugin marketplace add askalot-io/askalot-plugin
/plugin install askalot@askalot

The plugin bundles the Askalot agents, skills, slash commands, and the MCP tools. Its MCP wiring (.mcp.json) is type: http pointed at ${ASKALOT_MCP_URL} with interactive OAuth — no static bearer token. Set ASKALOT_MCP_URL in your shell before launching Claude Code:

export ASKALOT_MCP_URL="https://portor.<tenant>.askalot.io/mcp"

Add the MCP server only

If you only want the tools (no agents/skills/commands):

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 build a Bundle and derive a weighted dataset from your campaign data.

→ list_campaigns(status="completed")
→ create_bundle("CSAT Results", project_id, questionnaire_id, campaign_ids=[campaign_id])
→ create_bronze_dataset(bundle_id)
→ code_open_ends(bundle_id)  # codes open-ends, then weights the coded case base
→ get_dataset(silver_dataset_id)  # poll until "ready" — comparing earlier returns a conflict
→ compare_bundle_quality(bundle_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

• MCP Interface Reference — Complete tool documentation
• REST API — Traditional HTTP endpoints
• QML Syntax — Questionnaire markup language