Servidor MCP

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

Endpoint

Duas formas de conectar

• Permitir acesso (recomendado). Adicione o endereço do servidor no seu assistente, entre no SurveyNinja quando ele pedir, escolha um espaço de trabalho e clique em Permitir acesso. Não precisa de chave: o assistente trabalha no espaço que você escolheu e renova o acesso sozinho.
• Chave de API. Para clientes que não suportam login, ou quando um assistente deve trabalhar em todos os espaços em que você é dono ou membro. Passe a chave em um cabeçalho, como mostrado abaixo.

Claude

1. No Claude na web ou no app para desktop, abra Settings, depois Connectors, e clique em Add custom connector.
2. Digite um nome, por exemplo SurveyNinja, e o endereço do servidor.
3. Clique em Add, depois em Connect, e permita o acesso no SurveyNinja.

Nos planos Team e Enterprise do Claude, primeiro o dono da organização adiciona o conector e depois cada membro o conecta.

ChatGPT

1. Ative o modo de desenvolvedor nas configurações do ChatGPT. Ele está disponível em alguns planos do ChatGPT.
2. Crie um conector com o endereço do servidor e autenticação OAuth.
3. Permita o acesso no SurveyNinja.

Claude Code

Rode o comando no terminal, depois digite /mcp no Claude Code, selecione surveyninja e entre.

claude mcp add --transport http surveyninja https://mcp.surveyninja.io/mcp/v1

Com as skills prontas, como plugin que adiciona o servidor e todas as skills em uma única instalação:

/plugin marketplace add surveyninjaio/surveyninja-mcp /plugin install surveyninja@surveyninja

Cursor

Adicione o servidor em ~/.cursor/mcp.json para todos os projetos, ou em .cursor/mcp.json para um projeto. Depois abra a seção MCP nas configurações do Cursor e entre no servidor surveyninja.

{
  "mcpServers": {
    "surveyninja": {
      "url": "https://mcp.surveyninja.io/mcp/v1"
    }
  }
}

VS Code

Adicione o servidor em .vscode/mcp.json no seu projeto, inicie-o a partir do arquivo e entre quando o VS Code pedir. O servidor funciona no GitHub Copilot Chat no modo agente.

{
  "servers": {
    "surveyninja": {
      "type": "http",
      "url": "https://mcp.surveyninja.io/mcp/v1"
    }
  }
}

Obtendo uma chave de API

1. Faça login em sua conta do SurveyNinja.
2. Acesse Settings → API / MCP.
3. Clique em "Criar chave de API" e copie-a — a chave é exibida apenas uma vez.

Autenticação

Passe a chave de API no cabeçalho Authorization :

Para um cliente que aceita o formato mcpServers com cabeçalhos, troque YOUR_API_KEY pela sua chave:

{
  "mcpServers": {
    "surveyninja": {
      "url": "https://mcp.surveyninja.io/mcp/v1",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Configurações para cada cliente e as skills como arquivos: github.com/surveyninjaio/surveyninja-mcp.

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.

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 .

Gerenciamento de pesquisas

Conteúdo e estrutura da pesquisa

Temas de design

Variáveis da pesquisa

Opções ocultas

Respostas, análises e links públicos

Exportação

Todas as ferramentas aceitam quiz_id (obrigatório). O link de download é válido por 1 hora.

Códigos promocionais (plano pago)

4. Detalhes técnicos

Métodos JSON-RPC padrão

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