Developer docs menu

Quickstart

Run the UAG yourself inside your own network, or try it on a 30-day free trial project, and make your first MCP and Agent API calls.

This page gets a UAG running and answering in about ten minutes. There are two ways to try it:

  • Self-hosted: Form.io Open Source and the UAG in one Docker Compose stack, on your machine or your own servers. Free, and nothing leaves your network unless you enable a model engine that calls out.
  • On a 30-day free trial: the UAG in Docker, connected to a trial project on portal.form.io, to try the features that need a license.

For production, run the UAG self-hosted with Form.io Enterprise and a license that includes the UAG; see Deployment.

Both end with the same first calls: a token, the MCP tool list, and the Agent API's capabilities.

Prerequisites: Docker with Compose, and curl. Node.js 22 or newer for the JavaScript examples.

tip

To have your coding agent do this, run npx skills add formio/ai in your application's folder to install the Agentic Coding Plugin, and ask, for example: "Deploy the UAG against our Form.io project with Docker Compose and make our serviceRequest form agent-ready." It writes the Compose file with placeholder secrets and shows each form change before saving it.

Self-hosted with Form.io Open Source

Running the UAG inside your own security boundary is the deployment most teams choose. The UAG, Form.io and MongoDB all run in your network; the UAG calls only the Form.io server you point it at, plus whichever model providers you explicitly enable. Agents connect from inside the network, or through a public URL you choose to expose. Form.io Open Source and the UAG's MCP and conversation features need no license.

1. Write the Compose file

Create a directory with this docker-compose.yml. Replace every CHANGEME before you run it anywhere but your own machine; ADMIN_KEY must be the same on both services.

yaml
services:
  mongo:
    image: mongo:7
    restart: always
    volumes:
      - mongo-data:/data/db

  # Form.io Open Source. The container listens on 3001.
  formio:
    image: formio/formio
    restart: always
    depends_on:
      - mongo
    ports:
      - "3000:3001"
    environment:
      NODE_CONFIG: '{"mongo": "mongodb://mongo:27017/formio-oss", "jwt": {"secret": "CHANGEME"}, "mongoSecret": "CHANGEME"}'
      ROOT_EMAIL: admin@example.com
      ROOT_PASSWORD: CHANGEME
      ADMIN_KEY: CHANGEME
    healthcheck:
      # The UAG loads the project at startup, so hold it back until Form.io answers.
      test: ["CMD", "node", "-e", "fetch('http://localhost:3001/').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
      interval: 5s
      timeout: 5s
      retries: 40

  formio-uag:
    image: formio/uag
    restart: always
    depends_on:
      formio:
        condition: service_healthy
    ports:
      - "3200:3200"
    environment:
      PORT: 3200
      # Container-to-container address of the Form.io server.
      PROJECT: http://formio:3001
      ADMIN_KEY: CHANGEME
      JWT_SECRET: CHANGEME
      # Re-read the project every 10 seconds while you experiment.
      PROJECT_TTL: 10

volumes:
  mongo-data:

2. Start it

bash
docker compose up -d
docker compose logs -f formio-uag

When the UAG is ready it prints, among other lines:

text
[formio-uag] Open Source edition. Agentic Formflow requires a license (LICENSE_KEY) that includes the UAG, or a project on Form.io's hosted service; MCP and conversation forms are unaffected.
Form.io UAG server running on port 3200

Form.io is at http://localhost:3000 (log in as admin@example.com with ROOT_PASSWORD), and the UAG is at http://localhost:3200.

note

The UAG exits if it cannot load the project. If the logs say "No Form.io project could be loaded", check that PROJECT is reachable from inside the UAG container and that ADMIN_KEY matches the Form.io server's.

3. Give the agent a form

Agents see only forms tagged uag. Create one with the admin key (or in the portal, under Settings → Tags):

bash
curl -s -X POST http://localhost:3000/form \
  -H 'x-admin-key: CHANGEME' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Support Request",
    "name": "supportRequest",
    "path": "supportrequest",
    "type": "form",
    "tags": ["uag"],
    "components": [
      { "type": "textfield", "key": "fullName", "label": "Full name", "input": true, "validate": { "required": true } },
      { "type": "email", "key": "email", "label": "Email", "input": true, "validate": { "required": true } },
      { "type": "radio", "key": "urgency", "label": "Urgency", "input": true,
        "values": [ { "label": "Low", "value": "low" }, { "label": "High", "value": "high" } ] },
      { "type": "button", "key": "submit", "label": "Submit", "input": true, "action": "submit" }
    ]
  }'

