Skip to main content
OpnForm includes a remote Model Context Protocol server. It lets AI assistants build forms from a conversation, show you a private preview, manage forms, and help you work with submissions. The setup depends on whether you use OpnForm Cloud or a self-hosted OpnForm instance.

Choose your OpnForm setup

The hosted MCP server is already enabled at:
You can start a private form draft without an OpnForm account. Connect your account with OAuth only when you want the assistant to save forms, manage existing forms, or read submissions.If you are signed in to OpnForm, open Settings → MCP & AI agents to find the server URL and ready-to-copy instructions for your AI client. There is no activation switch for OpnForm Cloud.

Create a form with OpnForm Cloud

You can ask a compatible AI assistant to create a form before connecting your OpnForm account.
1

Describe the form you need

Explain the form’s goal, audience, questions, and any requirements you already know. The assistant validates the definition before creating a private draft.
2

Review the interactive preview

Open the preview returned by the assistant. Test the questions and flow, then ask the assistant to add, remove, or revise fields.The preview is private and does not publish the form.
3

Open the draft in OpnForm

Select Open in OpnForm when you want to continue in the visual editor. You can customize the design before creating an account or signing in to save the form. Changes are saved automatically to the private draft without publishing it. Keep the editor open until it shows Draft saved; closing or reloading with unsaved changes triggers a browser warning. If the assistant updates the same draft while you are editing, the editor reloads the latest version and displays a warning.
4

Connect your account when needed

Complete OAuth when you ask the assistant to save the draft, manage your existing forms, or access submissions. OpnForm displays the requested connection before you approve it.
Guest draft links are private bearer links. Do not share them publicly. If a preview expires, ask the assistant to generate a fresh preview.

Enable MCP on a self-hosted instance

Prerequisites

Before you enable MCP, verify that your instance has:
  • public HTTPS values for APP_URL and FRONT_URL;
  • a valid Laravel Passport key pair;
  • persistent storage for the Passport keys so existing OAuth connections survive container replacement;
  • a trusted MCP client that supports remote streamable HTTP servers and OAuth.
Do not expose a production MCP endpoint over plain HTTP. Localhost URLs are suitable only for local client testing.
1

Open the MCP settings

Sign in as an administrator, then open Settings → MCP & AI agents.
2

Resolve the setup checks

OpnForm verifies the public URLs and Passport keys. If a requirement is missing, the page identifies what you need to configure before activation.
3

Enable the server

Turn on Enable MCP.
Enable MCP in the settings of a self-hosted OpnForm instance
The status changes to MCP is available and the page displays your /mcp endpoint.
The switch is stored in the OpnForm database and applies without restarting the application. Until an administrator changes it, OpnForm uses MCP_ENABLED from the API environment as the default:
Self-hosted instances use a strict authenticated flow. They expose validation and account-scoped MCP tools, but not the cloud guest draft endpoints.

Connect an AI assistant

For OpnForm Cloud, use https://api.opnform.com/mcp. For a self-hosted instance, copy the endpoint displayed in Settings → MCP & AI agents.
Copy the MCP server URL from OpnForm settings
The settings page generates the correct command or configuration for your client. Select your client, then copy the displayed value.
Select an AI client and copy its generated MCP configuration
Use Install in Cursor for one-click setup, or copy the generated mcpServers JSON configuration.
Open Portable Agent Plugin configuration in OpnForm settings if your client supports Agent Plugins. To share instructions for a particular client, include the selected client in the settings URL:
On self-hosted instances, replace https://opnform.com with your frontend URL. Supported agent values are cursor, claude_code, chatgpt, codex, and other.

Authenticate your OpnForm account

Form, workspace, and submission tools use OAuth. The MCP client discovers OpnForm’s authorization metadata, opens the OpnForm consent screen, and uses authorization code flow with PKCE S256. You never paste an OpnForm password or access token into a conversation. On OpnForm Cloud, guest form creation and preview remain available before authentication. On self-hosted instances, guest draft creation is unavailable. Schema resources, the field catalog, and validate_form_definition remain available before authentication because they do not read or store account data.
After authenticating a Codex connection, start a new conversation with OpnForm selected so the MCP client loads the stored credential.
A connected user can revoke the current access and refresh tokens by sending an authenticated DELETE request to /mcp-oauth/session.

Available capabilities

Workspace administration and submission mutations are unavailable. MCP does not expose permanent form deletion, form restoration, submission deletion, or submission restoration. Normal workspace permissions and plan limits continue to apply. If saving a form disables unavailable premium features, the tool response lists those changes. Before validating or saving a definition, OpnForm silently normalizes issues it can repair without guessing intent. For example, it removes empty or invalid display-logic blocks, repairs stale logic reference metadata, discards unusable entries from select options, and removes invalid computed variables together with formulas or logic that become invalid as a result. Ambiguous changes still return a precise error path, such as an empty select field, a duplicate field ID, or a malformed form block.

