MCP Server

Model Context Protocol (MCP) — стандарт, позволяющий ИИ-моделям (Claude, Cursor, Copilot и др.) подключаться к WebAsk и работать с вашими данными напрямую: читать опросы, ответы, аналитику и выполнять действия без ручного копирования.

Содержание

Подключение
Ресурсы (Resources)
Инструменты (Tools)
Технические детали
Типичные сценарии

1. Подключение

Получение API-ключа

Войдите в свой аккаунт WebAsk.
Перейдите в раздел Настройки → API / MCP.
Нажмите «Создать API-ключ» и скопируйте его — ключ показывается только один раз.

Эндпоинт

POST https://mcp.webask.io/mcp/v1

Аутентификация

Передайте API-ключ в заголовке Authorization:

Authorization: Bearer 42|xK7mP9nQ2wL5eH8jR3vU6tY0iD4aF1bG

Конфигурация для Claude Desktop

Файл claude_desktop_config.json

{
  "mcpServers": {
    "webask": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"],
      "env": {
        "MCP_URL": "https://mcp.webask.io/mcp/v1",
        "MCP_AUTH_HEADER": "Authorization",
        "MCP_AUTH_VALUE": "Bearer <ваш_api_ключ>"
      }
    }
  }
}

Конфигурация для Cursor / VS Code

{
  "mcp.servers": {
    "webask": {
      "url": "https://mcp.webask.io/mcp/v1",
      "headers": {
        "Authorization": "Bearer <ваш_api_ключ>"
      }
    }
  }
}

Лимиты

180 запросов в минуту на пользователя (tools/call, resources/read и т.д.)
Экспортные ссылки действуют 1 час

2. Ресурсы (Resources)

Ресурсы предназначены только для чтения данных. Для их вызова отправляется запрос resources/read с соответствующим URI.

URI	Описание
Пользователь и воркспейсы
user://me	Базовая информация о текущем пользователе
workspace://list	Список всех рабочих пространств пользователя
Папки и опросы
folder://list	Список всех папок пользователя
quiz://list	Список всех доступных опросов
Структура и конфигурация опроса
quiz://{'{id}'}/structure	Полная структура виджетов опроса
quiz://{'{id}'}/texts	Пользовательские надписи интерфейса
quiz://{'{id}'}/variables	Скрытые переменные (extra fields)
quiz://{'{id}'}/hidden_options	Служебные конфигурационные опции опроса
quiz://{'{id}'}/widgets_hidden	Скрытая мета-информация виджетов
Ответы и аналитика
quiz://{'{id}'}/answers	Список ответов респондентов с пагинацией
quiz://{'{id}'}/summary	Сводная аналитика (воронка, устройства, гео)
quiz://{'{id}'}/report	Детальный отчёт по виджетам (с фильтрами)
quiz://{'{id}'}/report_filters	Сохранённые фильтры пользователя
quiz://{'{id}'}/report/{'{uuid}'}/inputs	Текстовые ответы на input-виджеты
quiz://{'{id}'}/report/{'{uuid}'}/files	Файлы, загруженные респондентами
Темы и промокоды
theme://list	Список тем оформления воркспейса
theme://{'{id}'}/details	Детальные настройки темы
promocode://list	Списки групп промокодов
promocode://{'{id}'}/codes	Коды в конкретном списке промокодов

3. Инструменты (Tools)

Tools — действия, которые выполняются на стороне WebAsk по запросу ИИ-модели через метод tools/call.

Формат ответа инструментов

Каждый инструмент возвращает объект с полями content (массив текстовых блоков) и isError (false — успех, true — ошибка). При успехе добавляются доп. поля с данными.

Управление опросами

Tool	Описание	Обязательные параметры
create_quiz	Создаёт новый опрос	`folder_id`
rename_quiz	Переименовывает опрос	`quiz_id`, `name`
duplicate_quiz	Создаёт копию опроса	`quiz_id`
archive_quiz	Архивирует / разархивирует	`quiz_id`, `archive`
delete_quiz	Удаляет опрос (мягкое удаление)	`quiz_id`
publish_quiz	Публикует текущую версию	`quiz_id`
move_quiz	Перемещает опрос в другую папку	`quiz_id`, `folder_id`
make_quiz_template	Создаёт шаблон на основе опроса	`quiz_id`
create_folder	Создаёт папку для опросов	`workspace_id`, `name`

Содержимое и структура опроса

Tool	Описание	Обязательные параметры
update_quiz_widgets	Сохраняет структуру виджетов	`quiz_id`, `ids`, `entities`
update_quiz_texts	Обновляет тексты кнопок и элементов (платный тариф)	`quiz_id`, `texts`
update_quiz_settings	Обновляет настройки опроса (язык, лимиты, тема, скрипты и др.)	`quiz_id`
update_quiz_logic	Сохраняет логику переходов и скоринг	`quiz_id`
update_quiz_note	Добавляет/изменяет внутреннюю заметку	`quiz_id`, `notes`
upload_quiz_media	Загрузка медиа для блока multimedia (платный тариф)	`quiz_id`, `type`
upload_quiz_widget_image	Загрузка картинки для виджета с медиавариантами	`quiz_id`

Темы оформления

