Skip to main content
Glama
humansurvey-mcp

humansurvey-mcp

by sunsiyuan

HumanSurvey

Sitio web: humansurvey.co · Documentación: humansurvey.co/docs · Preguntas frecuentes: humansurvey.co/faq

human-survey MCP server

Infraestructura de recopilación de comentarios para agentes de IA.

HumanSurvey permite a un agente que realiza trabajos a largo plazo recopilar comentarios estructurados de un grupo de personas:

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

¿Qué es esto?

HumanSurvey es una API mínima y un servidor MCP para una tarea específica: permitir que los agentes recopilen comentarios estructurados de grupos de humanos y obtengan resultados utilizables por máquinas.

Está diseñado para:

  • Agentes de IA que gestionan eventos, lanzamientos de productos o flujos de trabajo comunitarios que necesitan encuestar a un grupo

  • Desarrolladores que crean productos de agentes que necesitan una primitiva ligera de recopilación de comentarios

No está diseñado para:

  • Paneles de control de encuestas

  • Creadores de formularios visuales

  • Bibliotecas de plantillas

  • Campañas de correo electrónico

  • Interfaz de usuario de análisis/informes

Related MCP server: Datapoint MCP

Características

  • Entrada de esquema JSON — estructurada, precisa y generada directamente por la máquina

  • Servidor MCP — cree encuestas y lea resultados directamente desde Claude Code

  • Superficie de API mínima — rutas de creador autenticadas, envío público de encuestados

  • Cuatro tipos de preguntas semánticas — choice, text, scale, matrix

  • Lógica condicional — showIf en Markdown y esquema JSON

  • Ciclo de vida explícito — cierre de encuestas, caducidad y límites máximos de respuesta

Principios del producto

  • Semántico sobre visual: HumanSurvey tiene un protocolo pequeño, no un zoológico de tipos de campo específicos de la interfaz de usuario.

  • E/S centrada en la IA: los agentes escriben la encuesta y los agentes consumen los resultados; los humanos están en el medio.

  • Todo es una API: la funcionalidad del creador debe estar disponible a través de HTTP autenticado y MCP.

  • El alcance estrecho gana: si una característica sirve principalmente a los operadores de encuestas humanos, probablemente no pertenezca aquí.

Tipos de preguntas admitidos

  • single_choice

  • multi_choice

  • text

  • scale

  • matrix

Sintaxis de 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 |

Preguntas de escala:

**Q4. How severe is this issue?**

[scale 1-5 min-label="Low" max-label="Critical"]

Lógica condicional:

**Q1. Did the deploy fail?**

- ☐ Yes
- ☐ No

**Q2. Which step failed?**

> show if: Q1 = "Yes"

> _______________________________________________

Inicio rápido

Uso con Claude Code

Añadir a su configuración de Claude Code (~/.claude.json):

{
  "mcpServers": {
    "survey": {
      "command": "npx",
      "args": ["-y", "humansurvey-mcp"],
      "env": {
        "HUMANSURVEY_API_KEY": "hs_sk_your_key_here"
      }
    }
  }
}

Luego en Claude Code:

> Create a post-event feedback survey with a 1-5 rating, open text, and a yes/no question

Herramientas disponibles:

  • create_key — aprovisionamiento automático de una clave API; no se requiere configuración humana

  • create_survey — crear a partir de un esquema JSON; max_responses, expires_at, webhook_url opcionales

  • get_results — resultados agregados + respuestas sin procesar

  • list_surveys — listar encuestas propiedad de su clave

  • close_survey — cerrar una encuesta inmediatamente

Usar la API HTTP

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

Todos los campos son opcionales. wallet_address utiliza el formato CAIP-10 — se utilizará para pagos nativos de agentes en el futuro.

Luego cree una encuesta:

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

Respuesta:

{
  "survey_url": "/s/abc123",
  "question_count": 1
}

Leer resultados:

curl https://www.humansurvey.co/api/surveys/abc123/responses \
  -H "Authorization: Bearer hs_sk_..."

Superficie pública

  • Página de documentación: https://www.humansurvey.co/docs

  • OpenAPI: https://www.humansurvey.co/api/openapi.json

  • Índice de IA: https://www.humansurvey.co/llms.txt

Pila tecnológica

Componente

Tecnología

Framework

Next.js (App Router)

Base de datos

Neon (Postgres sin servidor)

Analizador

remark (ecosistema unificado)

Frontend

React + Tailwind CSS

Servidor MCP

@modelcontextprotocol/sdk

Despliegue

Vercel

Estructura del proyecto

├── apps/web/          # Next.js app (API + frontend)
├── packages/parser/   # Markdown → Survey JSON parser
├── packages/mcp-server/ # MCP server for Claude Code
└── docs/              # Architecture docs

Contribución

Lea CONTRIBUTING.md antes de abrir una solicitud de extracción (PR). La regla más importante es la disciplina de alcance: las nuevas variantes de interfaz de usuario, los paneles de análisis y las funciones de operador humano suelen estar fuera del alcance.

Desarrollo

pnpm install
pnpm dev              # Start Next.js dev server
pnpm --filter @mts/parser test
pnpm build            # Build all packages

Licencia

MIT

Available Tools

5 tools
close_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

    A4.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a distinct, non-overlapping purpose: creating API keys, creating surveys, listing surveys, retrieving results, and closing surveys. No ambiguity.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Collects 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.
      1
      9 npm
      2
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      13
      7
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Real 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.
      7
      47 npm
      MIT