MCP Tool Reference

Tool Categories

Koji MCP provides 15 tools organized into 5 categories. Each tool is designed to be invoked conversationally — you describe what you want, and Claude selects the right tool automatically.

---

Read and Explore Tools

koji_list_studies

Purpose: List all your research studies with summary metrics.

Parameters:

Returns: Array of studies with id, name, status, interview_count, completion percentage, created/updated dates, and interview link.

Example prompts:

• "List my active studies"
• "Show me all my draft studies"
• "How many studies do I have?"

---

koji_get_study

Purpose: Get full details for a specific study including the research brief, structured questions with types and probing settings, methodology, progress, and recent interviews.

Parameters:

Returns: Complete study details including name, status, research brief (problem context, target participant, methodology framework, interview plan with keyQuestions array), brief completion percentage, readiness to publish flag, interview summaries, and interview link.

Key fields in keyQuestions:

• id — Unique question identifier
• text — The question as asked by the AI interviewer
• type — open_ended, scale, single_choice, multiple_choice, ranking, or yes_no
• config — Type-specific settings (scaleMin, scaleMax, scaleLabels for scales; options for choices/rankings)
• probing — Follow-up configuration (maxFollowUps 0-3, instructions, anchor for scales)
• section — Logical grouping label
• required — Whether the AI must cover this question

Example prompts:

• "Show me the details of my churn research study"
• "What structured questions are in my NPS study?"
• "Is my study ready to publish?"

---

koji_get_interviews

Purpose: List interviews for a study with AI-generated summaries, themes, and sentiment analysis.

Parameters:

Returns: Array of interviews with id, status, interview mode (voice/text), respondent info (name, source), and cached analysis (summary, themes, sentiment, word count, message count).

Example prompts:

• "Show me completed interviews from my pricing study"
• "Which interviews had negative sentiment?"
• "How many voice vs text interviews do I have?"

---

koji_get_transcript

Purpose: Read the full interview transcript message-by-message with respondent context and per-question structured answers.

Parameters:

Returns: Full transcript with conversation_id, study context, status, interview mode, respondent details (name, intake form data), complete message array (role + content), analysis results, and structured answers.

Key fields in analysis.structured_answers (per question):

• value — The typed answer (number for scale, string for choice, array for ranking/multiple choice)
• qualitative_context — Follow-up context the respondent provided
• confidence — How confident the extraction is (high, medium, low)
• follow_up_insights — Insights from probing follow-ups

Note: Transcripts over 60,000 characters are automatically truncated with a warning.

Example prompts:

• "Show me the transcript for interview [id]"
• "What NPS score did this respondent give and why?"
• "Read the latest interview from my study"

---

koji_get_account

Purpose: View your account details, plan tier, credit balance, feature access, and billing status.

Parameters: None

Returns: Account info including plan name, credit balance, feature flags (voice_interviews, report_generation, etc.), usage (study count, interviews this billing period), billing status, and BYOK configuration.

Example prompts:

• "What plan am I on?"
• "How many credits do I have left?"
• "Do I have access to voice interviews?"

---

Create and Modify Tools

koji_create_study

Purpose: Create a new research study with structured questions and an AI-generated brief using proven research methodologies.

Parameters:

Question structure (questions array):

Methodology frameworks:

• Mom Test — Validate ideas without leading questions. Focuses on past behavior, not hypotheticals.
• Jobs-to-be-Done — Understand the job customers are hiring your product to do.
• Customer Discovery — Explore problem space before building solutions. Ideal for startups.
• Exploratory — Open-ended research to discover unknowns.
• Lead Magnet — Engage prospects with valuable research conversations.

Example prompts:

• "Create a Mom Test study about why enterprise users leave during onboarding"
• "Create a study with an NPS question (0-10 scale with anchor probing), a satisfaction rating (1-5), and 3 open-ended questions about user experience"
• "Create a JTBD study with a ranking question asking users to prioritize these 5 features"

---

koji_update_brief

Purpose: Update any section of a study's research brief, including replacing all structured questions.

Parameters:

Important: The questions parameter replaces all existing questions. Include all questions you want to keep when updating.

Example prompts:

• "Add an NPS question to my study on a 0-10 scale"
• "Change the methodology to Jobs-to-be-Done"
• "Replace the interview questions with these 5 new ones"
• "Update the probing depth to 3 follow-ups for all questions"

---

koji_publish_study

Purpose: Publish a draft study to make it live. Sets up the AI interviewer, generates the interview link, and optionally configures voice interviews.

Parameters:

What happens on publish:

1. Validates the research brief is complete enough (checks key fields)
2. Generates the AI interviewer system prompt from your methodology and questions
3. Sets up voice interview capability (if available on your plan)
4. Creates the interview conversation endpoint
5. Generates the shareable interview link
6. Updates study status to 'active'

Returns: Study id, 'active' status, interview link, voice enabled flag, and brief progress percentage.

