Documentazione MCP Server

Cos’è questo?

Il Model Context Protocol è uno standard aperto per collegare assistenti AI a sistemi esterni. Votira offre strumenti per sondaggio, risultati, AI Panel e account, con autorizzazioni esplicite per modifiche e utilizzo AI.

Autenticazione

Genera una singola chiave di accesso MCP in Impostazioni (una chiave per account). Viene mostrata solo una volta. Presentala come Bearer token sull’endpoint MCP:

Authorization: Bearer vot_mcp_xxxxxxxxxxxxxxxx

Puoi ruotare oppure elimina la chiave in qualsiasi momento; la rotazione invalida immediatamente il segreto precedente.

Configurazione client

Configura qualsiasi client MCP che supporti il trasporto HTTP streamable verso l’endpoint. Esempio di configurazione client:

{
  "mcpServers": {
    "votira": {
      "url": "https://votira.co/mcp",
      "headers": { "Authorization": "Bearer vot_mcp_xxxxxxxx" }
    }
  }
}

Strumenti disponibili

Strumento	Argomenti	Restituisce
`list_surveys`	—	I tuoi sondaggi con id, titolo, stato e numero di risposte.
`get_survey`	`survey_id`	Un sondaggio con le sue domande e impostazioni.
`get_survey_responses`	`survey_id`, `limit?`, `offset?`	Risposte paginati per un sondaggio.
`get_survey_analysis`	`survey_id`	Analisi AI in cache sull’intero sondaggio e per singola domanda.

Permessi e strumenti avanzati

Le nuove e le attuali chiavi MCP sono di sola lettura per impostazione predefinita. Abilita esplicitamente i permessi di scrittura, eliminazione e AI-crediti nelle Impostazioni. La rotazione mantiene i permessi selezionati; i visualizzatori dell’organizzazione non possono effettuare modifiche.

Gli strumenti di modifica richiedono il permesso di scrittura, quelli distruttivi richiedono il permesso di eliminazione, e gli strumenti AI a pagamento richiedono entrambi. Controlla gli argomenti dello strumento prima di approvare un’operazione di scrittura o che consuma crediti nel tuo assistente.

I risultati JSON includono structuredContent. Le esportazioni di file vengono restituite come risorse MCP incorporate: testo per CSV e JSON, blob base64 per PDF. Le operazioni asincrone restituiscono jobId; usa get_ai_job per recuperare stato e risultato.

Gli strumenti di gestione e audit dell’organizzazione richiedono privilegi da amministratore. Le chiavi API personali, le password, gli acquisti e l’eliminazione dell’account non sono disponibili come strumenti.

get_integration_capabilities

Visualizza operazioni disponibili, schemi, permessi e limiti.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}

create_survey

Crea un sondaggio, incluse pagine, domande e impostazioni.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "payload": {
      "type": "object"
    }
  },
  "required": [
    "payload"
  ],
  "type": "object"
}

update_survey

Aggiorna contenuto, pagine, programmazione e aspetto del sondaggio.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "payload": {
      "type": "object"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id",
    "payload"
  ],
  "type": "object"
}

duplicate_survey

Duplica un sondaggio come nuovo bozza senza risposte.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "title": {
      "maxLength": 2000,
      "type": "string"
    }
  },
  "required": [
    "survey_id"
  ],
  "type": "object"
}

set_survey_status

Pubblica, chiudi o riporta un sondaggio a bozza.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "status": {
      "enum": [
        "draft",
        "published",
        "closed"
      ]
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id",
    "status"
  ],
  "type": "object"
}

delete_survey

Elimina definitivamente un sondaggio, risposte, immagini, analisi e visualizzazioni.

Permessi richiesti: delete

{
  "additionalProperties": false,
  "properties": {
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id"
  ],
  "type": "object"
}

list_templates

Elenca i modelli di sondaggio localizzati.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}

get_template

Visualizza un modello localizzato con domande e tema.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {
    "template_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "template_id"
  ],
  "type": "object"
}

create_survey_from_template

Crea un sondaggio localizzato da un modello senza crediti AI.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "template_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "title": {
      "maxLength": 2000,
      "type": "string"
    }
  },
  "required": [
    "template_id"
  ],
  "type": "object"
}

get_question_types