Computed variables and display logic

The versioned form-definition schema and field catalog document computed variables, display-logic actions, condition groups, and the operators available for each reference type. Formula references use technical IDs in braces:
A logic condition may use that calculated value by setting property_meta.type to computed:
With patch_form_draft, replace the complete computed_variables list through set_form_values, and add or modify a block’s logic through add_block or update_block. The draft is normalized and validated atomically before its version changes.

Compare and restore draft versions

Each new interactive preview is pinned to the draft version it displays. Later chat or editor changes do not update that earlier preview. Ask your assistant to “show version 1” to compare it, or “return to version 1” to continue from it.
  • get_form_draft and preview_form_draft accept an optional version. Omit it to use the current version.
  • restore_form_draft_version takes draft_handle, the latest expected_version, and the historical version to restore. It creates a new current version without deleting intervening versions. For example, restoring V1 while on V3 creates V4 with V1’s content.
  • Restoration does not save or publish an account form. After restoring, request a new preview and continue the normal save flow.
  • An old preview cannot silently open a newer version in the editor. Restore it first, or use the latest preview. A version-pinned editor link is checked both when created and when opened; if the draft changes in between, request a new link.
History follows the seven-day guest draft lifetime. Saving through the browser editor claims the guest draft: guest editing and restoration stop, but existing signed, version-pinned previews remain readable until the original expiry. Saving through ChatGPT with create_form_in_account instead creates an independent account form and leaves the guest draft active until expiry, so you can still compare or restore its versions. Guest edits and restoration never update the saved account form, and account-form edits never change the guest snapshots. Use account tools for changes to saved forms; this feature does not add account-form revision history or rollback. Versions overwritten before this feature was enabled cannot be recovered, and previously generated unversioned preview links are not retroactively pinned. Self-hosted deployments must run the database migration before enabling the updated MCP code. Refresh tools in your AI assistant to discover the restoration tool and optional version parameters.

Self-hosted OAuth configuration

The following settings apply only to self-hosted instances. Configure the callback destinations accepted by your instance: The consent screen displays the callback destination before approval. OAuth authorization requests and login tickets use atomic cache locks. If you run multiple application instances, configure Laravel’s default cache as a shared, lock-capable store such as Redis or DynamoDB. File and array cache drivers are suitable only for single-instance development.

Self-hosted rate limits

The default limits are permissive for normal agent use:

Privacy and observability

When MCP_OBSERVABILITY_ENABLED=true, a self-hosted instance records only the MCP method, tool name, authentication mode, outcome, HTTP status, and duration. OpnForm does not include request arguments, OAuth tokens, form definitions, submission values, export URLs, user identifiers, or IP addresses in MCP telemetry or structured MCP request logs. Set MCP_OBSERVABILITY_ENABLED=false to disable MCP usage events and their structured logs. General instance telemetry remains controlled by OPNFORM_TELEMETRY_DISABLED (with the deprecated OPNFORM_ANONYMOUS_TELEMETRY_DISABLED name supported when the new variable is absent).

Troubleshooting

This switch appears only on self-hosted instances. Verify that APP_URL and FRONT_URL use public HTTPS origins and that the API container can read a persistent Passport key pair. Reload the settings page after correcting the configuration.
Allow /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource, and /.well-known/oauth-protected-resource/mcp to reach the API. A generic Nginx rule blocking paths that start with a dot can reject these routes before they reach OpnForm. Keep the hidden-file protection and add an exception for these specific OAuth routes.Opening /mcp directly in a browser can return 405 Method Not Allowed because MCP requests use HTTP POST. Configure the URL in your MCP client instead.
Complete the OAuth flow from the MCP client. Guest drafts on OpnForm Cloud do not authenticate your account automatically.
Start a new conversation after authentication. Some clients retain the tool and authentication state that existed when the conversation started.
Ask the assistant to create a fresh preview. Preview links are private and expire automatically.
Check the client callback against MCP_OAUTH_REDIRECT_DOMAINS and MCP_OAUTH_CUSTOM_SCHEMES. Also verify that APP_URL, FRONT_URL, and reverse-proxy forwarding headers reflect the public origins.
Confirm that your /mcp endpoint is reachable from outside your private network, that your reverse proxy allows streamable HTTP responses, and that no firewall or authentication proxy blocks MCP discovery requests.

Agent safety behavior

  • Fetch the current form revision before updating, publishing, or trashing it.
  • Re-fetch and reconcile the form after a revision conflict.
  • Ask before publishing or moving a form to the trash.
  • Use submission data only when it is necessary for the user’s request.
  • Respect validation, workspace permissions, plan cleaning, and rate limits.