Connect an AI agent
Atom Form exposes a Model Context Protocol (MCP) server so an agent can build, publish, and analyze forms end to end — the same operations you'd perform in the builder UI.
- Endpoint
- POST https://useatomform.com/api/mcp
- Transport
- Streamable HTTP, stateless (MCP spec 2026-07-28, with fallback for older clients)
1. Get a token
Sign in, open the avatar menu → API & MCP, and create a token. Pick only the scopes an agent needs — the plaintext token is shown exactly once.
| Scope | Grants |
|---|---|
| forms:read | list_forms, get_form, validate_form |
| forms:write | create_form, update_form, duplicate_form, delete_form |
| forms:publish | publish_form, set_form_status |
| responses:read | list_responses, get_response, get_form_analytics |
get_form_schema_guide only requires a valid token. Give an analytics-only agent forms:read + responses:read — it won't be able to touch live forms.
2. Connect your client
Pick your client below and swap YOUR_TOKEN for the token you just created.
claude mcp add --transport http atom-form https://useatomform.com/api/mcp \ --header "Authorization: Bearer YOUR_TOKEN"
Run in a terminal, then use the atom-form tools in any Claude Code session. Paste the same block into a project's .mcp.json to share it with a team.
3. What an agent can do
13 tools, all workspace-isolated. Recommended flow: call get_form_schema_guide once per session, then create_form → validate_form → publish_form.
| Tool | Purpose |
|---|---|
| get_form_schema_guide | Complete schema reference — 18 field types, logic, recall, scoring, themes, plus a full valid example. Call this first. |
| list_forms | List workspace forms (search / status filter) with URLs. |
| get_form | One form including full draft schema, optionally the published snapshot, and has_unpublished_changes. |
| create_form | Create a draft from a complete schema. Returns publish blockers immediately. |
| update_form | Full-replacement draft update and/or rename. Live form untouched until republish. |
| validate_form | Dry run: structural errors, duplicate-id checks, publish blockers, recall-token warnings. Saves nothing. |
| publish_form | Validate + snapshot the draft live; returns the public URL. |
| set_form_status | Toggle a live form published ↔ closed. |
| duplicate_form | Copy a form's draft into a new draft. |
| delete_form | Permanent delete (requires confirm: true). |
| list_responses | Paginated responses with answers decoded to question text. |
| get_response | One response, decoded and raw. |
| get_form_analytics | Views, starts, submissions, partials, completion rate, average duration. |
Design & security
- Every query is filtered by the token owner's workspace, resolved server-side — an agent can never cross into another workspace.
- Tokens are SHA-256 hashed at rest; only the prefix is shown after creation. Revocation takes effect within a minute.
- Rate limit: 120 requests/min per token.
- Writes touch the draft only —
publish_formis the one call that goes live. - Errors are structured (code, message, details) so an agent can self-correct without a human.