Elenca tutti i tipi di domanda supportati e i campi di configurazione specifici per tipo.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}

add_question

Aggiungi una domanda al sondaggio.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "question": {
      "type": "object"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id",
    "question"
  ],
  "type": "object"
}

update_question

Aggiorna una domanda mantenendo la sua identità.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "question": {
      "type": "object"
    },
    "question_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id",
    "question_id",
    "question"
  ],
  "type": "object"
}

delete_question

Elimina una domanda e ripara i riferimenti di ramificazione.

Permessi richiesti: delete

{
  "additionalProperties": false,
  "properties": {
    "question_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id",
    "question_id"
  ],
  "type": "object"
}

reorder_questions

Riordina tutte le domande, mantenendo l'ordine principale delle pagine.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "order": {
      "items": {
        "maxLength": 100,
        "minLength": 1,
        "pattern": "^[A-Za-z0-9_-]+$",
        "type": "string"
      },
      "maxItems": 50,
      "type": "array",
      "uniqueItems": true
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id",
    "order"
  ],
  "type": "object"
}

get_survey_preview

Ottieni domande A/B risolte senza registrare una visualizzazione. Usa respondent_id per abbinare invii JSON successivi.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {
    "respondent_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "seed": {
      "maxLength": 2000,
      "type": "string"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id"
  ],
  "type": "object"
}

generate_survey_questions

Genera domande da un'idea o modifica domande esistenti in modo incrementale. Costa un credito; può restituire un job.

Permessi richiesti: write, ai

{
  "additionalProperties": false,
  "properties": {
    "idea": {
      "maxLength": 2000,
      "type": "string"
    },
    "pages": {
      "items": {
        "type": "object"
      },
      "maxItems": 20,
      "type": "array"
    },
    "questions": {
      "items": {
        "type": "object"
      },
      "maxItems": 50,
      "type": "array"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "idea"
  ],
  "type": "object"
}

get_ai_job

Visualizza stato e risultato di un job AI di proprietà di questo account.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {
    "job_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "job_id"
  ],
  "type": "object"
}

generate_question_analysis

Analizza una domanda a testo libero. I risultati memorizzati sono gratuiti; l'analisi nuova costa un credito.

Permessi richiesti: write, ai

{
  "additionalProperties": false,
  "properties": {
    "question_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id",
    "question_id"
  ],
  "type": "object"
}

generate_survey_analysis

Genera l'analisi AI del sondaggio. I risultati memorizzati sono gratuiti; l'analisi nuova costa un credito.

Permessi richiesti: write, ai

{
  "additionalProperties": false,
  "properties": {
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id"
  ],
  "type": "object"
}

get_ai_credits

Visualizza crediti AI disponibili, limiti, consumo e costi delle operazioni.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}

list_personas

Elenca persone in un pannello personale o organizzativo, eventualmente limitate a un pool.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {
    "pool_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

get_persona

Visualizza una persona sintetica.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {
    "persona_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "persona_id"
  ],
  "type": "object"
}

create_persona

Crea manualmente una persona senza consumare crediti AI.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "attributes": {
      "type": "object"
    },
    "name": {
      "maxLength": 2000,
      "type": "string"
    },
    "poolIds": {
      "items": {
        "maxLength": 100,
        "minLength": 1,
        "pattern": "^[A-Za-z0-9_-]+$",
        "type": "string"
      },
      "maxItems": 500,
      "type": "array",
      "uniqueItems": true
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "type": "object"
}

update_persona

Modifica attributi della persona e sostituisci le appartenenze ai pool se fornito.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "attributes": {
      "type": "object"
    },
    "name": {
      "maxLength": 2000,
      "type": "string"
    },
    "persona_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "poolIds": {
      "items": {
        "maxLength": 100,
        "minLength": 1,
        "pattern": "^[A-Za-z0-9_-]+$",
        "type": "string"
      },
      "maxItems": 500,
      "type": "array",
      "uniqueItems": true
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "persona_id"
  ],
  "type": "object"
}

delete_persona

Elimina una persona dal pannello.

Permessi richiesti: delete

{
  "additionalProperties": false,
  "properties": {
    "persona_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "persona_id"
  ],
  "type": "object"
}

list_pools

Elenca pool nominati e il conteggio delle persone.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

get_pool

