# Formius agent documentation

> Formius is an AI form builder that humans and AI agents operate side by side. Describe a form in plain language and Formius builds it with validation and file uploads, translates it into 24 languages, publishes it, and collects email-verified responses. AI agents get first-class access through an MCP server with 10 scoped tools authenticated by personal access tokens.

## What Formius is

Formius (formius.ai) is a form platform with two front doors. Humans describe a
form in plain language and the built-in AI generates it in seconds, with
validation, file uploads, and automatic translation into 24 languages.
AI agents use the same platform programmatically through an MCP server.
Responses are email-verified, exportable, and shareable across a team.
Plans include a 7 day free trial.

## MCP server

- Endpoint: POST https://dev.formius.ai/api/mcp (streamable HTTP)
- Server: formius-mcp 0.2.0-phase2, MCP protocol 2025-11-25
- Auth: Authorization: Bearer <personal access token>. No OAuth today, so
  claude.ai web connectors are not supported; use Claude Code, Claude Desktop
  (via mcp-remote), Cursor, or any MCP client that can send a Bearer header.
- Rate limit: 120 requests per minute per token. AI
  generation tools additionally draw from the plan generation quota.

## Personal access tokens

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

Available scopes:

- 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

### formius_create_form

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.
Scope: forms:write. Mode: write.

### formius_quote_lesson_generation

Preview the exact credit cost of an AI lesson for a prompt, language set, and zero to three illustrations without starting generation.
Scope: billing:read. Mode: read.

### formius_create_lesson

Create an illustrated AI lesson from an accepted quote, with optional password access, fixed or AI-reviewed tasks, and idempotent credit accounting.
Scope: forms:write. Mode: write.

### formius_get_lesson_generation_status

Read lesson generation progress, per-image state, and the exact reserved, charged, and refunded credit amounts for a quote.
Scope: billing:read. Mode: read.

### formius_get_form

Read a form: metadata, edit state (response count and lock), URLs, and optionally the full field structure.
Scope: forms:read. Mode: read.

### formius_update_form

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.
Scope: forms:write. Mode: write.

### formius_list_forms

List forms the token owner can access, owned and shared, with optional title query, status filter, and limit.
Scope: forms:read. Mode: read.

### formius_find_form_by_name

Fuzzy-find accessible forms by title. Returns the top 5 matches with a match score from 0 to 1.
Scope: forms:read. Mode: read.

### formius_clone_form

Clone an accessible form into a new draft owned by the caller, with an optional new title.
Scope: forms:write. Mode: write.

### formius_share_form

Share a form with another Formius admin by email with view, edit, or admin permission.
Scope: shares:write. Mode: write.

### formius_get_responses

Read form responses with status and date filters. Respondent email is included only when the token holds the responses:read:pii scope.
Scope: responses:read. Mode: read.

### formius_export_responses

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.
Scope: responses:export. Mode: read.

### formius_get_subscription_status

Check subscription access mode and the AI generation quota: used, limit, remaining, and reset time.
Scope: billing:read. Mode: read.

### formius_ping

Liveness check. Returns ok status and the MCP protocol version. Utility tool, no scope required.

## Connect

### Claude Code

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

### Claude Desktop

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

### Cursor

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

### Any MCP client (HTTP)

```bash
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"}'
```

## More

- Agent landing page: https://dev.formius.ai/agents
- Human-facing product tour: https://dev.formius.ai/creators
- Full reference page: https://dev.formius.ai/docs/agents