humansurvey-mcp
HumanSurvey
Веб-сайт: humansurvey.co · Документация: humansurvey.co/docs · FAQ: humansurvey.co/faq
Инфраструктура для сбора обратной связи для ИИ-агентов.
HumanSurvey позволяет агенту, выполняющему долгосрочную работу, собирать структурированную обратную связь от группы людей:
Agent is doing a job
→ needs structured feedback from a group
→ creates survey from JSON schema
→ shares /s/{id} URL with respondents
→ humans respond over hours or days
→ agent retrieves structured JSON results and acts on themЧто это такое?
HumanSurvey — это минималистичный API и MCP-сервер для одной узкой задачи: позволить агентам собирать структурированную обратную связь от групп людей и получать машиночитаемые результаты.
Он предназначен для:
ИИ-агентов, управляющих мероприятиями, запуском продуктов или рабочими процессами сообщества, которым необходимо провести опрос группы
Разработчиков, создающих агентские продукты, которым нужен легковесный примитив для сбора обратной связи
Он не предназначен для:
Панелей управления опросами
Визуальных конструкторов форм
Библиотек шаблонов
Email-рассылок
Интерфейсов аналитики/отчетности
Related MCP server: Datapoint MCP
Возможности
Ввод JSON-схемы — структурированный, точный и создаваемый непосредственно машиной
MCP-сервер — создание опросов и чтение результатов прямо из Claude Code
Минимальная поверхность API — аутентифицированные маршруты для создателя, публичная отправка ответов респондентами
Четыре семантических типа вопросов —
choice,text,scale,matrixУсловная логика —
showIfв Markdown и JSON-схемеЯвный жизненный цикл — закрытие опросов, срок действия и ограничение максимального количества ответов
Принципы продукта
Семантика важнее визуализации: HumanSurvey имеет небольшой протокол, а не зоопарк специфических для UI типов полей.
AI-first I/O: агенты создают опрос, а агенты потребляют результаты; люди находятся посередине.
Все есть API: функциональность создателя должна быть доступна через аутентифицированный HTTP и MCP.
Узкая специализация побеждает: если функция в основном обслуживает операторов опросов-людей, скорее всего, ей здесь не место.
Поддерживаемые типы вопросов
single_choicemulti_choicetextscalematrix
Синтаксис Markdown
# Survey Title
**Description:** Instructions for the respondent.
## Section Name
**Q1. Your question here?**
- ☐ Option A
- ☐ Option B
- ☐ Option C
**Q2. Multi-select question?** (select all that apply)
- ☐ Choice 1
- ☐ Choice 2
- ☐ Choice 3
**Q3. Open-ended question:**
> _______________
| # | Item | Rating |
|---|------|--------|
| 1 | Item A | ☐Good ☐OK ☐Bad |
| 2 | Item B | ☐Good ☐OK ☐Bad |Вопросы со шкалой:
**Q4. How severe is this issue?**
[scale 1-5 min-label="Low" max-label="Critical"]Условная логика:
**Q1. Did the deploy fail?**
- ☐ Yes
- ☐ No
**Q2. Which step failed?**
> show if: Q1 = "Yes"
> _______________________________________________Быстрый старт
Использование с Claude Code
Добавьте в конфигурацию Claude Code (~/.claude.json):
{
"mcpServers": {
"survey": {
"command": "npx",
"args": ["-y", "humansurvey-mcp"],
"env": {
"HUMANSURVEY_API_KEY": "hs_sk_your_key_here"
}
}
}
}Затем в Claude Code:
> Create a post-event feedback survey with a 1-5 rating, open text, and a yes/no questionДоступные инструменты:
create_key— самостоятельное получение API-ключа; участие человека не требуетсяcreate_survey— создание на основе JSON-схемы; опциональноmax_responses,expires_at,webhook_urlget_results— агрегированные результаты + необработанные ответыlist_surveys— список опросов, принадлежащих вашему ключуclose_survey— немедленное закрытие опроса
Использование HTTP API
curl -X POST https://www.humansurvey.co/api/keys \
-H "Content-Type: application/json" \
-d '{
"name": "my claude agent",
"email": "you@example.com",
"wallet_address": "eip155:8453:0xabc..."
}'Все поля опциональны. wallet_address использует формат CAIP-10 — в будущем будет использоваться для нативных платежей агентов.
Затем создайте опрос:
curl -X POST https://www.humansurvey.co/api/surveys \
-H "Authorization: Bearer hs_sk_..." \
-H "Content-Type: application/json" \
-d '{
"schema": {
"title": "Post-Event Feedback",
"sections": [{
"questions": [
{ "type": "scale", "label": "How would you rate the event?", "min": 1, "max": 5 },
{ "type": "text", "label": "What should we improve?" }
]
}]
}
}'Ответ:
{
"survey_url": "/s/abc123",
"question_count": 1
}Чтение результатов:
curl https://www.humansurvey.co/api/surveys/abc123/responses \
-H "Authorization: Bearer hs_sk_..."Публичные ресурсы
Страница документации:
https://www.humansurvey.co/docsOpenAPI:
https://www.humansurvey.co/api/openapi.jsonAI-индекс:
https://www.humansurvey.co/llms.txt
Технологический стек
Компонент | Технология |
Фреймворк | Next.js (App Router) |
База данных | Neon (serverless Postgres) |
Парсер | remark (unified ecosystem) |
Фронтенд | React + Tailwind CSS |
MCP-сервер | @modelcontextprotocol/sdk |
Развертывание | Vercel |
Структура проекта
├── apps/web/ # Next.js app (API + frontend)
├── packages/parser/ # Markdown → Survey JSON parser
├── packages/mcp-server/ # MCP server for Claude Code
└── docs/ # Architecture docsУчастие в разработке
Прочитайте CONTRIBUTING.md перед открытием PR. Самое важное правило — дисциплина области применения: новые варианты UI, панели аналитики и функции для операторов-людей обычно выходят за рамки проекта.
Разработка
pnpm install
pnpm dev # Start Next.js dev server
pnpm --filter @mts/parser test
pnpm build # Build all packagesЛицензия
MIT
Available Tools
5 toolsclose_surveyClose SurveyA
Permanently close a survey so it no longer accepts new responses. Use this when you have enough responses or the data collection window has passed. Returns the final response count. Closing is irreversible via MCP — use PATCH /api/surveys/{id} to re-open.
Inputs: survey_id (required).
create_keyCreate API KeyA
Create a new HumanSurvey API key. Call this before any other tool if HUMANSURVEY_API_KEY is not set. Returns a key — store it as HUMANSURVEY_API_KEY in your MCP config. The key cannot be retrieved again after creation.
Inputs: name, email, wallet_address.
create_surveyCreate SurveyA
Use this when an agent task involves collecting structured feedback or data from a group of people. Common cases: post-event attendee feedback, product satisfaction after a launch, team health checks, customer ratings after support resolution. The schema parameter is fully typed — follow the field types rather than guessing. Returns a survey_url to share with respondents and a survey_id to pass to get_results later. The survey accepts responses immediately and stays open until you close it or it expires. Embedding: append "?embed=1" to the returned survey_url to render inside an on any host site (onboarding/lead-capture flows). The embedded form posts events to window.parent with source: "humansurvey" — type "loaded", "resize" (with height), and "submitted" (with responseId and answers). See https://www.humansurvey.co/llms.txt for the full embed contract.
Inputs: schema (required), max_responses, expires_at, webhook_url.
get_resultsGet ResultsA
Retrieve aggregated results for a survey. Shows survey status (open/closed), total response count, and per-question results: choice tallies with percentages, scale mean/median/distribution, and recent text responses. If the survey is still open, call again later to check for new responses — the output will tell you. Use close_survey when you have enough responses.
Inputs: survey_id (required).
list_surveysList SurveysA
List all surveys created with the current API key, ordered newest first. Use this to find a survey_id you need for get_results or close_survey, or to check which surveys are still open.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a distinct, non-overlapping purpose: creating API keys, creating surveys, listing surveys, retrieving results, and closing surveys. No ambiguity.
All tool names follow a consistent verb_noun pattern in snake_case (create_key, create_survey, list_surveys, get_results, close_survey), making them predictable and easy to distinguish.
With 5 tools, the server is well-scoped for managing surveys. Each tool serves a necessary function without unnecessary bloat, fitting within the ideal range of 3-15 tools.
Covers core survey lifecycle (create, list, results, close) but lacks update and delete operations. While re-opening is possible via API, it's not exposed as a tool, creating a notable gap.
Maintenance
Related MCP Connectors
Create forms, share the link and read responses as JSON or CSV from your AI agent.
Create surveys, feedback and classification campaigns. Collect human answers and export results.
AI-native survey & form builder. Manage surveys, responses, analytics, and webhooks.
Ask people questions, get approvals and keep team decisions, from any AI agent.
Related MCP Servers
- AlicenseBqualityDmaintenanceCollects user feedback with text and image support through an Electron app, allowing AI tools to gather and process user input with customizable prompts and multiple response options.19 npm2Apache 2.0
- AlicenseAqualityCmaintenanceEnables AI agents to recruit real humans for evaluation tasks like surveys, A/B tests, and ratings on text, images, audio, and video, returning aggregated results directly into the conversation.137MIT
- AlicenseAqualityBmaintenanceFeedback ingestion for AI agents. Record your screen and talk; your agent does the rest — files the bugs, writes the spec, builds the backlog.997 PyPI35MIT
- AlicenseAqualityCmaintenanceReal human judgment as agent tools -- an AI agent can ask a question and get back a structured, schema-validated JSON answer from a real quality-scored human. 16 response types (yes/no, ratings, rankings, A/B tests, sentiment, image/video/audio review, voice/video/photo capture). Fully programmatic signup with a $5 free trial credit, no card required.747 npmMIT