Visualizza un pool nominato e le sue persone.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {
    "pool_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "pool_id"
  ],
  "type": "object"
}

create_pool

Crea un pool di persone nominato.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "description": {
      "maxLength": 2000,
      "type": "string"
    },
    "name": {
      "maxLength": 2000,
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "type": "object"
}

update_pool

Rinomina un pool o aggiorna la sua descrizione.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "description": {
      "maxLength": 2000,
      "type": "string"
    },
    "name": {
      "maxLength": 2000,
      "type": "string"
    },
    "pool_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "pool_id"
  ],
  "type": "object"
}

delete_pool

Elimina un pool e scollega i suoi membri senza eliminare le persone.

Permessi richiesti: delete

{
  "additionalProperties": false,
  "properties": {
    "pool_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "pool_id"
  ],
  "type": "object"
}

assign_pool_personas

Aggiungi o rimuovi persone da un pool in modo massivo.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "action": {
      "enum": [
        "add",
        "remove"
      ]
    },
    "personaIds": {
      "items": {
        "maxLength": 100,
        "minLength": 1,
        "pattern": "^[A-Za-z0-9_-]+$",
        "type": "string"
      },
      "maxItems": 500,
      "type": "array",
      "uniqueItems": true
    },
    "pool_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "pool_id",
    "personaIds",
    "action"
  ],
  "type": "object"
}

import_personas

Importa persone da JSON. I metadati del pool vengono ignorati; le persone importate non sono assegnate.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "personas": {
      "items": {
        "type": "object"
      },
      "maxItems": 200,
      "minItems": 1,
      "type": "array"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "personas"
  ],
  "type": "object"
}

export_personas

Esporta persone o un pool come JSON o CSV.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {
    "format": {
      "enum": [
        "json",
        "csv"
      ]
    },
    "persona_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "pool_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

generate_personas

Genera persone con AI. Costa cinque crediti per persona, con rimborsi per risultati mancanti.

Permessi richiesti: write, ai

{
  "additionalProperties": false,
  "properties": {
    "ageMax": {
      "maximum": 120,
      "minimum": 13,
      "type": "integer"
    },
    "ageMin": {
      "maximum": 120,
      "minimum": 13,
      "type": "integer"
    },
    "count": {
      "maximum": 50,
      "minimum": 1,
      "type": "integer"
    },
    "description": {
      "maxLength": 2000,
      "type": "string"
    },
    "extra": {
      "maxLength": 2000,
      "type": "string"
    },
    "genderMix": {
      "additionalProperties": false,
      "properties": {
        "female": {
          "maximum": 50,
          "minimum": 0,
          "type": "integer"
        },
        "male": {
          "maximum": 50,
          "minimum": 0,
          "type": "integer"
        },
        "non_binary": {
          "maximum": 50,
          "minimum": 0,
          "type": "integer"
        }
      },
      "type": "object"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    }
  },
  "required": [
    "description"
  ],
  "type": "object"
}

estimate_panel_cost

Stima i crediti necessari per somministrare un sondaggio a un pool nominato.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {
    "pool_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "pool_id",
    "survey_id"
  ],
  "type": "object"
}

administer_panel

Somministra un sondaggio a un pool nominato. Costa tre crediti per persona; può restituire un job.

Permessi richiesti: write, ai

{
  "additionalProperties": false,
  "properties": {
    "pool_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "scope": {
      "enum": [
        "user",
        "org"
      ],
      "type": "string"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "pool_id",
    "survey_id"
  ],
  "type": "object"
}

get_survey_results

Visualizza statistiche per domanda, suddivisioni A/B, visualizzazioni, conteggi AI-panel e analisi drop-off.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id"
  ],
  "type": "object"
}

get_partial_responses

Visualizza le risposte in corso, separate da quelle completate.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {
    "limit": {
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    },
    "offset": {
      "maximum": 100000,
      "minimum": 0,
      "type": "integer"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id"
  ],
  "type": "object"
}

export_survey_results

Scarica le risposte completate in formato CSV (fino a 5000 per pagina) o un report dei risultati in PDF.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {
    "format": {
      "enum": [
        "csv",
        "pdf"
      ]
    },
    "offset": {
      "maximum": 100000,
      "minimum": 0,
      "type": "integer"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id"
  ],
  "type": "object"
}

upload_survey_image

