MCP Tool Reference — All 17 Tools
Complete reference for all 17 Koji MCP tools. Includes parameters, return data, plan requirements, and example prompts for each tool across read, create, analyze, customize, and distribute categories.
Tool Categories
Koji MCP provides 17 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 & Explore Tools
koji_list_studies
Purpose: List all your research studies with summary metrics.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| status | string | No | Filter by status: 'draft', 'active', 'completed', 'archived' |
| limit | number | No | Results per page (1-100, default 50) |
| offset | number | No | Pagination offset |
Returns: Array of studies with id, name, status, interview_count, completion percentage, created/updated dates, and interview link.
Plan: All plans
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, methodology, progress, and recent interviews.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| study_id | UUID | Yes | The study identifier |
Returns: Complete study details including name, status, research brief (problem context, target participant, methodology framework, interview plan), brief completion percentage, readiness to publish flag, interview summaries, and interview link.
Plan: All plans
Example prompts:
- "Show me the details of my churn research study"
- "What is the methodology for study [id]?"
- "Is my study ready to publish?"
koji_get_interviews
Purpose: List interviews for a study with AI-generated summaries, themes, and sentiment analysis.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| study_id | UUID | Yes | The study identifier |
| status | string | No | Filter: 'active', 'completed', 'abandoned' |
| sentiment | string | No | Filter: 'positive', 'neutral', 'negative', 'mixed' |
| limit | number | No | Results per page (1-100, default 50) |
| offset | number | No | Pagination offset |
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).
Plan: All plans
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.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| interview_id | UUID | Yes | The interview/conversation identifier |
Returns: Full transcript with conversation_id, study context, status, interview mode, respondent details (name, intake form data), complete message array (role + content), message count, and truncation flag.
Note: Transcripts over 60,000 characters are automatically truncated with a warning.
Plan: All plans
Example prompts:
- "Show me the transcript for interview [id]"
- "Read the latest interview from my study"
- "What did the respondent say about pricing?"
koji_get_account
Purpose: View your account details, plan tier, usage limits, feature access, and billing status.
Parameters: None
Returns: Account info including plan name, feature flags, usage (study count, interviews this month), limits (max studies, max interviews, max report updates), billing status, and BYOK configuration.
Plan: All plans
Example prompts:
- "What plan am I on?"
- "How many interviews do I have left this month?"
- "Do I have access to voice interviews?"
✏️ Create & Publish Tools
koji_create_study
Purpose: Create a new research study with an AI-generated brief using proven research methodologies.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| topic | string | Yes | What you want to research (e.g., "Why do users churn after onboarding?") |
| goal | string | No | Business decision this research will inform |
| target_audience | string | No | Who you want to interview |
| methodology | enum | No | 'mom_test', 'jtbd', 'discovery', 'exploratory', 'lead_magnet' |
| key_questions | string[] | No | Specific questions to include in the interview |
| hypothesis | string | No | Your current assumption to test |
| context | string | No | Additional background information |
| estimated_duration | string | No | Target interview length (default: "15-20 minutes") |
Returns: Created study with id, name, full research brief (problem context, methodology framework with core principles and question patterns, interview plan with key questions and guardrails), brief completion percentage, and suggested next steps.
Plan: Free (1 study), Starter (3), Growth (10), Scale (unlimited)
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"
- "Start a JTBD study to understand how PMs choose analytics tools"
- "Create a discovery study about remote team collaboration challenges"
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:
| Parameter | Type | Required | Description |
|---|---|---|---|
| study_id | UUID | Yes | The study identifier |
What happens on publish:
- Validates the research brief is complete enough (checks key fields)
- Generates the AI interviewer system prompt from your methodology and questions
- Sets up voice interview capability (Growth+ plans with ElevenLabs)
- Creates the interview conversation endpoint
- Generates the shareable interview link
- Updates study status to 'active'
Returns: Study id, 'active' status, interview link, voice enabled flag, and brief progress percentage.
Plan: All plans (voice requires Growth)
Example prompts:
- "Publish my churn research study"
- "Make my latest study live"
📊 Analyze & Report Tools
koji_get_study_data
Purpose: Get structured, aggregated interview data for analysis. Returns summaries (not full transcripts) with theme and sentiment distributions.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| study_id | UUID | Yes | The study identifier |
| status | string | No | Filter interviews by status |
| limit | number | No | Max interviews (1-50, default 20) |
| offset | number | No | Pagination offset |
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 pagination info.
Note: This returns cached analysis summaries, not raw transcripts. If interviews have not been analyzed yet, a helpful message is returned.
Plan: All plans
Example prompts:
- "Get the data from my pricing study for analysis"
- "What are the top themes across my interviews?"
- "Show me the sentiment breakdown for completed interviews"
koji_generate_report
Purpose: Generate a comprehensive AI research report from your interview data. Takes 30-60 seconds.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| study_id | UUID | Yes | The study identifier |
What the report includes:
- Executive summary with study context
- Key takeaways prioritized by importance
- Theme analysis with supporting evidence
- Sentiment breakdown across interviews
- 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.
Plan: Starter (3 per study), Growth (unlimited), Scale (unlimited)
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:
| Parameter | Type | Required | Description |
|---|---|---|---|
| study_id | UUID | Yes | The study identifier |
| version | number | No | Specific report version (default: latest) |
| sections | string[] | No | Filter sections: 'executive_summary', 'key_takeaways', 'theme_analysis', 'charts', 'question_coverage', 'written_findings', 'recommendations', 'stat_cards' |
Returns: Full report data for requested sections, version info, interview counts, and publication status.
Plan: Starter+
Example prompts:
- "Show me the executive summary from my report"
- "Get the recommendations section of my latest report"
- "Show me the full report for my pricing study"
koji_publish_report
Purpose: Publish a report with a shareable public link, or unpublish a previously published report.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| study_id | UUID | Yes | The study identifier |
| publish | boolean | Yes | true to publish, false to unpublish |
Returns: Publication status, public URL, and public slug.
Plan: Growth+ for publishing
Example prompts:
- "Publish the report for my churn study"
- "Share a link to my latest research report"
- "Unpublish my pricing report"
🎨 Customize Tools
koji_customize_intake
Purpose: Customize the interview landing page that respondents see before starting.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| study_id | UUID | Yes | The study identifier |
| headline | string | No | Main title (max 100 chars) |
| subheadline | string | No | Secondary text (max 200 chars) |
| description | string | No | Description paragraph (max 500 chars) |
| cta_button_text | string | No | Button text (max 30 chars) |
| accent_color | hex string | No | Brand color (e.g., "#4F46E5") |
| show_orb | boolean | No | Show animated background orb |
| show_duration | boolean | No | Show duration badge |
| duration_text | string | No | Custom duration text |
| show_anonymous | boolean | No | Show anonymity badge |
| anonymous_text | string | No | Custom anonymity text |
| custom_badges | array | No | Up to 4 custom trust badges |
| footer_text | string | No | Footer text |
| consent_text | string | No | Consent/privacy text |
| show_powered_by | boolean | No | Show "Powered by Koji" |
Plan: Growth+ for branding, Scale to remove powered-by
Example prompts:
- "Set the headline to 'Share Your Experience with Acme' and accent color to #FF6B35"
- "Add a custom badge with a shield icon that says 'GDPR Compliant'"
- "Hide the powered by Koji badge"
koji_configure_lead_form
Purpose: Set up a pre-interview form to collect respondent information.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| study_id | UUID | Yes | The study identifier |
| enabled | boolean | Yes | Enable or disable the form |
| title | string | No | Form title (max 100 chars) |
| description | string | No | Form description (max 300 chars) |
| fields | array | No | Form fields (max 6) with id, type, label, placeholder, required, options |
| submit_button_text | string | No | Submit button text |
Field types: text, email, phone, select, textarea, checkbox
Plan: Growth+
Example prompts:
- "Add a lead form asking for name, email, and company"
- "Add a consent checkbox to my interview form"
- "Disable the lead form on my study"
koji_update_settings
Purpose: Configure interview interaction modes and link preview metadata.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| study_id | UUID | Yes | The study identifier |
| enable_voice | boolean | No | Enable voice interviews |
| enable_text | boolean | No | Enable text interviews |
| default_mode | enum | No | 'voice' or 'text' |
| og_title | string | No | Custom Open Graph title |
| og_description | string | No | Custom Open Graph description |
Plan: Growth+ for voice, Scale for custom OG
Example prompts:
- "Enable voice interviews as the default mode"
- "Set the link preview title to 'Customer Research Survey by Acme'"
koji_set_interview_slug
Purpose: Set a custom URL slug for the interview link.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| study_id | UUID | Yes | The study identifier |
| slug | string | Yes | Custom slug (3-60 chars, lowercase, hyphens) |
Result: Changes the link from koji.so/i/abc123 to koji.so/i/your-custom-slug
Plan: Growth+
Example prompts:
- "Set the interview URL to 'acme-product-feedback-2025'"
- "Change my interview slug to 'onboarding-research'"
📤 Distribute Tools
koji_export_data
Purpose: Export study data as structured JSON for external analysis or backup.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| study_id | UUID | Yes | The study identifier |
| include_brief | boolean | No | Include research brief (default: true) |
| include_transcripts | boolean | No | Include interview transcripts |
| include_respondents | boolean | No | Include respondent data |
| include_report_summary | boolean | No | Include report executive summary |
| transcript_limit | number | No | Transcripts per page (1-10, default 5) |
| transcript_offset | number | No | Transcript pagination offset |
Returns: Structured JSON with selected data sections. Transcripts are paginated to manage size.
Plan: All plans
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:
| Parameter | Type | Required | Description |
|---|---|---|---|
| study_id | UUID | Yes | Must be a published (active) study |
| respondents | array | Yes | 1-500 respondents with display_name, email, external_id, metadata |
Returns: Array of created respondents with unique interview URLs containing tracking parameters (?rid=...).
Plan: Scale
Example prompts:
- "Import these 50 customers to my onboarding study: [list]"
- "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:
| Instead of this | Say this |
|---|---|
| "Use koji_create_study with topic..." | "Create a study about why users prefer competitor X" |
| "Call koji_get_interviews with status completed" | "Show me all completed interviews" |
| "Run koji_generate_report" | "Generate a research report from my interviews" |
Claude automatically selects the right tool based on your intent.
Related Articles
Koji MCP Integration Overview
Connect Koji to Claude, Cursor, and other AI assistants using the Model Context Protocol (MCP). Manage your entire research workflow conversationally — create studies, run interviews, analyze data, and generate reports without leaving your AI assistant.
Connect Koji to Claude (Setup Guide)
Step-by-step guide to connect your Koji account to Claude Desktop, Claude.ai, Cursor, and other MCP clients. Takes under 2 minutes with OAuth — no API keys required.
MCP Workflow Guide for Product Managers
End-to-end guide for product managers using Koji MCP with Claude to automate customer discovery, validate hypotheses, and generate stakeholder-ready research reports — all from a single conversation.
MCP Workflow Guide for UX Researchers
How UX researchers use Koji MCP with Claude to scale qualitative research. Manage multiple studies, analyze transcripts across projects, generate themed reports, and maintain a living research repository.
MCP Workflow Guide for Founders & GTM Teams
How founders and go-to-market teams use Koji MCP with Claude to validate markets, qualify leads through research conversations, and build evidence-based positioning — all without hiring a dedicated researcher.
MCP Best Practices — Getting the Most from Koji + Claude
Tips, patterns, and anti-patterns for using Koji MCP effectively. Learn how to write better prompts, choose methodologies, manage token budgets, and build efficient research workflows with AI.
MCP Authentication & Security
How Koji MCP authenticates with OAuth 2.1 and PKCE. Covers the authorization flow, token lifecycle, security model, data privacy, and how to revoke access.