Servidor MCP
Conecte Claude, Cursor e outros assistentes de IA ao SurveyNinja via Protocolo de Contexto de Modelo
MCP Server
Model Context Protocol (MCP) é um padrão que permite que modelos de IA (Claude, Cursor, Copilot, etc.) se conectem ao SurveyNinja e trabalhem com seus dados diretamente — lendo pesquisas, respostas, análises e realizando ações sem cópia manual.
1. Conexão
Obtendo uma chave de API
- Faça login em sua conta do SurveyNinja.
- Acesse Settings → API / MCP.
- Clique em "Criar chave de API" e copie-a — a chave é exibida apenas uma vez.
Endpoint
Autenticação
Passe a chave de API no cabeçalho Authorization :
Configuração para Claude Desktop
Arquivo claude_desktop_config.json
{ "mcpServers": { "surveyninja": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-fetch"], "env": { "MCP_URL": "https://mcp.surveyninja.io/mcp/v1", "MCP_AUTH_HEADER": "Authorization", "MCP_AUTH_VALUE": "Bearer <your_api_key>" } } } } Configuração para Cursor / VS Code
{ "mcp.servers": { "surveyninja": { "url": "https://mcp.surveyninja.io/mcp/v1", "headers": { "Authorization": "Bearer <your_api_key>" } } } } Limites de taxa
- 180 requisições por minuto por usuário (tools/call, resources/read, etc.)
- Os links de exportação são válidos por 1 hora
2. Recursos
Os recursos são somente leitura. Para utilizá-los, envie uma requisição resources/read com o URI correspondente.
| URI | Descrição |
|---|---|
| Usuário e espaços de trabalho | |
| user://me | Informações básicas sobre o usuário atual |
| workspace://list | Lista de todos os espaços de trabalho do usuário |
| Pastas e pesquisas | |
| folder://list | Lista de todas as pastas do usuário |
| quiz://list | Lista de todas as pesquisas disponíveis |
| Estrutura e configuração da pesquisa | |
| quiz://{'{id}'}/structure | Estrutura completa de widgets da pesquisa |
| quiz://{'{id}'}/texts | Rótulos personalizados da interface do usuário |
| quiz://{'{id}'}/variables | Variáveis ocultas (campos adicionais) |
| quiz://{'{id}'}/hidden_options | Opções de configuração de serviço da pesquisa |
| quiz://{'{id}'}/widgets_hidden | Metadados de widgets ocultos |
| Respostas e análises | |
| quiz://{'{id}'}/answers | Lista paginada de respostas dos entrevistados |
| quiz://{'{id}'}/summary | Análises de resumo (funil, dispositivos, geo) |
| quiz://{'{id}'}/report | Relatório detalhado de widgets (com filtros) |
| quiz://{'{id}'}/report_filters | Filtros salvos do usuário |
| quiz://{'{id}'}/report/{'{uuid}'}/inputs | Respostas de texto para widgets de entrada |
| quiz://{'{id}'}/report/{'{uuid}'}/files | Arquivos enviados pelos entrevistados |
| Temas e códigos promocionais | |
| theme://list | Lista de temas do espaço de trabalho |
| theme://{'{id}'}/details | Configurações detalhadas do tema |
| promocode://list | Listas de grupos de códigos promocionais |
| promocode://{'{id}'}/codes | Códigos em uma lista de códigos promocionais específica |
3. Ferramentas
As ferramentas são ações executadas no lado do SurveyNinja mediante solicitação de um modelo de IA pelo método tools/call .
Formato de resposta da ferramenta
Cada ferramenta retorna um objeto com os campos content (array de blocos de texto) e isError (false — sucesso, true — erro). Em caso de sucesso, campos de dados adicionais são incluídos.
Gerenciamento de pesquisas
| Ferramenta | Descrição | Parâmetros obrigatórios |
|---|---|---|
| create_quiz | Cria uma nova pesquisa | folder_id |
| rename_quiz | Renomeia uma pesquisa | quiz_id, name |
| duplicate_quiz | Duplica uma pesquisa | quiz_id |
| archive_quiz | Arquiva / desarquiva | quiz_id, archive |
| delete_quiz | Exclui uma pesquisa (exclusão suave) | quiz_id |
| publish_quiz | Publica a versão atual | quiz_id |
| move_quiz | Move a pesquisa para outra pasta | quiz_id, folder_id |
| make_quiz_template | Cria um modelo a partir de uma pesquisa | quiz_id |
| create_folder | Cria uma pasta de pesquisas | workspace_id, name |
Conteúdo e estrutura da pesquisa
| Ferramenta | Descrição | Parâmetros obrigatórios |
|---|---|---|
| update_quiz_widgets | Salva a estrutura de widgets | quiz_id, ids, entities |
| update_quiz_texts | Atualiza os textos de botões e elementos (plano pago) | quiz_id, texts |
| update_quiz_settings | Atualiza as configurações da pesquisa (idioma, limites, tema, scripts, etc.) | quiz_id |
| update_quiz_logic | Salva a lógica de transição e pontuação | quiz_id |
| update_quiz_note | Adiciona/atualiza uma nota interna | quiz_id, notes |
| upload_quiz_media | Faz upload de mídia para o bloco multimídia (plano pago) | quiz_id, type |
| upload_quiz_widget_image | Faz upload de imagem para um widget com opções de mídia | quiz_id |
Temas de design
| Ferramenta | Descrição | Parâmetros obrigatórios |
|---|---|---|
| apply_quiz_theme | Aplica um tema a uma pesquisa | quiz_id, theme_id |
| create_theme | Cria um tema e o aplica a uma pesquisa (plano pago) | workspace_id, quiz_id |
| update_theme | Atualiza um tema existente | workspace_id, theme_id |
Variáveis da pesquisa
| Ferramenta | Descrição | Parâmetros obrigatórios |
|---|---|---|
| create_quiz_variable | Cria uma variável oculta (campo adicional) | quiz_id, name |
| update_quiz_variable | Renomeia uma variável | quiz_id, field_id, name |
| delete_quiz_variable | Exclui uma variável | quiz_id, field_id |
Opções ocultas
| Ferramenta | Descrição | Parâmetros obrigatórios |
|---|---|---|
| create_hidden_option | Cria uma opção de serviço da pesquisa | quiz_id, name, value |
| update_hidden_option | Atualiza uma opção da pesquisa | quiz_id, opt_id, name, value |
| delete_hidden_option | Exclui uma opção da pesquisa | quiz_id, opt_id |
| create_widget_hidden_option | Cria uma opção para um widget específico | quiz_id, widget_uuid, name, value |
| update_widget_hidden_option | Atualiza uma opção de widget | quiz_id, opt_id, name, value |
| delete_widget_hidden_option | Exclui uma opção de widget | quiz_id, opt_id |
Respostas, análises e links públicos
| Ferramenta | Descrição | Parâmetros obrigatórios |
|---|---|---|
| toggle_answer_visibility | Oculta/exibe uma resposta | quiz_id, answer_id, is_hide |
| tag_answer | Adiciona/sincroniza etiquetas de resposta | quiz_id, answer_id, tags |
| generate_filtered_report | Gera um relatório com filtros → report_uuid | quiz_id |
| share_summary_link | Link público para o resumo | quiz_id |
| share_report_link | Link público para o relatório | quiz_id |
| share_answers_link | Link público para a lista de respostas | quiz_id |
Exportação
Todas as ferramentas aceitam quiz_id (obrigatório). O link de download é válido por 1 hora.
| Ferramenta | Descrição |
|---|---|
| export_answers_csv | Exportar respostas para CSV |
| export_answers_xlsx | Exportar respostas para XLSX |
| export_answers_word | Exportar respostas para Word |
| export_summary_pdf | Exportar resumo para PDF |
| export_filtered_report_pdf | Exportar relatório filtrado para PDF |
| export_filtered_report_word | Exportar relatório filtrado para Word |
Códigos promocionais (plano pago)
| Ferramenta | Descrição | Parâmetros obrigatórios |
|---|---|---|
| create_promocode_group | Cria uma lista de códigos promocionais | quiz_id, name, codes |
| add_promocodes | Adiciona códigos a uma lista existente | quiz_id, list_id, codes |
4. Detalhes técnicos
Versão do protocolo
2025-06-18
Transporte
HTTP POST (JSON-RPC 2.0)
Método de conexão
POST /mcp/v1
Métodos JSON-RPC padrão
| Método | Descrição |
|---|---|
| initialize | Inicialização de sessão, obtenção de capacidades do servidor |
| tools/list | Listar todas as ferramentas disponíveis |
| tools/call | Chamar uma ferramenta com parâmetros |
| resources/list | Listar todos os recursos disponíveis |
| resources/read | Ler o conteúdo de um recurso por URI |
| prompts/list | Listar modelos de prompt |
| prompts/get | Obter um modelo de prompt específico |
Exemplo de requisição
POST https://mcp.surveyninja.io/mcp/v1 Authorization: Bearer 42|xK7mP9nQ2wL5eH8jR3vU6tY0iD4aF1bG Content-Type: application/json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "rename_quiz", "arguments": { "quiz_id": 123, "name": "New survey name" } } }
Formato de resposta de erro
{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32602, "message": "Invalid params: quiz_id is required" } } 5. Cenários típicos
1. Obter lista de pesquisas e estrutura de uma específica
1. resources/read: quiz://list → obter lista de pesquisas com IDs
2. resources/read: quiz://{'{id}'}/structure → obter a estrutura de widgets
2. Trabalhando com respostas
1. resources/read: quiz://{'{id}'}/answers → obter respostas (com answer_id)
2. tools/call: tag_answer (adicionar etiquetas) ou toggle_answer_visibility (ocultar/exibir)
3. Exportação com filtragem
1. tools/call: generate_filtered_report (quiz_id, dateFrom/dateTo d.m.Y formato, filters) → report_uuid
⚠ O formato de data aqui é d.m.Y (01.01.2024), enquanto o recurso quiz://report usa Y-m-d
2. resources/read: quiz://{'{id}'}/report/{'{uuid}'}/files ou /inputs
3. tools/call: export_filtered_report_pdf (quiz_id) → PDF link
⚠ export_filtered_report_pdf e _word aceitam apenas quiz_id; report_uuid não deve ser passado
4. Adicionando códigos promocionais
1. tools/call: create_promocode_group → criar uma lista com códigos iniciais → obter list_id
2. tools/call: add_promocodes → adicionar mais códigos à lista
3. resources/read: promocode://{'{list_id}'}/codes → verificar os códigos adicionados
5. Aplicar um tema e obter imediatamente a estrutura da pesquisa
1. resources/read: theme://list → obter lista de temas com IDs
2. tools/call: apply_quiz_theme (quiz_id, theme_id)
→ a resposta já inclui um campo quiz com a estrutura — nenhum resources/read adicional é necessário
Documentação completa do MCP em formato markdown para uso com IA: