Developers

Formaly MCP Server

Formaly ships a Model Context Protocol server so an AI agent can work with forms directly - no browser, no scraping. The endpoint is `https://www.formaly.io/api/mcp` over Streamable HTTP, authenticated with the same Formaly API key as the REST API.

› Developers

Connecting an agent to Formaly

Point any MCP client at the Streamable HTTP endpoint and pass your Formaly API key as a bearer token. The tools the agent sees are determined by the key's scopes: a read-only key exposes only the read tools.

{
  "mcpServers": {
    "formaly": {
      "type": "http",
      "url": "https://www.formaly.io/api/mcp",
      "headers": { "Authorization": "Bearer fml_abc123_your_secret_here" }
    }
  }
}

Read tools

Reads never consume credits and never change state. Call them freely.

Tool	Use it when	Scope
`list_forms`	The user wants to see their forms or surveys	`forms:read`
`get_form`	You need one form's full details and question schema	`forms:read`
`get_form_schema`	You only need the structure, to render or fill the form	`forms:read`
`get_form_responses`	The user wants the answers people actually submitted	`analytics:read`
`get_form_analytics`	The user asks how a form is performing	`analytics:read`
`get_credits`	The user asks about credits, or before a paid action	`forms:read`

Write tools

Write tools require the forms:write scope. create_form generates with AI and consumes credits.

Tool	Use it when	Notes
`create_form`	The user wants a new form from a description	Costs credits. Pass `request_id` for safe retries.
`update_form`	Rename, re-describe, or reconfigure a form	Pass `expected_version` from `get_form`.
`set_form_status`	Publish, close, or unpublish a form	Pass `expected_version` to avoid clobbering edits.
`delete_form`	The user explicitly asks to delete a form	Irreversible - confirm first. Pass `request_id`.

Rules for agents

Read before you write. get_form returns a version; pass it as expected_version so a concurrent edit surfaces as a CONFLICT instead of silent data loss.
Send a `request_id` on every create and delete. Retries then become safe rather than duplicating or destroying work.
Check credits before a batch. get_credits is free; discovering INSUFFICIENT_CREDITS halfway through a batch is not.
Confirm deletions with a human. delete_form removes the form and its responses permanently.
Do not retry a `FORBIDDEN`. It means the key lacks the scope; ask the user for a key that has it.

Related Formaly resources

Formaly agent guide (/AGENTS.md) - the same rules in a file agents can fetch directly.
Formaly REST API reference - everything the MCP tools do, over plain HTTP.
Formaly OpenAPI spec - machine-readable API description.
Formaly llms.txt - site and endpoint index for language models.