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.

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.

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.

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.

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.