Wait PROJECT_TTL seconds (10 here) for the UAG to register it, or run docker compose restart formio-uag.

To make the UAG reachable from outside the host, put it behind a reverse proxy with TLS, and set TRUST_PROXY so the UAG reads its public URL from the proxy's forwarded headers (or set BASE_URL to that URL). Remote MCP clients such as claude.ai connectors also need MCP_OAUTH=true and a database of the UAG's own (MONGO); see Connect Claude. Read Deployment and Security before you expose it.

Try it on a 30-day free trial

To try the features that need a license, such as Agentic Formflow, start a 30-day free trial on portal.form.io, run the UAG yourself and point it at the trial project. The UAG still runs where you run it, so its tokens, logs and engine traffic stay in your infrastructure. The trial is for trying the UAG; for production, run it self-hosted with Form.io Enterprise.

  1. Create a project. Start a free trial at https://portal.form.io and create a project. Note its API endpoint, https://<project>.form.io.
  2. Create an API key. In the project, open Project Settings → API Keys and add a key. The UAG uses it as PROJECT_KEY. Treat it as a secret: it grants administrator access to the project.
  3. Tag a form. Open a form, add uag under Settings → Tags, and save.
  4. Run the UAG.
bash
docker run -d --name formio-uag -p 3200:3200 \
  -e PROJECT="https://<project>.form.io" \
  -e PROJECT_KEY="<your API key>" \
  -e JWT_SECRET="<a long random string>" \
  formio/uag

Against a trial project, the UAG needs no license of its own, and Agentic Formflow is allowed (/agent/capabilities reports reason: "hosted"). A self-hosted UAG serving Form.io Enterprise, or running Agentic Formflow on your own Form.io, needs a license that includes the UAG; see Deployment.

note

A database of the UAG's own (MONGO) needs a license that includes the UAG (LICENSE_KEY), with a trial project too.

In the commands below, a trial project uses its own name in the client_id (<project>-x-token) and its API key as the secret: set PROJECT_KEY instead of ADMIN_KEY, send -H "x-token: $PROJECT_KEY" where a command sends x-admin-key, and where a step runs docker compose up -d, remove the container (docker rm -f formio-uag) and run the docker run command again with the new -e settings.

First calls

The examples use http://localhost:3200. Set two shell variables first:

bash
UAG=http://localhost:3200
ADMIN_KEY=CHANGEME

Get a token

Server-side clients exchange a key for a UAG access token with the client_credentials grant. The client_id is the project name followed by the credential type:

Deployment client_id client_secret
Form.io Open Source formio-oss-x-admin-key ADMIN_KEY
Form.io Enterprise, or a trial project on portal.form.io <project name>-x-token PROJECT_KEY

The token endpoint is /auth/token on the UAG, on every edition, and it is always on: it needs no BASE_URL, MONGO or MCP_OAUTH. Against an Enterprise or trial project, the project's routes are also served under its name, so /<project name>/auth/token works too.

bash
curl -s -X POST $UAG/auth/token \
  -H 'Content-Type: application/json' \
  -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"formio-oss-x-admin-key\",\"client_secret\":\"$ADMIN_KEY\"}"
json
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "formio"
}

expires_in is in seconds: JWT_EXPIRE_TIME (minutes, default 60) times 60. A 400 means the client_id prefix or the secret is wrong.

bash
TOKEN=$(curl -s -X POST $UAG/auth/token -H 'Content-Type: application/json' \
  -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"formio-oss-x-admin-key\",\"client_secret\":\"$ADMIN_KEY\"}" \
  | node -pe 'JSON.parse(require("fs").readFileSync(0)).access_token')

List the MCP tools

/mcp speaks JSON-RPC over Streamable HTTP. The UAG runs it statelessly, so a single tools/list request works without a session:

