Documentação do Servidor MCP

O que é isto?

O Model Context Protocol é um padrão aberto que permite aos assistentes de IA aceder de forma segura a ferramentas e dados de sistemas externos. O servidor MCP da Votira disponibiliza ferramentas de leitura para que um assistente possa responder a perguntas sobre os seus questionários e respondentes em seu nome.

Autenticação

Gere uma única chave de acesso MCP em Configurações (uma chave por conta). Só é apresentada uma vez. Utilize-a como token Bearer no endpoint MCP:

Authorization: Bearer vot_mcp_xxxxxxxxxxxxxxxx

Pode rodar ou eliminar a chave a qualquer momento; a rotação invalida imediatamente o segredo anterior.

Configuração do cliente

Aponte qualquer cliente MCP que suporte o transporte HTTP streamable para o endpoint. Exemplo de configuração do cliente:

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

Ferramentas disponíveis

Ferramenta	Argumentos	Retorna
`list_surveys`	—	Os seus inquéritos com id, título, estado e número de respostas.
`get_survey`	`survey_id`	Um inquérito com as suas perguntas e definições.
`get_survey_responses`	`survey_id`, `limit?`, `offset?`	Respostas paginadas de um inquérito.
`get_survey_analysis`	`survey_id`	Análise AI em cache para o inquérito completo e por pergunta.

Métodos do protocolo

O endpoint implementa os métodos principais MCP JSON‑RPC: initialize, tools/list e tools/call (mais ping). Exemplo de listagem de ferramentas:

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"}'

Executar uma ferramenta

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"}}}'

Segurança & limites

As ferramentas são apenas de leitura e sempre limitadas aos dados do proprietário da chave.
Um plano de conta inativo retorna 403 Forbidden.
O endpoint tem limite de taxa (600 pedidos/hora por cliente).
Nenhuma informação pessoal identificável é registada nos logs do servidor.