# formio-uag MCP server

> Enables AI agents to interact with Form.io forms by converting JSON schemas into understandable instructions and validating agent submissions.

- Repository: https://github.com/formio/uag
- Page: https://hostedmcp.org/servers/formio/uag
- Transport: remote
- Stars: 12
- License: MIT
- Latest version: 2.0.0

## Install

### Claude Code

```sh
claude mcp add --env 'JWT_SECRET=<YOUR_JWT_SECRET>' --env 'PROJECT=<PROJECT>' --env 'ADMIN_KEY=<YOUR_ADMIN_KEY>' --env 'LICENSE_KEY=<YOUR_LICENSE_KEY>' --env 'MONGO=<YOUR_MONGO>' --env 'PORTAL_SECRET=<YOUR_PORTAL_SECRET>' --env 'PROJECT_KEY=<YOUR_PROJECT_KEY>' --env 'UAG_LICENSE=<YOUR_UAG_LICENSE>' uag -- npx -y @formio/uag
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "uag": {
      "command": "npx",
      "args": [
        "-y",
        "@formio/uag"
      ],
      "env": {
        "JWT_SECRET": "<YOUR_JWT_SECRET>",
        "PROJECT": "<PROJECT>",
        "ADMIN_KEY": "<YOUR_ADMIN_KEY>",
        "LICENSE_KEY": "<YOUR_LICENSE_KEY>",
        "MONGO": "<YOUR_MONGO>",
        "PORTAL_SECRET": "<YOUR_PORTAL_SECRET>",
        "PROJECT_KEY": "<YOUR_PROJECT_KEY>",
        "UAG_LICENSE": "<YOUR_UAG_LICENSE>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "uag": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@formio/uag"
      ],
      "env": {
        "JWT_SECRET": "<YOUR_JWT_SECRET>",
        "PROJECT": "<PROJECT>",
        "ADMIN_KEY": "<YOUR_ADMIN_KEY>",
        "LICENSE_KEY": "<YOUR_LICENSE_KEY>",
        "MONGO": "<YOUR_MONGO>",
        "PORTAL_SECRET": "<YOUR_PORTAL_SECRET>",
        "PROJECT_KEY": "<YOUR_PROJECT_KEY>",
        "UAG_LICENSE": "<YOUR_UAG_LICENSE>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"uag","type":"stdio","command":"npx","args":["-y","@formio/uag"],"env":{"JWT_SECRET":"<YOUR_JWT_SECRET>","PROJECT":"<PROJECT>","ADMIN_KEY":"<YOUR_ADMIN_KEY>","LICENSE_KEY":"<YOUR_LICENSE_KEY>","MONGO":"<YOUR_MONGO>","PORTAL_SECRET":"<YOUR_PORTAL_SECRET>","PROJECT_KEY":"<YOUR_PROJECT_KEY>","UAG_LICENSE":"<YOUR_UAG_LICENSE>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "uag": {
      "command": "npx",
      "args": [
        "-y",
        "@formio/uag"
      ],
      "env": {
        "JWT_SECRET": "<YOUR_JWT_SECRET>",
        "PROJECT": "<PROJECT>",
        "ADMIN_KEY": "<YOUR_ADMIN_KEY>",
        "LICENSE_KEY": "<YOUR_LICENSE_KEY>",
        "MONGO": "<YOUR_MONGO>",
        "PORTAL_SECRET": "<YOUR_PORTAL_SECRET>",
        "PROJECT_KEY": "<YOUR_PROJECT_KEY>",
        "UAG_LICENSE": "<YOUR_UAG_LICENSE>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add uag --env 'JWT_SECRET=<YOUR_JWT_SECRET>' --env 'PROJECT=<PROJECT>' --env 'ADMIN_KEY=<YOUR_ADMIN_KEY>' --env 'LICENSE_KEY=<YOUR_LICENSE_KEY>' --env 'MONGO=<YOUR_MONGO>' --env 'PORTAL_SECRET=<YOUR_PORTAL_SECRET>' --env 'PROJECT_KEY=<YOUR_PROJECT_KEY>' --env 'UAG_LICENSE=<YOUR_UAG_LICENSE>' -- npx -y @formio/uag
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.uag]
command = "npx"
args = ["-y", "@formio/uag"]

[mcp_servers.uag.env]
JWT_SECRET = "<YOUR_JWT_SECRET>"
PROJECT = "<PROJECT>"
ADMIN_KEY = "<YOUR_ADMIN_KEY>"
LICENSE_KEY = "<YOUR_LICENSE_KEY>"
MONGO = "<YOUR_MONGO>"
PORTAL_SECRET = "<YOUR_PORTAL_SECRET>"
PROJECT_KEY = "<YOUR_PROJECT_KEY>"
UAG_LICENSE = "<YOUR_UAG_LICENSE>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'JWT_SECRET=<YOUR_JWT_SECRET>' -e 'PROJECT=<PROJECT>' -e 'ADMIN_KEY=<YOUR_ADMIN_KEY>' -e 'LICENSE_KEY=<YOUR_LICENSE_KEY>' -e 'MONGO=<YOUR_MONGO>' -e 'PORTAL_SECRET=<YOUR_PORTAL_SECRET>' -e 'PROJECT_KEY=<YOUR_PROJECT_KEY>' -e 'UAG_LICENSE=<YOUR_UAG_LICENSE>' uag npx -- -y @formio/uag
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "uag": {
      "command": "npx",
      "args": [
        "-y",
        "@formio/uag"
      ],
      "env": {
        "JWT_SECRET": "<YOUR_JWT_SECRET>",
        "PROJECT": "<PROJECT>",
        "ADMIN_KEY": "<YOUR_ADMIN_KEY>",
        "LICENSE_KEY": "<YOUR_LICENSE_KEY>",
        "MONGO": "<YOUR_MONGO>",
        "PORTAL_SECRET": "<YOUR_PORTAL_SECRET>",
        "PROJECT_KEY": "<YOUR_PROJECT_KEY>",
        "UAG_LICENSE": "<YOUR_UAG_LICENSE>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `JWT_SECRET` | yes | yes | Secret used to generate and validate JWT tokens |
| `PROJECT` | yes | no | API endpoint to Enterprise project or OSS server |
| `ADMIN_KEY` | no | yes | Server admin key for Form.io Open Source. Not required for Enterprise deployment. |
| `LICENSE_KEY` | no | yes | Form.io license for a self-hosted Enterprise deployment; when it includes the UAG it also enables the Agent API. Not required for Form.io Open Source, or for a project on Form.io's hosted service (https://*.form.io). |
| `MONGO` | no | yes | Optional. The UAG's own database (only uag-* collections, never submissions): run records, runs that survive a restart, remote MCP sign-in. Needs a license that includes the UAG. |
| `PORTAL_SECRET` | no | yes | Enterprise Portal connection secret |
| `PROJECT_KEY` | no | yes | Project API Key (Enterprise) or ADMIN_KEY (OSS) |
| `UAG_LICENSE` | no | yes | Deprecated: use LICENSE_KEY. Still read until UAG 3.0. |
| `BASE_URL` | no | no | Optional. The URL clients reach the UAG at, for the OAuth discovery documents remote MCP clients read. Derived from each request when unset. |
| `CLAUDE_API_KEY` | no | no |  |
| `CORS` | no | no | true (the default) allows every origin, false turns CORS off, any other value is the allowed origin, or several separated by commas |
| `DEBUG` | no | no | Debug logging filter (e.g. formio.*) |
| `JWT_EXPIRE_TIME` | no | no | Lifetime of the tokens the UAG issues, in minutes (default: 60) |
| `LOGIN_FORM` | no | no | Public URL to login form JSON endpoint |
| `MCP_OAUTH` | no | no | true turns on OAuth sign-in for remote MCP clients. Needs MONGO. |
| `MONGO_CONFIG` | no | no | MongoDB driver configuration (JSON) |
| `PORT` | no | no | Server port (default: 3200) |
| `PROJECT_TTL` | no | no | Project cache refresh interval in seconds (default: 900) |
| `TASK_RUN_RETENTION_DAYS` | no | no | Days run records are kept. Default 90; 0 keeps them forever. |
| `TEMPLATE_SYNC` | no | no | When a module's template is installed into the project: boot, refresh or off (default: boot) |
| `TRUST_PROXY` | no | no | Express's trust proxy (true, a number of hops, or addresses). Set it behind a reverse proxy, so the UAG reads its public URL from the forwarded headers. |
| `TYPESAFE_API_KEY` | no | no |  |
| `UAG_DATABASE` | no | no | The database to use on the MONGO connection. Default uag. |
| `UAG_ENGINES` | no | no |  |
| `UAG_ENGINE_FAST_MODEL` | no | no |  |

## FAQ

### Does the UAG require redeploying forms when instructions change?

No, you can update tasks or fields within the form and the agent will adapt without needing redeployments, prompt changes, or model retraining.