bash
curl -s -X POST $UAG/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The answer arrives as one Server-Sent Event:

text
event: message
data: {"result":{"tools":[{"name":"get_forms","title":"Get Available Forms", ... }]},"jsonrpc":"2.0","id":1}

Call a tool the same way, with tools/call:

bash
curl -s -X POST $UAG/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_forms","arguments":{}}}'

The text it returns lists Support Request (**supportRequest**) with your permissions on it. Real clients use an MCP SDK instead of curl; MCP tools has a complete one.

Ask the Agent API what it can do

bash
curl -s $UAG/agent/capabilities -H "x-admin-key: $ADMIN_KEY"
json
{
  "requestId": "f79dcf1c-11d7-4387-be12-e6c54527e2a6",
  "engines": [],
  "operations": {
    "extract": { "available": false, "engines": [] },
    "decide": { "available": false, "engines": [] },
    "generate": { "available": false, "engines": [] },
    "chat": { "available": false, "engines": [] }
  },
  "edition": "open-source",
  "formflow": { "licensed": false, "allowed": false, "reason": "unlicensed" },
  "durableRuns": false,
  "mcpOAuth": false
}

No engine is enabled yet, so no operation is available. durableRuns and mcpOAuth are false because the UAG has no database of its own (MONGO); see Deployment. A bearer token works here too (-H "Authorization: Bearer $TOKEN"). The admin-key form works only from servers: the UAG refuses admin credentials on any request that carries an Origin or Sec-Fetch-Site header.

Try the Agent API without a model

The stub engines answer instantly with fixed values and need no credentials and no license. Add them to the UAG's environment and recreate the container:

yaml
      UAG_ENGINES: stub-decision,stub-agent
bash
docker compose up -d
curl -s -X POST $UAG/supportrequest/agent/decide \
  -H "x-admin-key: $ADMIN_KEY" -H 'Content-Type: application/json' \
  -d '{"data":{}}'

A form's operations are under the form's URL on the UAG, as its submissions are: here the form's path, supportrequest, at the UAG's root. Against an Enterprise or trial project, the form is under the project's name ($UAG/<project name>/supportrequest/agent/decide), and the key is -H "x-token: $PROJECT_KEY".

json
{ "requestId": "b011c34d-9bda-447c-bb8d-9e53f8d362dc", "error": "The form \"supportRequest\" defines no tasks.", "code": "invalid_request" }

The form defines no task yet, so the UAG answers 400 and says so. Give it one: a criteria content component, and the uag property on the field the task decides (see Concepts). This replaces the form with the same fields plus a triage task that decides urgency (on a trial project, add the same two properties in the form builder instead):

bash
FORM_ID=$(curl -s http://localhost:3000/supportrequest -H "x-admin-key: $ADMIN_KEY" \
  | node -pe 'JSON.parse(require("fs").readFileSync(0))._id')
curl -s -X PUT http://localhost:3000/form/$FORM_ID \
  -H "x-admin-key: $ADMIN_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Support Request",
    "name": "supportRequest",
    "path": "supportrequest",
    "type": "form",
    "tags": ["uag"],
    "components": [
      { "type": "textfield", "key": "fullName", "label": "Full name", "input": true, "validate": { "required": true } },
      { "type": "email", "key": "email", "label": "Email", "input": true, "validate": { "required": true } },
      { "type": "content", "key": "triageCriteria", "input": false,
        "html": "<p>Decide how urgent the request is: high when the customer cannot work at all, otherwise low.</p>",
        "properties": { "uag": "triage", "uagField": "criteria" } },
      { "type": "radio", "key": "urgency", "label": "Urgency", "input": true,
        "properties": { "uag": "triage" },
        "values": [ { "label": "Low", "value": "low" }, { "label": "High", "value": "high" } ] },
      { "type": "button", "key": "submit", "label": "Submit", "input": true, "action": "submit" }
    ]
  }'

Wait PROJECT_TTL seconds and run the decide call again: urgency now comes back with the stub's placeholder answer. To decide for real, enable a real engine such as jev or claude (see Engines), which needs a LICENSE_KEY that includes the UAG, or a trial project on Form.io's hosted service.

Next steps