Log inSubmit server
Human Survey logo

Human Survey

by sunsiyuan

Collects self-reported attribution through embedded forms, then lets agents configure forms and read response data.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Human Survey

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "sunsiyuan-human-survey": {
      "command": "npx",
      "args": [
        "-y",
        "humansurvey-mcp"
      ],
      "env": {
        "HUMANSURVEY_API_KEY": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Automated check passed— started and listed 10 tools correctly (27d ago).

Overview

The sunsiyuan/human-survey MCP server connects AI agents to HumanSurvey's attribution API for configuring embedded forms and collecting self-reported channel data. Agents can manage platform and creator candidates, read rollups or response streams, and resolve unmatched free-text answers. Use it when your product owns a signup or checkout flow and needs attribution data from people rather than referrers. It runs through the `humansurvey-mcp` npm package and authenticates with an API key.

Use cases

  • Collect attribution during signup
  • Measure channels among paying customers
  • Compare signup and payment-flow responses
  • Read response streams into an agent workflow
  • Resolve unmatched attribution text

Key features

  • Configure embedded attribution forms
  • Rotate candidate ordering per respondent
  • Read rollups and cursor-based responses
  • Filter responses by external ID
  • Remap unresolved free text
  • Preserve immutable form configuration snapshots

Tools10

What Human Survey lets your agent do. Expand a tool for its parameters.

Verified live~2.7k tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 1d ago

Recent health check succeeded.

19/20 checks healthy over the last 87d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 16d ago via OSV.dev · humansurvey-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars1Stargazers on the source repository.
npm downloads197Package downloads in the last 30 days.
Last commit3mo agoMost recent push to the default branch.
Availability100%Our rolling endpoint + install checks that succeeded.
Install checkPassedOur sandbox started it and listed its tools.
Tools exposed10Callable tools this server registers over MCP.
Directory activity2 viewsConfig copies, upvotes, and views on AllMCPs.

How Human Survey works

What sunsiyuan/human-survey MCP server does

The sunsiyuan/human-survey MCP server gives an agent access to HumanSurvey's self-reported attribution service. It is intended for products that embed a short “how did you hear about us?” form in signup, onboarding, or payment flows. Respondents choose a platform and, where configured, a related creator or other follow-up candidate.

The service separates form configuration from respondent collection. An agent can create a form, configure its candidate nodes, and then provide the resulting form URL to a host application. The host controls how people reach the form, including a direct /s/{id} URL or an iframe embed.

How it works

HumanSurvey stores each response against the configuration snapshot shown to the respondent. This means later configuration changes do not rewrite the historical choices. Candidate order can be rotated for each render using a client-generated render_id; callers can also request fixed ordering when that is appropriate.

The first answer is saved before a follow-up is presented. A person who leaves before completing the follow-up still contributes a recorded first response. Completed responses can be read as a cursor-based stream or looked up using an external identity supplied by the host. The service also exposes aggregated rollups for analyzing candidate counts over a date range.

Free-text answers remain available for review when they cannot yet be matched. A remap can associate that text with a candidate, and subsequent reads apply the mapping without requiring historical data to be rewritten. The external_id field provides the link between attribution records and the host's own user or conversion data.

Setup and configuration

The sunsiyuan/human-survey MCP server is launched with the published humansurvey-mcp npm package. A Claude Code configuration uses the npx -y humansurvey-mcp command and passes the HUMANSURVEY_API_KEY environment variable. The key is obtained from HumanSurvey's email-code authentication flow; anonymous key creation is not supported.

After authentication, create a form through the service and configure its nodes before embedding it. Platform labels, marks, and aliases can be taken from HumanSurvey's attribution catalog. Creator candidates are supplied by the caller, so identifying or matching creators against an external creator database is outside this server's stated role. The host should also configure allowed origins when creating a form.

Tools and capabilities

The MCP package is described in the repository as exposing ten tools for the attribution API.

  • Create and configure attribution forms.
  • Retrieve catalog data for platform candidates.
  • Read aggregate rollups by candidate and date range.
  • Stream responses with cursors or filter them by external_id.
  • Find unresolved free-text responses.
  • Add remaps that resolve previously unmatched text.
  • Support attribution data associated with a host's own conversion events and identifiers.

These operations suit long-running agent workflows where an agent keeps candidate lists current, prepares a form for an event or product flow, and periodically reads results for analysis.

Limitations and notes

The sunsiyuan/human-survey MCP server is focused on attribution rather than general survey authoring. The project says arbitrary question types, Markdown authoring, and conditional logic are outside its current scope. It does not provide a human-facing analytics dashboard; aggregate results are exposed as API resources for the agent or host to consume.

HumanSurvey does not contact respondents or recruit an audience. The embedding application owns distribution and placement. Creator candidate data must be supplied by the caller, and matching vague respondent descriptions to a creator database is upstream work.

The project is licensed under MIT. Its documented stack includes the MCP SDK, a Next.js application, and a serverless Postgres database, but running the hosted service through the package does not require operating those components locally.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Human Survey

sunsiyuan/human-survey is an MCP server that connects AI agents to HumanSurvey’s self-reported attribution API. Its main tools configure embedded forms, manage platform and creator candidates, read rollups or response streams, inspect unresolved free text, and apply remaps. It is designed for signup, onboarding, and payment flows.

Install it through `npx -y humansurvey-mcp` in an MCP client configuration. Set `HUMANSURVEY_API_KEY` to an API key from HumanSurvey’s email-code authentication flow.

Create the form, then configure its nodes before embedding it. Supply platform candidates from the attribution catalog and provide creator candidates yourself. The host can set allowed origins and then use the returned form URL or iframe embed in its signup or payment flow.

Yes, it can read unresolved free-text responses and add remaps for them. The original text is retained, while later reads resolve it through the remap table, allowing one mapping to apply to historical results without a separate backfill.

No, it does not provide a human-facing analytics dashboard. Rollups and response data are exposed as API resources for agents or host applications to consume. The project is focused on self-reported attribution rather than general-purpose surveys or operator-facing analytics.

Related MCP servers

All in Workplace & Productivity All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewHuman Survey AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/sunsiyuan-human-survey?style=directory)](https://allmcps.com/mcp/sunsiyuan-human-survey)
HTML Embed
<a href="https://allmcps.com/mcp/sunsiyuan-human-survey"><img src="https://allmcps.com/api/badge/sunsiyuan-human-survey?style=directory" alt="Human Survey on AllMCPs" /></a>