Carica un'immagine PNG, JPEG, GIF o WebP codificata in base64 (massimo 5 MB) per il tema del sondaggio.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "content": {
      "maxLength": 6990510,
      "type": "string"
    },
    "contentType": {
      "enum": [
        "image/png",
        "image/jpeg",
        "image/gif",
        "image/webp"
      ]
    },
    "field": {
      "enum": [
        "headerImage",
        "backgroundImage"
      ]
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id",
    "field",
    "contentType",
    "content"
  ],
  "type": "object"
}

submit_survey_response

Invia una risposta completata per un rispondente esterno; applica regole di pubblicazione, programmazione, ramificazione e duplicati.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "answers": {
      "type": "object"
    },
    "completionTimeSeconds": {
      "maximum": 604800,
      "minimum": 0,
      "type": "integer"
    },
    "respondentInfo": {
      "type": "object"
    },
    "respondent_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id",
    "respondent_id",
    "answers"
  ],
  "type": "object"
}

save_partial_response

Salvataggio automatico della risposta parziale di un rispondente esterno quando la raccolta è abilitata.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "answers": {
      "type": "object"
    },
    "completionTimeSeconds": {
      "maximum": 604800,
      "minimum": 0,
      "type": "integer"
    },
    "respondentInfo": {
      "type": "object"
    },
    "respondent_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "survey_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "survey_id",
    "respondent_id",
    "answers"
  ],
  "type": "object"
}

get_account

Visualizza profilo, lingua, dominio, piano e accesso all'organizzazione.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}

update_account

Aggiorna nome visualizzato, lingua del servizio o dominio personalizzato. Non modifica email, credenziali o fatturazione.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "customDomain": {
      "maxLength": 253,
      "type": [
        "string",
        "null"
      ]
    },
    "displayName": {
      "maxLength": 100,
      "minLength": 2,
      "type": "string"
    },
    "preferredLanguage": {
      "maxLength": 10,
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

get_organization

Visualizza l'organizzazione, licenze disponibili e crediti AI condivisi.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}

list_organization_members

Elenca membri dell'organizzazione, ruoli, licenze e consumo AI. Solo amministratori.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}

add_organization_member

Aggiungi un account Votira esistente all'organizzazione. Solo amministratori.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "email": {
      "maxLength": 254,
      "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
      "type": "string"
    },
    "role": {
      "enum": [
        "viewer",
        "editor",
        "admin"
      ]
    }
  },
  "required": [
    "email",
    "role"
  ],
  "type": "object"
}

update_organization_member

Aggiorna il ruolo o la licenza assegnata a un membro. Solo amministratori; il proprietario è protetto.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "hasLicense": {
      "type": "boolean"
    },
    "member_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    },
    "role": {
      "enum": [
        "viewer",
        "editor",
        "admin"
      ]
    }
  },
  "required": [
    "member_id"
  ],
  "type": "object"
}

remove_organization_member

Rimuovi un membro senza eliminare il suo account. Solo amministratori.

Permessi richiesti: delete

{
  "additionalProperties": false,
  "properties": {
    "member_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "member_id"
  ],
  "type": "object"
}

list_organization_invites

Elenca inviti dell'organizzazione senza mostrare i token di invito. Solo amministratori.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {},
  "required": [],
  "type": "object"
}

create_organization_invite

Crea un invito e restituisci il suo URL di condivisione. Solo amministratori.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "email": {
      "maxLength": 254,
      "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
      "type": "string"
    },
    "role": {
      "enum": [
        "viewer",
        "editor",
        "admin"
      ]
    },
    "type": {
      "enum": [
        "member",
        "guest"
      ]
    }
  },
  "required": [
    "role"
  ],
  "type": "object"
}

revoke_organization_invite

Revoca un invito pendente dell'organizzazione. Solo amministratori.

Permessi richiesti: delete

{
  "additionalProperties": false,
  "properties": {
    "invite_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "invite_id"
  ],
  "type": "object"
}

get_audit_log