Example prompts:

• "Publish my churn research study"
• "Make my latest study live"

---

Analyze and Report Tools

koji_get_study_data

Purpose: Get structured, aggregated interview data for analysis, including per-question statistics for structured questions.

Parameters:

Returns: Study context (name, methodology, research goal), array of interview summaries with themes and sentiment, aggregate statistics (total completed, sentiment distribution, top themes with counts), and per-question aggregations.

Per-question aggregation fields:

• Scale questions: average, median, value distribution (e.g., "average NPS: 7.2, median: 8")
• Single/multiple choice: option frequency counts (e.g., "Search: 12, Referral: 8, Ads: 3")
• Ranking questions: average position per option
• Yes/no questions: yes/no counts
• Open-ended questions: sample qualitative answers
• Per-question confidence distribution and response counts

Example prompts:

• "What is the average NPS score from my study?"
• "Show me the feature ranking results"
• "What are the top themes across my interviews?"
• "How did respondents answer the satisfaction question?"

---

koji_generate_report

Purpose: Generate a comprehensive AI research report from your interview data. Takes 30-60 seconds.

Parameters:

What the report includes:

• Executive summary with study context
• Key takeaways prioritized by importance
• Theme analysis with supporting evidence
• Charts (pie charts, bar charts, distribution data)
• Question coverage analysis
• Written findings narrative
• Actionable recommendations
• Statistical overview cards
• All findings linked back to source interviews via citations

Returns: Report summary (version, executive overview, key takeaway titles, sentiment breakdown, generation time). Use koji_get_report for full content.

Example prompts:

• "Generate a report from my customer discovery study"
• "Create a research report from my latest interviews"

---

koji_get_report

Purpose: Retrieve a generated report with optional section filtering.

Parameters:

Returns: Full report data for requested sections, version info, interview counts, and publication status.

Example prompts:

• "Show me the executive summary from my report"
• "Get the recommendations section of my latest report"
• "Show me the charts from my pricing study report"

---

koji_publish_report

Purpose: Publish a report with a shareable public link, or unpublish a previously published report.

Parameters:

Returns: Publication status, public URL, and public slug.

Example prompts:

• "Publish the report for my churn study"
• "Share a link to my latest research report"
• "Unpublish my pricing report"

---

Customize Tool

koji_configure_study

Purpose: Configure a study's interview page branding, lead form, interaction mode, URL slug, and Open Graph settings. This single tool replaces the former koji_customize_intake, koji_configure_lead_form, koji_update_settings, and koji_set_interview_slug tools.

Parameters:

Branding (interview landing page):

Badges:

Lead form:

Field types: text, email, phone, select, textarea, checkbox

Interaction mode:

URL and Open Graph:

Footer:

Only include the fields you want to change — omitted fields keep their current values. You can update any combination of sections in a single call.

Example prompts:

• "Set the headline to 'Share Your Experience' with accent color #FF6B35 and add a lead form asking for name and email"
• "Set the interview URL to 'acme-product-feedback' and enable voice as the default mode"
• "Add a custom badge with a shield icon saying 'GDPR Compliant' and set the OG title for link previews"

---

Distribute Tools

koji_export_data

Purpose: Export study data as structured JSON for external analysis or backup.

Parameters:

Returns: Structured JSON with selected data sections. Transcripts are paginated to manage size.

Example prompts:

• "Export the brief and respondent data from my study"
• "Export the first 10 transcripts from my pricing study"
• "Get a full data export including the report summary"

---

koji_import_respondents

Purpose: Import contacts and generate personalized interview URLs for outreach campaigns.

Parameters:

Returns: Array of created respondents with unique interview URLs containing tracking parameters.

Example prompts:

• "Import these 50 customers to my onboarding study"
• "Create interview links for Sarah Chen, James Park, and Maria Rodriguez"
• "Import respondents from my CRM list with their company names as metadata"

---

Tips for Effective Prompting

You do not need to name tools directly. Just describe what you want naturally:

Claude automatically selects the right tool based on your intent.

---

Related Documentation

• MCP Overview — Integration overview and capabilities
• Structured Questions Guide — Deep dive into question types and configuration
• Best Practices — Tips for effective MCP usage
• Authentication and Security — OAuth 2.1 details

Further reading on the blog

• The Continuous Discovery Handbook: How Product Teams Run Weekly Customer Interviews (2026) — 64% of software features are rarely or never used. Continuous discovery — weekly customer interviews baked into your product workflow — is t
• How Founders Validate Product Ideas with Customer Interviews (2026) — 42% of startups fail because they built something nobody wanted. Here's how to use customer interviews — including AI-powered ones — to vali
• How to Analyze Customer Interview Data: A Complete Guide — You ran the interviews. Now what? Here is a step-by-step process for turning raw transcripts into clear, actionable insights your team will

<!-- further-reading:blog -->