Documentación del servidor MCP

¿Qué es esto?

El Model Context Protocol es un estándar abierto que permite a los asistentes de IA llamar herramientas y leer datos de sistemas externos de forma segura. El servidor MCP de Votira expone herramientas de lectura para que un asistente pueda responder preguntas sobre tus encuestas y participantes en tu nombre.

Autenticación

Genera una única clave de acceso MCP en Configuración (una clave por cuenta). Se muestra solo una vez. Preséntala como un token Bearer en el endpoint MCP:

Authorization: Bearer vot_mcp_xxxxxxxxxxxxxxxx

Puedes rotar o eliminar la clave en cualquier momento; la rotación invalida inmediatamente el secreto anterior.

Configuración del cliente

Dirige cualquier cliente MCP que soporte el transporte HTTP por streaming al endpoint. Ejemplo de configuración del cliente:

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

Herramientas disponibles

Herramienta	Argumentos	Devuelve
`list_surveys`	—	Tus encuestas con id, título, estado y número de respuestas.
`get_survey`	`survey_id`	Una encuesta con sus preguntas y ajustes.
`get_survey_responses`	`survey_id`, `limit?`, `offset?`	Respuestas paginadas de una encuesta.
`get_survey_analysis`	`survey_id`	Análisis AI en caché de la encuesta completa y por pregunta.

Métodos del protocolo

El endpoint implementa los métodos principales MCP JSON‑RPC: initialize, tools/list y tools/call (más ping). Ejemplo de listado de herramientas:

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

Ejecutar una herramienta

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

Seguridad & límites

Las herramientas son solo de lectura y siempre limitadas a los datos del propietario de la clave.
Un plan de cuenta inactivo devuelve 403 Forbidden.
El endpoint tiene límite de solicitudes (600 por hora y cliente).
No se escribe información personal identificable en los registros del servidor.