Formius docs

MCP server and agent API reference

Last updated: July 23, 2026

Formius exposes its form platform to AI agents through a Model Context Protocol server. An agent with a personal access token can create forms from natural language, manage their lifecycle, read email-verified responses, and export data. This page is the complete reference. A plain-text version of everything here is served at /llms-full.txt.

Endpoint

POST https://dev.formius.ai/api/mcp using streamable HTTP. Server: formius-mcp 0.2.0-phase2, MCP protocol 2025-11-25.

Authentication

Every request needs a personal access token in the Authorization: Bearer header. There is no OAuth flow today, which means claude.ai web connectors are not supported; Claude Code, Claude Desktop (through mcp-remote), Cursor, and raw HTTP clients all work.

Create a token

Log in to Formius and open Settings, then Integrations.
Create a new access token and select only the scopes your agent needs.
Pick an expiry in days, or no expiry, and create the token.
Copy the token right away. Formius shows it only once; store it in your secret manager.

Scopes

Scope	Grants
forms:read	List, search, and read forms
forms:write	Create, update, and clone forms
shares:write	Share forms with other admins
responses:read	Read responses without respondent email
responses:read:pii	Include respondent email in responses and exports
responses:export	Export responses to downloadable files
billing:read	Read subscription status and generation quota

Tools

Ten tools, each gated by a scope and annotated with read or write intent so MCP clients can decide what to auto-approve. Write tools that modify existing data are additionally marked destructive.

Tool	Scope	Mode	What it does
formius_create_form	forms:write	write	Generate a complete form from a natural-language prompt. Persists it as a draft by default and returns the form id, title, status, and URLs.
formius_quote_lesson_generation	billing:read	read	Preview the exact credit cost of an AI lesson for a prompt, language set, and zero to three illustrations without starting generation.
formius_create_lesson	forms:write	write	Create an illustrated AI lesson from an accepted quote, with optional password access, fixed or AI-reviewed tasks, and idempotent credit accounting.
formius_get_lesson_generation_status	billing:read	read	Read lesson generation progress, per-image state, and the exact reserved, charged, and refunded credit amounts for a quote.
formius_get_form	forms:read	read	Read a form: metadata, edit state (response count and lock), URLs, and optionally the full field structure.
formius_update_form	forms:write	write	Update a form with an AI edit prompt, a structure replacement, a status change (publish, pause, archive), or an access password. Breaking edits are blocked once responses exist.
formius_list_forms	forms:read	read	List forms the token owner can access, owned and shared, with optional title query, status filter, and limit.
formius_find_form_by_name	forms:read	read	Fuzzy-find accessible forms by title. Returns the top 5 matches with a match score from 0 to 1.
formius_clone_form	forms:write	write	Clone an accessible form into a new draft owned by the caller, with an optional new title.
formius_share_form	shares:write	write	Share a form with another Formius admin by email with view, edit, or admin permission.
formius_get_responses	responses:read	read	Read form responses with status and date filters. Respondent email is included only when the token holds the responses:read:pii scope.
formius_export_responses	responses:export	read	Export responses as CSV, CSV with file links, or ZIP to private storage and receive a 10 minute signed download URL. Up to 5000 rows per export.
formius_get_subscription_status	billing:read	read	Check subscription access mode and the AI generation quota: used, limit, remaining, and reset time.

There is also formius_ping, a scope-free utility: Liveness check. Returns ok status and the MCP protocol version. Use it to verify connectivity after setup.

Connect

Claude Code

claude mcp add --transport http formius https://dev.formius.ai/api/mcp --header "Authorization: Bearer YOUR_FORMIUS_PAT"

Claude Desktop

{
  "mcpServers": {
    "formius": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://dev.formius.ai/api/mcp",
        "--header",
        "Authorization: Bearer YOUR_FORMIUS_PAT"
      ]
    }
  }
}

Cursor

{
  "mcpServers": {
    "formius": {
      "url": "https://dev.formius.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_FORMIUS_PAT"
      }
    }
  }
}

Any MCP client (HTTP)

curl -X POST https://dev.formius.ai/api/mcp \
  -H "Authorization: Bearer YOUR_FORMIUS_PAT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The curl example above doubles as the API quickstart: it lists every available tool. Replace the method with tools/call to invoke one.

Rate limits

120 requests per minute per token. AI generation tools (create and AI-edit) additionally draw from your plan generation quota, which you can check with formius_get_subscription_status.