Tool	Описание	Обязательные параметры
apply_quiz_theme	Применяет тему к опросу	`quiz_id`, `theme_id`
create_theme	Создаёт тему и применяет к опросу (платный тариф)	`workspace_id`, `quiz_id`
update_theme	Обновляет существующую тему	`workspace_id`, `theme_id`

Переменные опроса

Tool	Описание	Обязательные параметры
create_quiz_variable	Создаёт скрытую переменную (extra field)	`quiz_id`, `name`
update_quiz_variable	Переименовывает переменную	`quiz_id`, `field_id`, `name`
delete_quiz_variable	Удаляет переменную	`quiz_id`, `field_id`

Скрытые опции

Tool	Описание	Обязательные параметры
create_hidden_option	Создаёт служебную опцию опроса	`quiz_id`, `name`, `value`
update_hidden_option	Обновляет опцию опроса	`quiz_id`, `opt_id`, `name`, `value`
delete_hidden_option	Удаляет опцию опроса	`quiz_id`, `opt_id`
create_widget_hidden_option	Создаёт опцию конкретного виджета	`quiz_id`, `widget_uuid`, `name`, `value`
update_widget_hidden_option	Обновляет опцию виджета	`quiz_id`, `opt_id`, `name`, `value`
delete_widget_hidden_option	Удаляет опцию виджета	`quiz_id`, `opt_id`

Ответы, аналитика и публичные ссылки

Tool	Описание	Обязательные параметры
toggle_answer_visibility	Скрывает/показывает ответ	`quiz_id`, `answer_id`, `is_hide`
tag_answer	Добавляет/синхронизирует теги ответа	`quiz_id`, `answer_id`, `tags`
generate_filtered_report	Формирует отчёт с фильтрами → `report_uuid`	`quiz_id`
share_summary_link	Публичная ссылка на сводку	`quiz_id`
share_report_link	Публичная ссылка на отчёт	`quiz_id`
share_answers_link	Публичная ссылка на список ответов	`quiz_id`

Экспорт

Все инструменты принимают quiz_id (обязательный). Ссылка на скачивание действует 1 час.

Tool	Описание
export_answers_csv	Экспорт ответов в CSV
export_answers_xlsx	Экспорт ответов в XLSX
export_answers_word	Экспорт ответов в Word
export_summary_pdf	Экспорт сводки в PDF
export_filtered_report_pdf	Экспорт отфильтрованного отчёта в PDF
export_filtered_report_word	Экспорт отфильтрованного отчёта в Word

Промокоды (платный тариф)

Tool	Описание	Обязательные параметры
create_promocode_group	Создаёт список промокодов	`quiz_id`, `name`, `codes`
add_promocodes	Добавляет коды в существующий список	`quiz_id`, `list_id`, `codes`

4. Технические детали

Версия протокола

2025-06-18

Транспорт

HTTP POST (JSON-RPC 2.0)

Метод подключения

POST /mcp/v1

Стандартные JSON-RPC методы

Метод	Описание
initialize	Инициализация сессии, получение capabilities сервера
tools/list	Получить список всех доступных инструментов
tools/call	Вызвать инструмент с параметрами
resources/list	Получить список всех доступных ресурсов
resources/read	Прочитать содержимое ресурса по URI
prompts/list	Получить список prompt-шаблонов
prompts/get	Получить конкретный prompt-шаблон

Пример запроса

POST https://mcp.webask.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": "Новое название опроса"
    }
  }
}

Формат ответа при ошибке

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params: quiz_id is required"
  }
}

5. Типичные сценарии

1. Получить список опросов и структуру конкретного

1. resources/read: quiz://list → получаем список опросов с ID

2. resources/read: quiz://{'{id}'}/structure → получаем структуру виджетов

2. Работа с ответами

1. resources/read: quiz://{'{id}'}/answers → получаем ответы (с answer_id)

2. tools/call: tag_answer (добавить теги) или toggle_answer_visibility (скрыть/показать)

3. Экспорт с фильтрацией

1. tools/call: generate_filtered_report (quiz_id, dateFrom/dateTo в формате d.m.Y, фильтры) → report_uuid

⚠ Формат дат здесь d.m.Y (01.01.2024), тогда как ресурс quiz://report использует Y-m-d

2. resources/read: quiz://{'{id}'}/report/{'{uuid}'}/files или /inputs

3. tools/call: export_filtered_report_pdf (quiz_id) → ссылка на PDF

⚠ export_filtered_report_pdf и _word принимают только quiz_id; report_uuid передавать не нужно

4. Добавление промокодов

1. tools/call: create_promocode_group → создаём список с первыми кодами → получаем list_id

2. tools/call: add_promocodes → добавляем ещё коды в список

3. resources/read: promocode://{'{list_id}'}/codes → проверяем добавленные коды

5. Применить тему и сразу получить структуру опроса

1. resources/read: theme://list → получаем список тем с ID

2. tools/call: apply_quiz_theme (quiz_id, theme_id)

→ в ответе сразу поле quiz со структурой — дополнительный resources/read не нужен

Полная документация MCP в markdown-формате для работы с ИИ:

/static/mcp_user_guide.md — полный справочник ресурсов и инструментов.

AI LLM-формат