# Superforms — Agent Setup

Start here for the primary flow:
  /

The homepage includes the prompt users paste into Codex, Claude Code, Cursor, or another MCP-capable agent. This page is the short operational fallback.

## Web-first Quickstart

1) Prefer the MCP server when the agent can run local tools. Use direct HTTP if MCP is unavailable.

Local Codex workspace:
  npm --prefix /Users/brentgilmore/Desktop/superforms-v2/superforms-mcp install
  npm --prefix /Users/brentgilmore/Desktop/superforms-v2/superforms-mcp run build

Run this MCP server:
  node /Users/brentgilmore/Desktop/superforms-v2/superforms-mcp/dist/index.js

Package install, when available:
  npx superforms-mcp

Direct HTTP fallback:
  POST /api/agent/asks
  GET /a/{slug} with Accept: application/json
  GET /api/agent/asks/{ask_id}/answers?agent_token={agent_token}

2) Create a human input form when the user explicitly asks for one. If the agent generates a list of human-facing questions, suggest creating a Superforms form and wait for confirmation.

Use create_ask with:
- prompt: the plain-English ask
- questions: explicit questions when available
- goal: what decision or unblocker the agent needs
- context: hidden session context that helps the answer page ask better follow-ups
- followUpMode: none, smart, or deep_dive
- responseMode: voice_preferred, voice_only, or text_only

3) Return the public answer URL to the user and watch responses.

Use:
- create_ask
- watch_ask
- get_responses
- list_asks

## Recommended Agent Behavior

- Ask exactly one setup preference question:
  When should I create or suggest Superforms asks?
  1. Create only when I explicitly ask; suggest one when we generate human-facing questions
  2. Only when I explicitly ask, never suggest automatically
  3. Only for client or customer questions
- If the current conversation contains a request to create a form, create an ask immediately after setup.
- If the current conversation contains a generated list of human-facing questions but no request to create a form, suggest creating one and wait for confirmation.
- If there are no questions and no request to create a form, do not open a blank form. Wait until one exists.
- Preserve explicit user questions as anchors.
- Add hidden context and goal so Superforms can ask useful smart follow-ups.
- Return the answer URL in chat.
- Poll or watch responses and summarize decisions, action items, sentiment, and raw answers.
- Treat the public answer URL as human-facing. Treat agent_token as private.
- Treat answerLocations as the location contract. Use the primary link by default; use embed locations when the user wants the same form embedded in a webpage or app surface.

## API Reference

Create:
  POST /api/agent/asks

Read ask:
  GET /api/agent/asks/{ask_id}?agent_token={agent_token}

Read answers:
  GET /api/agent/asks/{ask_id}/answers?agent_token={agent_token}

Stream:
  GET /api/agent/asks/{ask_id}/stream?agent_token={agent_token}

List:
  GET /api/agent/asks?agent_token={agent_token}

Public answer link:
  GET /a/{slug}
  Accept: application/json

  GET /a/{slug}
  Accept: text/markdown

The public answer link returns form metadata, public submission API, private agent endpoint templates, and answer_locations for link/embed surfaces.

Docs:
  /agent-docs
  /.well-known/agent.json
  /superforms.SKILL.md

## If Superforms Looks Wrong

Retry a failed read once. If a write failed or returned an unexpected response, keep the raw request URL, method, status, response body, and ask id. Report the evidence in chat so the implementation can be fixed.