Cerca nel registro delle attività dell'organizzazione. Solo amministratori Enterprise.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {
    "category": {
      "enum": [
        "auth",
        "survey",
        "results",
        "ai",
        "keys",
        "billing",
        "organization",
        "profile",
        "audit",
        "api",
        "mcp"
      ]
    },
    "date_from": {
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "type": "string"
    },
    "date_to": {
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "type": "string"
    },
    "limit": {
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    },
    "offset": {
      "maximum": 100000,
      "minimum": 0,
      "type": "integer"
    },
    "search": {
      "maxLength": 100,
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

export_audit_log

Esporta fino a 5000 voci di audit come CSV. Solo amministratori Enterprise.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {
    "category": {
      "enum": [
        "auth",
        "survey",
        "results",
        "ai",
        "keys",
        "billing",
        "organization",
        "profile",
        "audit",
        "api",
        "mcp"
      ]
    },
    "date_from": {
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "type": "string"
    },
    "date_to": {
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "type": "string"
    },
    "limit": {
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    },
    "offset": {
      "maximum": 100000,
      "minimum": 0,
      "type": "integer"
    },
    "search": {
      "maxLength": 100,
      "type": "string"
    }
  },
  "required": [],
  "type": "object"
}

list_invoices

Elenca fatture personali pagate e, per gli amministratori, fatture dell'organizzazione.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {
    "limit": {
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    },
    "offset": {
      "maximum": 100000,
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [],
  "type": "object"
}

download_invoice

Scarica un PDF di fattura pagata dopo aver verificato la proprietà della fatturazione dell'account.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {
    "invoice_id": {
      "maxLength": 100,
      "pattern": "^in_[A-Za-z0-9]+$",
      "type": "string"
    }
  },
  "required": [
    "invoice_id"
  ],
  "type": "object"
}

list_support_requests

Elenca ticket di supporto, segnalazioni di bug e richieste di funzionalità dell'account.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {
    "limit": {
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    },
    "offset": {
      "maximum": 100000,
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [],
  "type": "object"
}

get_support_request

Visualizza una richiesta di supporto e le risposte del team, limitate al suo proprietario.

Permessi richiesti: read

{
  "additionalProperties": false,
  "properties": {
    "submission_id": {
      "maxLength": 100,
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_-]+$",
      "type": "string"
    }
  },
  "required": [
    "submission_id"
  ],
  "type": "object"
}

create_support_request

Apri un ticket di supporto, segnala un bug o richiedi una funzionalità.

Permessi richiesti: write

{
  "additionalProperties": false,
  "properties": {
    "category": {
      "enum": [
        "bug",
        "feature",
        "ticket"
      ]
    },
    "description": {
      "maxLength": 5000,
      "minLength": 10,
      "type": "string"
    },
    "priority": {
      "enum": [
        "low",
        "normal",
        "high",
        "urgent"
      ]
    },
    "problemSolved": {
      "maxLength": 5000,
      "type": "string"
    },
    "severity": {
      "enum": [
        "low",
        "medium",
        "high",
        "critical"
      ]
    },
    "stepsToReproduce": {
      "maxLength": 5000,
      "type": "string"
    },
    "subject": {
      "maxLength": 150,
      "minLength": 3,
      "type": "string"
    },
    "ticketCategory": {
      "enum": [
        "billing",
        "technical",
        "account",
        "other"
      ]
    }
  },
  "required": [
    "category",
    "subject",
    "description"
  ],
  "type": "object"
}

Metodi del protocollo

L’endpoint implementa i metodi principali MCP JSON‑RPC: initialize, tools/list e tools/call (più ping). Esempio di elenco strumenti:

curl -X POST https://votira.co/mcp \
  -H "Authorization: Bearer $VOTIRA_MCP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Esegui uno strumento

curl -X POST https://votira.co/mcp \
  -H "Authorization: Bearer $VOTIRA_MCP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"get_survey","arguments":{"survey_id":"srv_123"}}}'

Sicurezza & limiti

Gli strumenti sono limitati all'account autenticato e alle risorse autorizzate dell'organizzazione. Le scritture e l'utilizzo dei crediti AI richiedono permessi espliciti.
Un piano account inattivo restituisce 403 Forbidden.
L’endpoint è soggetto a rate limit (600 richieste/ora per client).
Nessuna informazione personale identificabile viene scritta nei log del server.

Votira MCP Server

Cos’è questo?

Autenticazione

Configurazione client

Strumenti disponibili

Permessi e strumenti avanzati

Metodi del protocollo

Sicurezza & limiti

Basta ipotesi. Inizia a validare.