Servidor MCP
Conecte Claude, Cursor y otros asistentes de IA a SurveyNinja mediante el Protocolo de Contexto de Modelo
MCP Server
Model Context Protocol (MCP) es un estándar que permite a los modelos de IA (Claude, Cursor, Copilot, etc.) conectarse a SurveyNinja y trabajar con sus datos directamente: leer encuestas, respuestas, analíticas y realizar acciones sin copiar manualmente.
1. Conexión
Obtener una clave API
- Inicie sesión en su cuenta de SurveyNinja.
- Vaya a Settings → API / MCP.
- Haga clic en "Crear clave API" y cópiela — la clave solo se muestra una vez.
Endpoint
Autenticación
Pase la clave API en el encabezado Authorization :
Configuración para Claude Desktop
Archivo 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>" } } } } Configuración para Cursor / VS Code
{ "mcp.servers": { "surveyninja": { "url": "https://mcp.surveyninja.io/mcp/v1", "headers": { "Authorization": "Bearer <your_api_key>" } } } } Límites de frecuencia
- 180 solicitudes por minuto por usuario (tools/call, resources/read, etc.)
- Los enlaces de exportación son válidos durante 1 hora
2. Recursos
Los recursos son de solo lectura. Para utilizarlos, envíe una solicitud resources/read con el URI correspondiente.
| URI | Descripción |
|---|---|
| Usuario y espacios de trabajo | |
| user://me | Información básica sobre el usuario actual |
| workspace://list | Lista de todos los espacios de trabajo del usuario |
| Carpetas y encuestas | |
| folder://list | Lista de todas las carpetas del usuario |
| quiz://list | Lista de todas las encuestas disponibles |
| Estructura y configuración de la encuesta | |
| quiz://{'{id}'}/structure | Estructura completa de widgets de la encuesta |
| quiz://{'{id}'}/texts | Etiquetas personalizadas de la interfaz de usuario |
| quiz://{'{id}'}/variables | Variables ocultas (campos adicionales) |
| quiz://{'{id}'}/hidden_options | Opciones de configuración de servicio de la encuesta |
| quiz://{'{id}'}/widgets_hidden | Metadatos de widgets ocultos |
| Respuestas y analíticas | |
| quiz://{'{id}'}/answers | Lista paginada de respuestas de encuestados |
| quiz://{'{id}'}/summary | Analíticas de resumen (embudo, dispositivos, geo) |
| quiz://{'{id}'}/report | Informe detallado de widgets (con filtros) |
| quiz://{'{id}'}/report_filters | Filtros guardados del usuario |
| quiz://{'{id}'}/report/{'{uuid}'}/inputs | Respuestas de texto para widgets de entrada |
| quiz://{'{id}'}/report/{'{uuid}'}/files | Archivos subidos por los encuestados |
| Temas y códigos promocionales | |
| theme://list | Lista de temas del espacio de trabajo |
| theme://{'{id}'}/details | Configuración detallada del tema |
| promocode://list | Listas de grupos de códigos promocionales |
| promocode://{'{id}'}/codes | Códigos en una lista de códigos promocionales específica |
3. Herramientas
Las herramientas son acciones ejecutadas en el lado de SurveyNinja a solicitud de un modelo de IA mediante el método tools/call .
Formato de respuesta de herramienta
Cada herramienta devuelve un objeto con los campos content (arreglo de bloques de texto) y isError (false — éxito, true — error). En caso de éxito, se añaden campos de datos adicionales.
Gestión de encuestas
| Herramienta | Descripción | Parámetros requeridos |
|---|---|---|
| create_quiz | Crea una nueva encuesta | folder_id |
| rename_quiz | Renombra una encuesta | quiz_id, name |
| duplicate_quiz | Duplica una encuesta | quiz_id |
| archive_quiz | Archiva / desarchiva | quiz_id, archive |
| delete_quiz | Elimina una encuesta (eliminación temporal) | quiz_id |
| publish_quiz | Publica la versión actual | quiz_id |
| move_quiz | Mueve la encuesta a otra carpeta | quiz_id, folder_id |
| make_quiz_template | Crea una plantilla a partir de una encuesta | quiz_id |
| create_folder | Crea una carpeta de encuestas | workspace_id, name |
Contenido y estructura de la encuesta
| Herramienta | Descripción | Parámetros requeridos |
|---|---|---|
| update_quiz_widgets | Guarda la estructura de widgets | quiz_id, ids, entities |
| update_quiz_texts | Actualiza los textos de botones y elementos (plan de pago) | quiz_id, texts |
| update_quiz_settings | Actualiza la configuración de la encuesta (idioma, límites, tema, scripts, etc.) | quiz_id |
| update_quiz_logic | Guarda la lógica de transición y puntuación | quiz_id |
| update_quiz_note | Añade/actualiza una nota interna | quiz_id, notes |
| upload_quiz_media | Sube medios para el bloque multimedia (plan de pago) | quiz_id, type |
| upload_quiz_widget_image | Sube una imagen para un widget con opciones de medios | quiz_id |
Temas de diseño
| Herramienta | Descripción | Parámetros requeridos |
|---|---|---|
| apply_quiz_theme | Aplica un tema a una encuesta | quiz_id, theme_id |
| create_theme | Crea un tema y lo aplica a una encuesta (plan de pago) | workspace_id, quiz_id |
| update_theme | Actualiza un tema existente | workspace_id, theme_id |
Variables de encuesta
| Herramienta | Descripción | Parámetros requeridos |
|---|---|---|
| create_quiz_variable | Crea una variable oculta (campo adicional) | quiz_id, name |
| update_quiz_variable | Renombra una variable | quiz_id, field_id, name |
| delete_quiz_variable | Elimina una variable | quiz_id, field_id |
Opciones ocultas
| Herramienta | Descripción | Parámetros requeridos |
|---|---|---|
| create_hidden_option | Crea una opción de servicio de encuesta | quiz_id, name, value |
| update_hidden_option | Actualiza una opción de encuesta | quiz_id, opt_id, name, value |
| delete_hidden_option | Elimina una opción de encuesta | quiz_id, opt_id |
| create_widget_hidden_option | Crea una opción para un widget específico | quiz_id, widget_uuid, name, value |
| update_widget_hidden_option | Actualiza una opción de widget | quiz_id, opt_id, name, value |
| delete_widget_hidden_option | Elimina una opción de widget | quiz_id, opt_id |
Respuestas, analíticas y enlaces públicos
| Herramienta | Descripción | Parámetros requeridos |
|---|---|---|
| toggle_answer_visibility | Oculta/muestra una respuesta | quiz_id, answer_id, is_hide |
| tag_answer | Añade/sincroniza etiquetas de respuesta | quiz_id, answer_id, tags |
| generate_filtered_report | Genera un informe con filtros → report_uuid | quiz_id |
| share_summary_link | Enlace público al resumen | quiz_id |
| share_report_link | Enlace público al informe | quiz_id |
| share_answers_link | Enlace público a la lista de respuestas | quiz_id |
Exportación
Todas las herramientas aceptan quiz_id (requerido). El enlace de descarga es válido durante 1 hora.
| Herramienta | Descripción |
|---|---|
| export_answers_csv | Exportar respuestas a CSV |
| export_answers_xlsx | Exportar respuestas a XLSX |
| export_answers_word | Exportar respuestas a Word |
| export_summary_pdf | Exportar resumen a PDF |
| export_filtered_report_pdf | Exportar informe filtrado a PDF |
| export_filtered_report_word | Exportar informe filtrado a Word |
Códigos promocionales (plan de pago)
| Herramienta | Descripción | Parámetros requeridos |
|---|---|---|
| create_promocode_group | Crea una lista de códigos promocionales | quiz_id, name, codes |
| add_promocodes | Añade códigos a una lista existente | quiz_id, list_id, codes |
4. Detalles técnicos
Versión del protocolo
2025-06-18
Transporte
HTTP POST (JSON-RPC 2.0)
Método de conexión
POST /mcp/v1
Métodos JSON-RPC estándar
| Método | Descripción |
|---|---|
| initialize | Inicialización de sesión, obtención de capacidades del servidor |
| tools/list | Listar todas las herramientas disponibles |
| tools/call | Llamar a una herramienta con parámetros |
| resources/list | Listar todos los recursos disponibles |
| resources/read | Leer el contenido de un recurso por URI |
| prompts/list | Listar plantillas de prompts |
| prompts/get | Obtener una plantilla de prompt específica |
Ejemplo de solicitud
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 respuesta de error
{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32602, "message": "Invalid params: quiz_id is required" } } 5. Escenarios típicos
1. Obtener la lista de encuestas y la estructura de una específica
1. resources/read: quiz://list → obtener lista de encuestas con IDs
2. resources/read: quiz://{'{id}'}/structure → obtener la estructura de widgets
2. Trabajo con respuestas
1. resources/read: quiz://{'{id}'}/answers → obtener respuestas (con answer_id)
2. tools/call: tag_answer (añadir etiquetas) o toggle_answer_visibility (ocultar/mostrar)
3. Exportación con filtrado
1. tools/call: generate_filtered_report (quiz_id, dateFrom/dateTo d.m.Y formato, filters) → report_uuid
⚠ El formato de fecha aquí es d.m.Y (01.01.2024), mientras que el recurso quiz://report usa Y-m-d
2. resources/read: quiz://{'{id}'}/report/{'{uuid}'}/files o /inputs
3. tools/call: export_filtered_report_pdf (quiz_id) → PDF link
⚠ export_filtered_report_pdf y _word aceptan solo quiz_id; no se debe pasar report_uuid
4. Añadir códigos promocionales
1. tools/call: create_promocode_group → crear una lista con códigos iniciales → obtener list_id
2. tools/call: add_promocodes → añadir más códigos a la lista
3. resources/read: promocode://{'{list_id}'}/codes → verificar los códigos añadidos
5. Aplicar un tema y obtener inmediatamente la estructura de la encuesta
1. resources/read: theme://list → obtener la lista de temas con IDs
2. tools/call: apply_quiz_theme (quiz_id, theme_id)
→ la respuesta ya incluye un campo quiz con la estructura — no se necesita un resources/read adicional
Documentación completa de MCP en formato markdown para trabajar con IA: