# Markdown to Survey (MTS)

> The survey layer for AI agents. Create interactive surveys from JSON schema, collect responses from humans, and retrieve structured results via API or MCP.

## What is MTS?

MTS lets AI agents gather structured information from humans. An agent sends a survey schema to the MTS API, gets a shareable respondent URL, and later retrieves structured results. The web demo accepts plain text or Markdown and uses an LLM to translate it into schema — this mirrors what an agent would do.

## MCP Integration

Add to `~/.claude.json`:

```json
{
  "mcpServers": {
    "survey": {
      "command": "npx",
      "args": ["-y", "@mts/mcp-server"],
      "env": { "MTS_API_KEY": "mts_sk_your_key_here" }
    }
  }
}
```

Tools: `create_survey`, `get_results`, `list_surveys`, `close_survey`

## API Quick Start

Get an API key:

```bash
curl -X POST https://www.humansurvey.co/api/keys \
  -H "Content-Type: application/json" \
  -d '{"name":"my agent"}'
```

Create a survey from JSON schema:

```bash
curl -X POST https://www.humansurvey.co/api/surveys \
  -H "Authorization: Bearer mts_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "schema": {
      "title": "Incident Intake",
      "sections": [{
        "questions": [
          { "type": "single_choice", "label": "Which environment?", "required": true,
            "options": [{ "label": "Local" }, { "label": "Staging" }, { "label": "Production" }] },
          { "type": "scale", "label": "How urgent?", "required": true,
            "min": 1, "max": 5, "minLabel": "Low", "maxLabel": "Critical" }
        ]
      }]
    }
  }'
```

## Question Types

- `single_choice` — one selection from a list of options
- `multi_choice` — one or more selections from a list of options
- `text` — free-form text response
- `scale` — numeric position on a bounded range (max 11 points)
- `matrix` — apply shared options across multiple rows

## Docs

- Full docs: https://www.humansurvey.co/docs
- OpenAPI: https://www.humansurvey.co/api/openapi.json
- Full AI index: https://www.humansurvey.co/llms-full.txt