formio/uag repository overview

⁠Form.io Universal Agent Gateway (UAG)

The UAG uses the Model Context Protocol⁠ to let AI agents work with Form.io⁠ forms, resources, and workflows. It converts a Form JSON schema into an AI-readable markdown description — giving an agent the same understanding of a form that the JavaScript renderer gives a human — then validates and submits the result against the same rules the renderer enforces.

Also published as @formio/uag⁠ on npm and listed in the official MCP Registry⁠ as io.form/formio-uag.

⁠What it enables

Conversation to a validated submission. An agent collects data through natural language and produces a deterministic, schema-valid Form.io submission — no bespoke parsing, and the form's own validation still applies.

Agentic workflows. An agent reads existing submission data plus your criteria, then contributes its own data and analysis back into the record — review steps, enrichment, triage, and similar automation driven by a form submission.

⁠Quick start

Against a Form.io Open Source server:

docker run -d --name formio-uag -p 3200:3200 \
  -e PROJECT=https://forms.example.com \
  -e ADMIN_KEY=your-admin-key \
  -e JWT_SECRET=your-jwt-secret \
  -e BASE_URL=https://forms.example.com \
  -e LOGIN_FORM=https://forms.example.com/user/login \
  --restart unless-stopped \
  formio/uag

Against a Form.io Enterprise project, use PROJECT_KEY and UAG_LICENSE in place of ADMIN_KEY:

docker run -d --name formio-uag -p 3200:3200 \
  -e PROJECT=https://forms.example.com/myproject \
  -e PROJECT_KEY=your-project-api-key \
  -e UAG_LICENSE=your-license \
  -e JWT_SECRET=your-jwt-secret \
  -e BASE_URL=https://forms.example.com \
  --restart unless-stopped \
  formio/uag

Docker Compose is the recommended path for anything beyond a single container. Working stacks — including one that runs the UAG alongside a Form.io OSS server — are in the examples directory⁠.

⁠Connecting an agent

The MCP endpoint is http://<host>:<port>/mcp, served over Streamable HTTP (default port 3200).

Integrations run their own MCP client and connect outward to the UAG, so the UAG does not need to be publicly reachable for them — only reachable from the integration, such as over a private Docker network or localhost. The bundled Claude integration is published as formio/uag-claude⁠.

⁠Configuration

Treat every key, secret, and license as sensitive: supply them through an .env file or your platform's secret store rather than inline in a committed file.

⁠Caching behaviour worth knowing

Forms and resources are cached and refreshed on the PROJECT_TTL interval, so a change to a form can take up to that long to appear to an agent. Set PROJECT_TTL=0 to disable refreshing entirely, in which case a restart is the only way to pick up changes.

⁠Links

• Source and full documentation: https://github.com/formio/uag⁠
• Examples, including agentic workflows and a conversational form: https://github.com/formio/uag/tree/main/examples⁠
• Claude integration image: https://hub.docker.com/r/formio/uag-claude⁠
• MCP server for building and managing Form.io forms from a coding agent: https://hub.docker.com/r/formio/mcp⁠
• License: MIT