ListenLabs MCP

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'listenlabsmcp'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize ListenLabs MCP:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'listenlabsmcp_list_creatable_orgs',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "listenlabsmcp"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize ListenLabs MCP:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="listenlabsmcp_list_creatable_orgs",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Study move, publish, launch — Move a study into a folder, or back out to the dashboard root
• Folder manage — Create, rename, re-nest, or delete a dashboard folder
• Search across studies — Search across study metadata using a text query
• List studies, creatable orgs — List studies accessible to the authenticated user
• Get study state, study responses, study analysis — Return the current state of a study — title, audience, study guide, questions, screener, and recruitment details
• Create study — Start a new guided user-interview study

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

listenlabsmcp_create_study#Start a new guided user-interview study. Provide a plain-language description of the study goals and target audience. The platform's creation agent walks through onboarding stages; subsequent turns must use edit_study with the returned studyId and chatId.3 params▾

Start a new guided user-interview study. Provide a plain-language description of the study goals and target audience. The platform's creation agent walks through onboarding stages; subsequent turns must use edit_study with the returned studyId and chatId.

NameTypeRequiredDescription

promptstringrequiredPlain-language description of the study to create (goals, who to interview, what to learn)

orgIdstringoptionalOrganization UUID when known (e.g. from list_creatable_orgs)

orgNamestringoptionalOrganization name to create the study in. Required when the user belongs to multiple organizations.

listenlabsmcp_edit_study#Send a natural-language edit instruction or structured button event to the study creation agent. Use after create_study (pass the chatId) for guided onboarding, or with a fresh chatId for direct edits to an existing study. Supply either prompt or buttonClick, not both.4 params▾

Send a natural-language edit instruction or structured button event to the study creation agent. Use after create_study (pass the chatId) for guided onboarding, or with a fresh chatId for direct edits to an existing study. Supply either prompt or buttonClick, not both.

NameTypeRequiredDescription

studyIdstringrequiredUUID of the study to edit

buttonClickobjectoptionalStructured button event from the guided onboarding flow

chatIdstringoptionalChat session ID from create_study or a previous edit_study call. Omit on the first turn.

promptstringoptionalFree-form instruction or user input for the study agent

listenlabsmcp_get_response#Deep-dive into a single respondent's interview. Returns a structured transcript with question tracking, input types, multiple choice data, and source URLs for each message. Paginated for large interviews.3 params▾

Deep-dive into a single respondent's interview. Returns a structured transcript with question tracking, input types, multiple choice data, and source URLs for each message. Paginated for large interviews.

NameTypeRequiredDescription

readable_idnumberrequiredRespondent number from get_study_responses

study_idstringrequiredStudy ID (UUID) from list_studies

cursorstringoptionalPagination cursor for long transcripts

listenlabsmcp_get_study_analysis#Get the AI-generated analysis report for a study, rendered as markdown. Use list_studies first to find studies where has_analysis is true. The report includes sourced respondent quotes with deep-links to the original transcript messages.1 param▾

Get the AI-generated analysis report for a study, rendered as markdown. Use list_studies first to find studies where has_analysis is true. The report includes sourced respondent quotes with deep-links to the original transcript messages.

NameTypeRequiredDescription

study_idstringrequiredStudy ID (UUID) from list_studies

listenlabsmcp_get_study_responses#Get response transcripts for a study. Returns formatted interview transcripts with pagination. Each respondent answer includes a source link to that exact message in the transcript.5 params▾

Get response transcripts for a study. Returns formatted interview transcripts with pagination. Each respondent answer includes a source link to that exact message in the transcript.

NameTypeRequiredDescription

study_idstringrequiredStudy ID (UUID) from list_studies

cursorstringoptionalPagination cursor from previous response

max_responsesnumberoptionalMaximum number of responses to return (default 10, max 50)

question_numbersarrayoptionalOnly include these question numbers in the transcript (1-indexed)

readable_idsarrayoptionalFilter to specific respondents by their readable ID numbers

listenlabsmcp_get_study_state#Return the current state of a study — title, audience, study guide, questions, screener, and recruitment details. Also includes launch eligibility, credit balance, and per-recruitment cost. Call before edit_study or launch_study to inspect the current study configuration.1 param▾

Return the current state of a study — title, audience, study guide, questions, screener, and recruitment details. Also includes launch eligibility, credit balance, and per-recruitment cost. Call before edit_study or launch_study to inspect the current study configuration.

NameTypeRequiredDescription

studyIdstringrequiredUUID of the study to inspect

listenlabsmcp_launch_study#Publish the study's draft revision (if needed) and start all unlaunched recruitments that fit the organization's credit balance. Recruitments are launched greedily in dashboard order. Returns launched and skipped recruitments with balance before/after. Safe to re-call — already-launched recruitments are skipped.1 param▾

