@formio/ai is what brings Form.io into your agentic coding environment. It provides a series of tools that enable any developer to perform a number of complex actions against the Form.io Enterprise Server using their favorite Agentic Coding toolsets. This turns the Form.io Enterprise Server into a Composable Backend for Agentically Coded Applications.
- Getting Started
- What you get
- Why this exists
- Agentic Skill Library
- Examples and Use Cases
- Using the MCP server without the skills
- MCP server tools
- Authentication
- Environment variables
- Contributing
- License
Works in any agent that supports Agent Skills:
npx skills add formio/aiThen open the folder in your agent and describe what you want:
Build me an app for tracking client engagements — clients, engagements, and time
entries. Consultants should only see engagements they're assigned to.
That is the whole setup. The command installs the skill library into .agents/skills/, which every skills-capable agent reads. It installs skills only — the Form.io MCP server, which is what gives the agent tools like form_create, form_list, and project_import, is connected on first use by the bundled formio-mcp-setup skill: it writes the MCP configuration for your client, asks you to approve it, and tells you to reload. You never hand-write a config file.
If your agent has a plugin marketplace, installing the plugin is an alternative to the command above — not a second step. A plugin install already includes the skills and the MCP server, and it prompts for your Base URL — the deployment, not a project — up front:
| Agent | Install | Includes |
|---|---|---|
| Claude Code | /plugin marketplace add https://github.com/formio/ai.git then /plugin install formio-ai@formio |
skills + MCP + Base URL prompt |
| Cursor | Coming Soon | skills + MCP + Base URL prompt |
| GitHub Copilot CLI | Coming Soon | skills + MCP |
| VS Code | Coming Soon | skills + MCP |
| Codex / ChatGPT | Coming Soon | skills + MCP |
| Anything else | npx skills add formio/ai |
skills; MCP installed on first use. |
Either way you end up in the same place: the skills loaded, and 20 Form.io tools available.
Nothing above asks for a URL, because the server starts with no configuration and asks when it first needs one. Two values exist when you want to set them explicitly:
- Project URL — the endpoint for your project. On our SaaS environment (https://portal.form.io) that is a sub-domain such as
https://myproject.form.io. Self-hosted, it depends on how your deployment routes projects: a sub-directory (https://forms.mysite.com/myproject) or a sub-domain of your own domain (https://myproject.mysite.com). - Base URL — the endpoint for the deployment. On our SaaS environment it is always
https://api.form.io— never your project's*.form.iosub-domain. Self-hosted, it is the deployment host, often a sub-domain of your own domain, e.g.https://forms.mysite.com. In the sub-domain routing case the project host and the base host differ by design, so neither can be worked out from the other.
A plugin install prompts for the Base URL only. The Project URL is never an install-time question: a deployment is shared across your projects, but a Form.io project is one-to-one with the application built against it, so the agent asks for it in the directory it belongs to and records both values there with the project_set tool. One server, one mapping per workspace.
- Agent plugin:
@formio/ai. One-command install wherever the agent has a marketplace — Claude Code, Cursor, GitHub Copilot CLI, VS Code, Codex. Bundles the MCP server and the skill library, and each client reads the manifest it understands. - MCP server:
@formio/mcp. Form.io operations (form_*,role_*,action_*,project_*) as MCP tools. Works with any MCP-aware client: Claude Code, Claude Desktop, VS Copilot, and whatever comes next. - Skills library: Eleven activatable skills covering app orchestration, form building (webforms and wizards), form embedding, resource planning, JSON-schema authoring, action configuration, authentication & authorization, the
@formio/jsSDK surface, and the full Form.io REST surface.
Form.io has been the data standardization layer for enterprise data for a decade. With the proliferation of AI coding agents, that standardization matters more, not less.
Build on the Form.io platform, not from scratch. The agent builds complete applications including the data models, forms, workflows, and business logic. Form.io is the platform it builds on. The APIs, data patterns, RBAC, audit infrastructure, and form management capabilities are production-grade and already there. The agent uses them as tools to build applications better.
Standardization across every AI-built app. One model, one set of rules, one audit trail, regardless of which team or which agent built it. With a standardization layer, multiple teams ship multiple applications, all with defensible, reconcilable data layers across the enterprise.
Governance built in. RBAC, group permissions, change history, audit trails — all emitted on the first pass. Every app lands inside the same compliance envelope the enterprise already runs on.
The plugin ships an activatable skill library. Claude loads the relevant skill on demand based on what you ask — you rarely need to name one explicitly.
Orchestration skills are special skills that serve as the entry point for most prompts. Rather than covering a single capability, they coordinate the other skills (planning, schema authoring, actions, deployment, framework scaffolding) to fulfill a broad, plain-language request end to end. When you describe what you want instead of which tool to use, an orchestration skill picks it up and drives the whole pipeline.
| Skill | What it does |
|---|---|
formio-application |
Framework-agnostic "build me an app" orchestrator. Turns plain-language intent into a running application backed by a Form.io project — planning resources, importing the template, and handing off to a framework implementor. Also handles adding new features to an existing app. |
formio-form-builder |
"Build me a form" orchestrator. Builds a single form end to end — webform or multi-page wizard — from intent through schema authoring to a saved form in your deployment, with an optional embed handoff. Also handles field edits to an existing form. |
| Skill | What it does |
|---|---|
formio-application |
Orchestration entry point for building or extending an application on the Form.io platform (see above). |
formio-form-builder |
Orchestration entry point for building a single form — webform or wizard — end to end (see above). |
formio-form |
Embeds and renders Form.io forms in any web application with the @formio/js renderer — pre-fill, conditional fields, calculated values, custom validation, and conditional wizard pages. |
formio-resource-planner |
Plans the resource structure, field configuration, and access/permission model from high-level requirements, then emits a ready-to-import template.json. |
formio-schema |
Reference for Form.io JSON schema — the document shapes for projects, forms/resources, and submissions. Used when constructing, editing, or interpreting any Form.io JSON. |
formio-actions |
Reference for configuring Form.io actions — the server-side behavior layer for email notifications, authentication, webhooks, role assignment, and form-to-form saves. |
formio-auth |
Authentication and authorization specialist — login/registration, RBAC, SSO (OIDC/SAML/LDAP), Token Swap, Custom JWT, passwordless email tokens, and JWT/session mechanics. |
formio-api |
Comprehensive Form.io REST API reference — every endpoint across platform admin, project admin, runtime, and PDF scopes. |
formio-sdk |
Reference for the @formio/js JavaScript SDK and @formio/js/utils Utilities — static and instance methods, VanillaJS rendering, plugins, and helpers. |
formio-mcp-setup |
Connects the Form.io MCP server to whichever coding agent is running, and captures the project URL, when the skills were installed without it. |
formio-angular |
Angular framework implementor. Turns an approved template.json plus a target project into a working Angular app using @formio/angular. Delegated to by formio-application. |
Ready-to-paste example prompts live in examples/ — each file is one self-contained prompt plus notes on what it should exercise. To try one, create a new folder, start Claude Code inside it, and paste the prompt:
mkdir form-app
cd form-app
npx skills add formio/ai
claudeCreate a brand-new 'greenfield' form-based application — or introduce a new form-based feature within an existing one — using the formio-application orchestration skill. The agent plans the data model, imports it into your Form.io project, and scaffolds the front end, using the Form.io platform as the composable backend for the full application logic.
- CRM Application — clients, deals, and activity logs with owner-scoped access.
- Help Desk — customer tickets, agent workflows, internal notes, and email notifications.
- Storyboard — Trello-style board → swimlane → story kanban with drag-and-drop ordering and team-based access.
This library currently only supports the Angular application framework for new 'greenfield' applications. It generally supports other frameworks using the Vanilla JS @formio/js javascript renderer. Full support for other frameworks are coming soon.
Create complex forms and multi-page conditional wizards with the formio-form-builder skill. The agent authors the form JSON and automatically creates the form within any stage of your deployment — including forms whose submission data must adhere to well-defined external schemas such as FHIR.
- College Application Wizard — multi-page wizard with program-driven conditional pages.
- FHIR-Compliant Patient Form — submission data that conforms to the FHIR Patient resource.
- Customer Feedback Form — conditional follow-up fields and a conditional email notification.
- Student Onboarding Wizard — create a wizard and embed it within your application in one pass.
Embed an existing form or wizard within any HTML-based application using the formio-form skill.
- Embed an Existing Form — render a saved form with
@formio/js, pre-fill it, and handle submit events.
The formio-api skill knows the full REST surface of your Form.io deployment — create any Resource, Form, Submission, or other entity via prompt.
- Create a Patient Resource — create a new resource through the MCP server's first-party tools.
The bundled MCP server is also published standalone as @formio/mcp — you do not need the agent plugin or the skill library to use it. Any MCP-aware client (Claude Code, Claude Desktop, Cursor, VS Code Copilot) can spawn the server directly and call the tools below.
It is also listed in the official MCP Registry as io.form/formio-mcp, so clients that browse the registry can discover and install it without any manual configuration.
{
"mcpServers": {
"formio-mcp": {
"command": "npx",
"args": ["-y", "@formio/mcp@0.10.0"]
}
}
}That is the JSON mcpServers shape — what Claude Code (.mcp.json), Cursor (.cursor/mcp.json), Claude Desktop, Windsurf, and Cline expect. Both the filename and the top-level key vary by client, so there is no universal .mcp.json.
Copilot uses servers, not mcpServers. In .vscode/mcp.json the top-level key is servers — everything inside the entry is identical.
{
"servers": {
"formio-mcp": {
"command": "npx",
"args": ["-y", "@formio/mcp@0.10.0"]
}
}
}Codex takes TOML, and has no JSON equivalent:
[mcp_servers.formio-mcp]
command = "npx"
args = ["-y", "@formio/mcp@0.10.0"]Authentication is the same everywhere: the first authenticated tool call opens the browser portal-login flow, or set FORMIO_API_KEY to skip the browser entirely — required on any host with no browser, such as a cloud agent, a container, or CI.
Once connected, prompt the tools directly — no skill activation involved:
Using the formio-mcp tools, show me every form and role in my Form.io project, then export the full project template and save it to ./backup/template.json.
Using the formio-mcp form_create tool, create a new form called "Contact Us" with fields for full name (required), email (required), subject, and message, plus a submit button.
Ready-to-paste versions of these live in examples/mcp/: Inspect and Export a Project and Create a Form Directly.
One caveat: without the skills, the agent authors Form.io JSON (form schemas, action settings, access arrays) from its own general knowledge instead of the conventions the skill library encodes — every operation the tools cover still works, but you give up the guardrails. For other transports (Streamable HTTP for remote clients, SSE for Claude Desktop) and running the server from a clone of this repo, see the MCP server README.
The bundled @formio/mcp server exposes these tools. Skills prefer these over raw HTTP whenever an operation is covered.
| Tool | Purpose |
|---|---|
form_create |
Create a new form. Use the formio-schema skill first to build the JSON definition. |
form_get |
Fetch a single form definition by ID or path. |
form_list |
List forms with optional filtering and pagination. |
form_update |
Update an existing form. Call form_get first, edit with formio-schema, then update. |
form_revisions_list |
List the immutable published revision summaries for a form (_vid, _id, modified, user, _vnote). Requires form revisions to be enabled. |
form_revision_get |
Fetch a single immutable form revision by _vid or revision document _id. |
| Tool | Purpose |
|---|---|
role_create |
Create a new project role. |
role_list |
List all project roles. |
role_update |
Full-replacement update of a role. Include all fields you want preserved. |
| Tool | Purpose |
|---|---|
action_types_list |
List all action types available on the server. |
action_type_get |
Get an action type's settings schema. |
action_create |
Attach a new action to a form. |
action_list |
List actions on a form. |
action_get |
Get a single action by ID. |
action_update |
Update an action. |
action_delete |
Detach an action from a form. |
| Tool | Purpose |
|---|---|
project_export |
Export the project's complete template (roles, resources, forms, actions) as a portable JSON document. Use before project_import to snapshot. |
project_import |
Import a template JSON — additively merges roles, resources, forms, and actions in one call. Same-machine-name items are overwritten in place; everything else is preserved. |
project_set |
Persist a per-cwd Project URL mapping in ~/.formio/projects.json, so one server can serve several workspaces. Registered in every client. An explicit FORMIO_PROJECT_URL in the server environment takes precedence over the mapping. |
| Tool | Purpose |
|---|---|
hello |
Smoke-test tool. Returns a static greeting; useful for verifying MCP wiring before any authenticated call. |
The MCP server supports two authentication modes:
- JWT mode (default). A short-lived local Express server renders the Form.io portal login form; the user signs in once, the JWT comes back via a
/callbackendpoint, andformioFetchattachesx-jwt-tokenon every subsequent request. The flow is implicit — the first authenticated tool call triggers it on a cache miss. No explicitauthenticatetool exists. - API-key mode. Set
FORMIO_API_KEY. All requests attachx-token; the browser flow is skipped entirely.
When FORMIO_LOGIN_FORM is unset, the server probes these candidates on the first login attempt and caches the first one that responds (1.5-second timeout per candidate):
${FORMIO_BASE_URL}/formio/user/login(portal-base)${FORMIO_PROJECT_URL}/admin/login(project admin)${FORMIO_PROJECT_URL}/user/login(project user)
The probe runs lazily — only when the local auth page is actually served.
| Name | Required | Default | Purpose | Hosted SaaS example | Self-hosted example |
|---|---|---|---|---|---|
FORMIO_BASE_URL |
no | https://api.form.io |
Full base URL of your Form.io deployment — always https://api.form.io on the hosted cloud, never a project's *.form.io sub-domain. |
https://api.form.io |
https://forms.example.com |
FORMIO_PROJECT_URL |
yes* | — | Full URL of your Form.io project. Takes precedence over any per-directory mapping written by project_set. Self-hosted, it is a sub-directory of the deployment or a sub-domain of your own domain (https://myproject.example.com), depending on how that deployment routes projects. |
https://myproject.form.io |
https://forms.example.com/myproject |
FORMIO_DEFAULT_PROJECT_URL |
no | — | A project URL to offer, not to apply. When set and the working directory has no mapping, the server names it as the suggested project so the agent can confirm it and persist it with project_set. It never changes what a tool resolves — the opposite of FORMIO_PROJECT_URL, which pins the server and cannot be redirected by project_set. |
||
FORMIO_API_KEY |
no | undefined |
Long-lived project API key. When set, the server skips the browser login flow — the only way to authenticate on a host with no browser. | CHANGEME |
CHANGEME |
FORMIO_LOGIN_FORM |
no | Auto-resolved | Override the portal login form URL used by the JWT login flow. | https://formio.form.io/user/login |
https://forms.example.com/formio/user/login |
FORMIO_FORCE_BROWSER |
no | 0 |
When 1, attempt the browser login even where the server detects no browser is available (CI, a container, SSH with no display). |
— | — |
FORMIO_AUTH_HOST / FORMIO_AUTH_PORT |
no | 127.0.0.1 / ephemeral |
Bind address and port for the login server. Set both when running in a container so the login page is reachable through a published port. | — | 0.0.0.0 / 43117 |
FORMIO_INSECURE_TLS |
no | false |
When true, skips TLS certificate verification (sets NODE_TLS_REJECT_UNAUTHORIZED=0) — for self-hosted deployments behind self-signed certs. Do not use against production. |
— | true |
* Not at startup — the server starts and lists every tool without it, and only errors when a tool actually needs a project. The alternative is the project_set tool, which maps a working directory to a project in ~/.formio/projects.json so one server can serve several workspaces. Resolution order: FORMIO_PROJECT_URL, then the mapping for the caller's cwd, then the error. Map a directory before any client connects with npx -y @formio/mcp@0.10.0 project set --project-url <url> --base-url <url> --cwd <path>; project get --cwd <path> prints what resolves and which source won, exiting 0 when it resolved, 1 when nothing is mapped, and 2 when the command itself failed.
This is a pnpm + Turborepo monorepo: the @formio/mcp MCP server (packages/mcp-server/), the @formio/ai agent plugin (plugin/, bundling the server + skill library), and the skill test suite (packages/skill-tests/). Setup, conventions, skill-authoring guidelines, and the release flow are in CONTRIBUTING.md. Security reports: SECURITY.md.