Formius docs

MCP server and agent API reference

Last updated: July 27, 2026

Formius exposes its form platform to AI agents through a Model Context Protocol server. An OAuth-connected agent or a client 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://www.formius.ai/api/mcp using streamable HTTP. Server: formius-mcp 0.2.0-phase2, MCP protocol 2025-11-25.

Authentication

Claude, Claude Desktop, and Claude Code connect through OAuth 2.1 with dynamic client registration and PKCE. Add the endpoint, sign in to Formius, and approve the requested access. Personal access tokens in the Authorization: Bearer header remain available for clients that use static credentials.

Create a personal access 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

13 product tools, each gated by a scope and annotated with a title plus 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

In Claude, open Customize, then Connectors, add a custom connector, and paste the endpoint shown below. In Claude Code, run the two commands and complete the browser sign-in.

Claude.ai and Claude Desktop custom connector

https://www.formius.ai/api/mcp

Claude Code

claude mcp add --transport http --scope user formius https://www.formius.ai/api/mcp
claude mcp login formius

Cursor with a personal access token

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

Any MCP client with a personal access token

curl -X POST https://www.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.