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 127 tools, each belonging to exactly one of seventeen toolsets. These are the same names you can narrow a connection to with ?toolsets= — see Narrowing the Tools a Connection Sees.

Toolset	Tools	Examples
sampling	23	Respondents, pools, sampling strategies — create, draw, refresh, preview
fielding	21	Surveys, invitations, interviewer workload, the response flow, synthetic fills
analysis	20	Bundles, the Bronze/Silver/Gold pipeline, coding selection, quality, export
questionnaire	17	Create and manage QML files, validate with Z3, publish, upload
campaign	8	Create campaigns, bind a questionnaire, assign a pool
project	7	Create projects, manage ownership
documents	4	Search and read your indexed research documents
methodology	4	Search 24 peer-reviewed methodology papers
audit	3	Query the audit trail
session	4	See which organizations the session may act in, move it between them, look up users
conversation	4	Record and read back an agent run's conversation
docs	3	Search and read the Askalot documentation
paper	3	Read and anchor-edit the project's Research Paper, trace the answerability chain
composite	3	Run a whole chain in one call — fielding, simulation, or the dataset pipeline
tasks	1	get_task_status — poll a long-running job by the task_id it handed back
entitlements	1	Read what your subscription covers
discovery	1	list_toolsets — what each toolset holds and what this connection named

The last eight rows are admitted on every connection whatever it names; the first nine are the ones ?toolsets= filters.

Every tool resolves against one organization

A session is in exactly one organization at a time. list_organizations shows which, and switch_organization moves it — see Your Active Organization for what that changes and how a not-found refusal tells you when you are in the wrong one.

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

Narrowing the connection to the work at hand

Append ?toolsets= to that endpoint to have Claude see only the toolsets you name — https://portor.<tenant>.askalot.io/mcp?toolsets=analysis,campaign, for example. A connection that names none gets everything, which is the default. The scope lives in the URL, so changing it means editing the connector and reconnecting; it narrows what is in front of Claude and grants nothing. Details in Narrowing the Tools a Connection Sees.

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"

Left unset, the plugin connects to the free trial tenant. If your account is on another tenant, sign-in still succeeds and then ends with user_not_in_tenant. The message names the tenant it checked, the tenant your sign-in was for, and that tenant's exact URL. Set the variable to that URL and start Claude Code again.

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, offers_ai_channel=false)
→ 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

The read-only annotation is not only advice to Claude: in a sealed organization it is what Askalot itself uses to decide which calls to refuse. Anything not marked read-only is treated as a write there and answered with org_sealed — except the design-time tools that only ever start or walk a preview, which change nothing in the research record and keep working.

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