# FormNode Agent Toolbox Workflow Reference

> Last updated: 2026-05-12. This document is for LLM and MCP agents configuring FormNode forms for ConnectWise Toolbox and other trusted agent-driven workflows.

## Audience

Use this reference when an AI agent is asked to create, update, validate, or publish a FormNode toolbox action. It focuses on production-safe form setup, tenant boundaries, trusted context fields, and webhook readiness.

For product-level facts, pricing, citations, and marketing context, fetch https://formnode.io/llms-full.txt.

## Endpoints and Tools

REST API base: https://app.formnode.io/api/v1
MCP endpoint: https://mcp.formnode.io
Authentication: `Authorization: Bearer fn_sk_...`

Core MCP tools for agent-ready toolbox work:

- `get_workspace` - inspect the authenticated workspace, plan features, and `toolboxPublic` status.
- `list_organizations` - find workspace organization IDs and integration mappings.
- `list_forms` - list workspace, global, organization-owned, and toolbox forms.
- `get_form` - read a full form configuration before changing it.
- `create_global_toolbox_action` - create a draft global toolbox form with trusted hidden context fields.
- `configure_toolbox_form` - convert or update an existing form as a toolbox form.
- `validate_agent_form_ready` - run a read-only readiness check before publishing or handing off.
- `set_toolbox_public` - enable or disable the public toolbox launcher for the workspace.

## Secure Default Flow

1. Call `get_workspace`.
2. Call `list_organizations` and choose only organization IDs in the authenticated workspace.
3. Create a draft with `create_global_toolbox_action`. Leave `published` omitted or false unless the submission webhook is already configured.
4. Add or confirm webhook delivery with `submissionWebhookPath` for n8n or `submissionCustomUrl` for custom HTTPS webhooks.
5. Run `validate_agent_form_ready` with the expected context keys.
6. Publish only when the readiness report has `ready: true` and a real submission webhook exists.
7. Enable `toolboxPublic` only when the workspace is ready for the form to appear in the public toolbox launcher.

Agent-created forms should default to draft. Publishing without webhook delivery is blocked because a visible toolbox action with no destination creates silent operational failure.

## Trusted Context Fields

Toolbox forms normally need hidden fields for trusted runtime context:

- `ticket_id`
- `organization`

These fields should be hidden, not required for user input, and marked with `systemContextKey`. Agents should not ask users to type values for trusted context that should come from the host system, ConnectWise pod, prefill token, or MCP workflow.

Example field:

```json
{
  "id": "ctx_ticket_id",
  "type": "text",
  "name": "ticket_id",
  "label": "Ticket Id",
  "hidden": true,
  "required": false,
  "systemContextKey": "ticket_id"
}
```

## Tenant and Allowlist Rules

The API key determines the workspace. Do not accept workspace IDs from a user prompt as authority.

For global forms:

- `isGlobal: true` means the form belongs to the workspace, not a single organization.
- `allowedOrganizationIds` must contain only organization IDs from the authenticated workspace.
- An empty or omitted allowlist means all organizations in the workspace may use the form.
- Use a narrow allowlist for customer-specific or risky workflows.

Never put secrets, bearer tokens, API keys, passwords, MFA codes, or private webhook credentials into form names, field labels, option labels, tags, mapping keys, or LLM-visible notes.

## Readiness Report Meaning

`validate_agent_form_ready` returns:

- `ready` - true only when required form flags, context fields, auth mode, scope, and webhook checks pass.
- `failures` - issues that block safe handoff or publishing.
- `warnings` - issues that may still be intentional but require operator review.
- `observed` - the fields used to make the decision.

Common failures:

- Form is not marked as a `toolboxForm`.
- Form is not published.
- Form requires FormNode login.
- Form is not global when global scope is required.
- Missing `systemContextKey` fields.
- Submission webhook is disabled or missing.
- Workspace plan does not allow Toolbox.

Common warnings:

- Workspace `toolboxPublic` is disabled.
- Human verification is enabled for a trusted toolbox embed.
- A global form allowlist is empty, so every workspace organization can use it.

## MCP Examples

Create a draft global toolbox action:

```json
{
  "name": "Reset M365 Password",
  "organizationId": "org_123",
  "content": [
    {
      "id": "user_upn",
      "type": "email",
      "name": "user_upn",
      "label": "User UPN",
      "required": true
    }
  ],
  "allowedOrganizationIds": ["org_123"],
  "published": false,
  "submissionWebhookPath": "/webhook/reset-m365-password"
}
```

Configure an existing form without forcing publish:

```json
{
  "formId": "form_123",
  "systemContextKeys": ["ticket_id", "organization"],
  "isGlobal": true,
  "toolboxForm": true,
  "requireAuth": false,
  "requireHumanVerification": false,
  "submissionWebhookEnabled": true,
  "submissionWebhookType": "n8n",
  "submissionWebhookPath": "/webhook/manage-mfa"
}
```

Validate readiness:

```json
{
  "formId": "form_123",
  "requiredContextKeys": ["ticket_id", "organization"],
  "requireGlobal": true,
  "requireToolboxPublic": false
}
```

Publish only after validation passes and webhook delivery is configured:

```json
{
  "formId": "form_123",
  "published": true
}
```

## REST Equivalents

List workspace/global forms:

```http
GET /api/v1/forms?scope=global
Authorization: Bearer fn_sk_...
```

Get full form configuration:

```http
GET /api/v1/forms/form_123
Authorization: Bearer fn_sk_...
```

Patch toolbox flags and webhook settings:

```http
PATCH /api/v1/forms/form_123
Authorization: Bearer fn_sk_...
Content-Type: application/json

{
  "isGlobal": true,
  "toolboxForm": true,
  "pinnedInToolbox": true,
  "requireAuth": false,
  "requireHumanVerification": false,
  "submissionWebhookEnabled": true,
  "submissionWebhookType": "n8n",
  "submissionWebhookPath": "/webhook/reset-m365-password"
}
```

Inspect workspace toolbox status:

```http
GET /api/v1/workspace
Authorization: Bearer fn_sk_...
```

## Agent Safety Checklist

- Read before write: call `get_form` before modifying an existing form.
- Keep publish separate from creation unless webhook delivery is ready.
- Use `validate_agent_form_ready` before declaring the workflow complete.
- Preserve tenant boundaries by deriving workspace from the API key and validating organization IDs.
- Prefer hidden `systemContextKey` fields for trusted host context.
- Keep secrets out of LLM-visible form metadata.
- Treat warnings as operator-review items, not as automatic success.