Skip to content

Available Tools Reference

!!! info "TL;DR" The MCP server exposes 12 tools for surveys, responses, workflows, and analytics. Each tool requires specific scopes. See table below for full reference.

Tool List

Tool Description Required Scopes
create_survey Create a new survey with questions surveys:write
update_survey Modify existing survey surveys:write
publish_survey Change survey status to active surveys:publish
list_surveys Get all surveys with filters surveys:read
get_survey Get survey details and questions surveys:read
delete_survey Delete a survey surveys:write
submit_response Submit a survey response responses:write
list_responses Get responses for a survey responses:read
get_analytics Get survey analytics analytics:read
get_sentiment Get sentiment analysis results sentiment:read
create_workflow Create an automated workflow workflows:write
trigger_workflow Execute a workflow workflows:execute

Survey Tools

create_survey

Creates a new survey with questions, targeting rules, and display settings.

Scopes: surveys:write

Parameters:

{
  title: string                    // Survey title
  description?: string             // Optional description
  questions: Array<{
    type: 'multiple_choice' | 'text' | 'rating' | 'nps' | 'csat' | 'matrix'
    text: string
    required?: boolean
    options?: string[]             // For multiple_choice, matrix
    min_value?: number             // For rating
    max_value?: number             // For rating
  }>
  targeting?: {
    user_segment?: string          // SQL filter expression
    page_url?: string              // Trigger on specific pages
    event?: string                 // Trigger on event
  }
  settings?: {
    allow_multiple_responses?: boolean
    show_branding?: boolean
    redirect_url?: string
  }
}

Returns:

{
  "survey_id": "uuid",
  "status": "draft",
  "url": "https://canviq.app/surveys/:id"
}

update_survey

Updates an existing survey. Cannot modify questions on active surveys.

Scopes: surveys:write

Parameters:

{
  survey_id: string
  title?: string
  description?: string
  settings?: {...}  // Same as create_survey
}

publish_survey

Changes survey status from draft to active. Once active, responses can be collected.

Scopes: surveys:publish

Parameters:

{
  survey_id: string
}

list_surveys

Gets all surveys with optional filters.

Scopes: surveys:read

Parameters:

{
  status?: 'draft' | 'active' | 'paused' | 'closed'
  limit?: number    // Default 50, max 100
  offset?: number
}

Returns:

{
  "surveys": [
    {
      "id": "uuid",
      "title": "...",
      "status": "active",
      "response_count": 42,
      "created_at": "..."
    }
  ],
  "total": 123
}

get_survey

Gets full survey details including questions.

Scopes: surveys:read

Parameters:

{
  survey_id: string
}

delete_survey

Deletes a survey. Cannot delete surveys with responses unless force: true.

Scopes: surveys:write

Parameters:

{
  survey_id: string
  force?: boolean  // Delete even if responses exist
}

Response Tools

submit_response

Submits a response to a survey.

Scopes: responses:write

Parameters:

{
  survey_id: string
  user_id?: string          // Optional, for tracking
  answers: Array<{
    question_id: string
    value: string | number | string[]  // Depends on question type
  }>
}

list_responses

Gets responses for a survey.

Scopes: responses:read

Parameters:

{
  survey_id: string
  limit?: number
  offset?: number
  start_date?: string   // ISO 8601
  end_date?: string
}

Analytics Tools

get_analytics

Gets aggregated analytics for a survey.

Scopes: analytics:read

Parameters:

{
  survey_id: string
  metrics?: string[]  // ['completion_rate', 'avg_time', 'nps_score']
}

Returns:

{
  "response_count": 150,
  "completion_rate": 0.87,
  "avg_completion_time": 120,
  "nps_score": 42,
  "breakdown_by_question": [...]
}

get_sentiment

Gets sentiment analysis results for text responses.

Scopes: sentiment:read

Parameters:

{
  survey_id: string
  question_id?: string  // Filter by question
}

Returns:

{
  "overall_sentiment": 0.65, // -1 to 1
  "positive_count": 80,
  "neutral_count": 50,
  "negative_count": 20,
  "themes": ["performance", "usability", "design"]
}

Workflow Tools

create_workflow

Creates an automated workflow that triggers on events.

Scopes: workflows:write

Parameters:

{
  name: string
  trigger: {
    type: 'survey_response' | 'submission_created' | 'vote_threshold'
    conditions: {...}
  }
  actions: Array<{
    type: 'send_email' | 'create_github_issue' | 'update_status' | 'slack_notify'
    params: {...}
  }>
}

trigger_workflow

Manually executes a workflow.

Scopes: workflows:execute

Parameters:

{
  workflow_id: string
  context?: Record<string, unknown>  // Override trigger data
}

What's Next