Building with AI
The MCP authoring loop: create the form record, get the binding contract, validate the HTML, publish, and verify
The Forms SDK was designed to be authored by coding agents. The Surface MCP server creates the record, hands the agent the binding contract, and statically validates the HTML. Run the loop yourself, or hand it to an agent with a prompt like "build our demo booking form as an SDK form on our landing page".
The authoring loop
plan_form with sdk: true critiques a blueprint before anything is created.
create_form with sdk: true: steps, questions, endings; no styling or routing parameters. Give every question real question text (the responses table reads those labels). Save the formId and previewToken.
get_sdk_binding_map returns, per question: questionId, componentType, fieldNames, option keys, answerShape, plus environmentId, apiBaseUrl, and a ready-to-paste init snippet. Use the snippet; a wrong apiBaseUrl is the most common failure.
Write HTML or React against the binding contract, copying IDs and option keys from the binding map.
validate_form_html checks the markup against the record. Fix every blocker; warnings are silent data loss at runtime.
Boot with preview: true and the previewToken to walk the draft with zero writes, then publish_form and deploy.
Submit one real test response, await form.flush(), read it back with get_response, confirm every answer and meta.surfaceTagStatus: "sdk". Without a browser, run headless in Node.
Validating framework pages
validate_form_html must see the markup the visitor actually receives. Plain HTML: pass the file. Framework page: fetch the rendered HTML (curl http://localhost:3000/your-page) and pass it with containerSelector set to your boot container. Never validate a hand transcription of the source. If navigation or submit is code-driven, declare data-surface-nav="js".
Editing an existing SDK form
Every record edit must be followed through to the HTML:
get_form_structure(withinclude: ["params"]) for the structure and itsrevision.- Edit with
add_step,update_step,add_component,update_component,remove_component, orbatch_edit, passing the revision asifRevisionso concurrent edits fail loudly. - Re-fetch
get_sdk_binding_mapand update the HTML for every difference. validate_form_htmluntil clean, thenpublish_formand deploy together.
If publish and deploy cannot land simultaneously: publish first for additions, deploy first for removals and option-key changes. The dashboard's SDK form builder edits the same draft by hand.
Tools that refuse on SDK forms
Styling, marketing, layout, and routing tools reject SDK forms: presentation lives in your HTML, navigation in your code. simulate_response does not apply either. validate_form checks configuration integrity only; a pass says nothing about your page.
Installing the skill
If your agent runner supports skills (Claude Code does):
cp -r node_modules/@surface-labs/forms-sdk/skills/surface-forms-sdk .claude/skills/The skill includes the workflow, HTML patterns, an editing sync loop, and a debugging runbook.