Publish the study's draft revision (if needed) and start all unlaunched recruitments that fit the organization's credit balance. Recruitments are launched greedily in dashboard order. Returns launched and skipped recruitments with balance before/after. Safe to re-call — already-launched recruitments are skipped.

NameTypeRequiredDescription

studyIdstringrequiredUUID of the study to launch

listenlabsmcp_list_creatable_orgs#List organizations the user belongs to where they can create studies. Returns org ID, name, and role. Supports pagination and case-insensitive name search. Call before create_study when the user has not specified an organization.3 params▾

List organizations the user belongs to where they can create studies. Returns org ID, name, and role. Supports pagination and case-insensitive name search. Call before create_study when the user has not specified an organization.

NameTypeRequiredDescription

cursorstringoptionalPagination cursor from a previous call's nextCursor

limitintegeroptionalPage size (default 10, max 25)

textHintstringoptionalCase-insensitive substring to filter org names by

listenlabsmcp_list_studies#List studies accessible to the authenticated user. Returns study ID, name, status, creation date, response count, and whether analysis is available. Paginated (50 per page). Use textHint to filter by study title; use cursor for pagination.3 params▾

List studies accessible to the authenticated user. Returns study ID, name, status, creation date, response count, and whether analysis is available. Paginated (50 per page). Use textHint to filter by study title; use cursor for pagination.

NameTypeRequiredDescription

cursorstringoptionalPagination cursor from previous response

statusstringoptionalFilter by study status

textHintstringoptionalCase-insensitive substring to filter study titles by

listenlabsmcp_manage_folder#Create, rename, re-nest, or delete a dashboard folder. Folders only: it never creates, moves, or deletes a study. Use move_study to file a study in a folder. Delete only removes an EMPTY folder, and only when the user explicitly asked to delete it.8 params▾

Create, rename, re-nest, or delete a dashboard folder. Folders only: it never creates, moves, or deletes a study. Use move_study to file a study in a folder. Delete only removes an EMPTY folder, and only when the user explicitly asked to delete it.

NameTypeRequiredDescription

actionstringrequiredcreate makes a new folder, rename changes a folder's name, move re-nests it under another folder, delete permanently removes an empty one.

folderNamestringrequiredThe folder to act on, or a "/"-separated path for nested folders (e.g. "Research / Q3 2026"). For create, this is the folder to make.

folderIdstringoptionalFolder UUID from list_studies folders[] or a previous error. Takes precedence over folderName; use it when a name was reported as ambiguous.

newNamestringoptionalNew folder name. Required for action="rename", ignored otherwise.

orgIdstringoptionalOrganization UUID when known (e.g. from list_creatable_orgs). Prefer orgName when the user gave a name.

orgNamestringoptionalOrganization name. Required when the user belongs to multiple organizations and did not specify one.

parentFolderIdstringoptionalDestination folder UUID for action="move". Takes precedence over parentFolderName; use it when the parent name was reported as ambiguous.

parentFolderNamestringoptionalFolder to nest under, matched like folderName. Used by action="move"; omit it to move the folder to the dashboard root.

listenlabsmcp_move_study#Move a study into a folder, or back out to the dashboard root. Pass folderName to move it into an existing folder; omit both folderName and folderId to move the study out of its folder and back to the dashboard root. The folder must already exist.3 params▾

Move a study into a folder, or back out to the dashboard root. Pass folderName to move it into an existing folder; omit both folderName and folderId to move the study out of its folder and back to the dashboard root. The folder must already exist.

NameTypeRequiredDescription

studyIdstringrequiredStudy identifier: the UUID from list_studies, the short link id from a Listen Labs study URL (e.g. zy4GuhxP), or the full pasted URL (e.g. https://listenlabs.ai/p/zy4GuhxP/).

folderIdstringoptionalDestination folder UUID from a previous move_study error. Use instead of folderName when selecting by ID.

folderNamestringoptionalExisting destination folder name, or a "/"-separated path to pick between folders sharing a name (e.g. "Research / Q3 2026"). Rejected if no such folder exists. Omit to move the study to the dashboard root.

listenlabsmcp_publish_study#Publish the study's current draft revision so respondents see the latest version. No-op when the draft is identical to prod. Does not start recruitments — use launch_study to begin sourcing respondents.1 param▾

Publish the study's current draft revision so respondents see the latest version. No-op when the draft is identical to prod. Does not start recruitments — use launch_study to begin sourcing respondents.

NameTypeRequiredDescription

studyIdstringrequiredUUID of the study to publish

listenlabsmcp_search_across_studies#Search across study metadata using a text query. Returns matching studies with relevant context.2 params▾

Search across study metadata using a text query. Returns matching studies with relevant context.

NameTypeRequiredDescription

querystringrequiredSearch term to find across studies

max_resultsnumberoptionalMaximum number of results to return (default 10)