Skip to content

Beautiful Open-Source Form Builder

Document MCP for cloud and self-hosted users (#1265)

Julien Nahum262e07a21d21
diff --git a/api/app/Http/Controllers/Settings/McpSettingsController.php b/api/app/Http/Controllers/Settings/McpSettingsController.php
index ca795e7ca..916c32259 100644
--- a/api/app/Http/Controllers/Settings/McpSettingsController.php
+++ b/api/app/Http/Controllers/Settings/McpSettingsController.php
@@ -18,7 +18,9 @@ final class McpSettingsController extends Controller
McpAvailability $availability,
McpConnectionConfiguration $connection,
): JsonResponse {
- Gate::authorize('manage-instance-settings');
+ if (config('app.self_hosted')) {
+ Gate::authorize('manage-instance-settings');
+ }
return response()->json($this->payload($availability, $connection));
}
@@ -55,7 +57,8 @@ final class McpSettingsController extends Controller
$status = $availability->status($readiness);
return array_merge($status, [
+ 'self_hosted' => (bool) config('app.self_hosted'),
'source' => $status['configured_value'] === null ? 'environment' : 'settings',
- ], $connection->forSelfHostedInstance());
+ ], $connection->forInstance());
}
}
diff --git a/api/app/Support/Mcp/McpConnectionConfiguration.php b/api/app/Support/Mcp/McpConnectionConfiguration.php
index ce3b4b6fd..10e38cc28 100644
--- a/api/app/Support/Mcp/McpConnectionConfiguration.php
+++ b/api/app/Support/Mcp/McpConnectionConfiguration.php
@@ -12,7 +12,7 @@ final class McpConnectionConfiguration
* install_urls: array{cursor: string}
* }
*/
- public function forSelfHostedInstance(): array
+ public function forInstance(): array
{
$appUrl = rtrim((string) config('app.url'), '/');
$serverUrl = $appUrl.'/mcp';
diff --git a/api/routes/api.php b/api/routes/api.php
index 2ca891a57..2a7990ac7 100644
--- a/api/routes/api.php
+++ b/api/routes/api.php
@@ -130,9 +130,9 @@ Route::group(['middleware' => 'auth.multi'], function () {
Route::post('/portal', [\App\Http\Controllers\Settings\LicenseController::class, 'portal'])->name('portal');
});
- Route::prefix('/mcp')->name('mcp.')->middleware(['self-hosted'])->group(function () {
+ Route::prefix('/mcp')->name('mcp.')->group(function () {
Route::get('/', [McpSettingsController::class, 'show'])->name('show');
- Route::put('/', [McpSettingsController::class, 'update'])->name('update');
+ Route::put('/', [McpSettingsController::class, 'update'])->middleware(['self-hosted'])->name('update');
});
Route::prefix('/two-factor')->name('two-factor.')->group(function () {
diff --git a/api/tests/Feature/Mcp/McpSettingsTest.php b/api/tests/Feature/Mcp/McpSettingsTest.php
index 31768c667..1ae534017 100644
--- a/api/tests/Feature/Mcp/McpSettingsTest.php
+++ b/api/tests/Feature/Mcp/McpSettingsTest.php
@@ -37,6 +37,7 @@ it('returns connection details generated for the self-hosted instance', function
$response->assertSuccessful()
->assertJson([
+ 'self_hosted' => true,
'enabled' => false,
'available' => false,
'configured_value' => null,
@@ -164,12 +165,32 @@ it('requires a workspace admin to read or update instance MCP settings', functio
$this->json($method, '/settings/mcp', ['enabled' => true])->assertForbidden();
})->with(['GET', 'PUT']);
-it('hides MCP settings from cloud instances', function (string $method) {
+it('returns the hosted MCP connection guide to cloud users', function () {
config()->set('app.self_hosted', false);
+ config()->set('app.url', 'https://api.opnform.com');
+ config()->set('app.front_url', 'https://opnform.com');
+ $member = $this->createUser();
+ $this->workspace->users()->attach($member, ['role' => 'user']);
+ $this->actingAs($member, 'api');
- $this->json($method, '/settings/mcp', ['enabled' => true])
+ $this->getJson('/settings/mcp')
+ ->assertSuccessful()
+ ->assertJson([
+ 'self_hosted' => false,
+ 'enabled' => true,
+ 'available' => true,
+ 'ready' => true,
+ 'server_url' => 'https://api.opnform.com/mcp',
+ 'settings_url' => 'https://opnform.com/?user-settings=mcp',
+ ]);
+});
+
+it('does not allow cloud users to update the hosted MCP availability', function () {
+ config()->set('app.self_hosted', false);
+
+ $this->putJson('/settings/mcp', ['enabled' => false])
->assertNotFound()
->assertJson([
'error' => 'Only available on self-hosted instances.',
]);
-})->with(['GET', 'PUT']);
+});
diff --git a/client/components/users/settings/Mcp.vue b/client/components/users/settings/Mcp.vue
index d2768807a..f90f5c29a 100644
--- a/client/components/users/settings/Mcp.vue
+++ b/client/components/users/settings/Mcp.vue
@@ -11,7 +11,7 @@
MCP & AI agents
</h3>
<p class="text-sm text-neutral-500">
- Connect AI assistants directly to this OpnForm instance.
+ {{ pageDescription }}
</p>
</div>
</div>
@@ -72,7 +72,10 @@
</div>
</div>
- <div class="flex shrink-0 items-center gap-3 rounded-lg border border-neutral-200 bg-neutral-50 px-3 py-2">
+ <div
+ v-if="isSelfHosted"
+ class="flex shrink-0 items-center gap-3 rounded-lg border border-neutral-200 bg-neutral-50 px-3 py-2"
+ >
<span class="text-sm font-medium text-neutral-700">Enable MCP</span>
<USwitch
:model-value="settings.enabled"
@@ -279,34 +282,47 @@ const sharedSettingsUrl = computed(() => {
})
const isMcpAvailable = computed(() => settings.value?.available === true)
+const isSelfHosted = computed(() => settings.value?.self_hosted !== false)
+
+const pageDescription = computed(() => {
+ return isSelfHosted.value
+ ? 'Connect AI assistants directly to this OpnForm instance.'
+ : 'Connect AI assistants to OpnForm Cloud.'
+})
const statusTitle = computed(() => {
+ if (!isSelfHosted.value) return 'OpnForm MCP is ready'
if (!settings.value?.ready) return 'Server setup required'
return isMcpAvailable.value ? 'MCP is available' : 'Ready to connect'
})
const statusDescription = computed(() => {
+ if (!isSelfHosted.value) return 'Create private drafts without signing in, or connect your account to manage forms and read submissions.'
if (!settings.value?.ready) return 'Resolve the prerequisites below before exposing the MCP endpoint.'
if (isMcpAvailable.value) return 'Connected AI assistants can create and manage forms and read submissions using your OpnForm account.'
return 'OAuth is ready. Enable MCP when you want this instance to accept agent connections.'
})
const statusIcon = computed(() => {
+ if (!isSelfHosted.value) return 'i-heroicons-check'
if (!settings.value?.ready) return 'i-heroicons-exclamation-triangle'
return settings.value?.enabled ? 'i-heroicons-check' : 'i-heroicons-pause'
})
const statusIconClasses = computed(() => {
+ if (!isSelfHosted.value) return 'bg-emerald-100 text-emerald-600'
if (!settings.value?.ready) return 'bg-red-100 text-red-600'
return settings.value?.enabled ? 'bg-emerald-100 text-emerald-600' : 'bg-neutral-100 text-neutral-500'
})
const statusBadgeLabel = computed(() => {
+ if (!isSelfHosted.value) return 'Cloud'
if (!settings.value?.ready && settings.value?.enabled) return 'Unavailable'
return settings.value?.enabled ? 'Enabled' : 'Disabled'
})
const statusBadgeColor = computed(() => {
+ if (!isSelfHosted.value) return 'success'
if (!settings.value?.ready && settings.value?.enabled) return 'error'
return settings.value?.enabled ? 'success' : 'neutral'
})
diff --git a/client/components/users/settings/Modal.vue b/client/components/users/settings/Modal.vue
index 29f76eaf1..569c8192d 100644
--- a/client/components/users/settings/Modal.vue
+++ b/client/components/users/settings/Modal.vue
@@ -49,7 +49,7 @@
</SettingsModalPage>
<SettingsModalPage
- v-if="canManageInstanceSettings"
+ v-if="canViewMcpSettings"
id="mcp"
label="MCP & AI agents"
icon="i-heroicons-cpu-chip"
@@ -86,6 +86,7 @@ const { current: workspace, workspaces } = useCurrentWorkspace()
const { data: user } = useAuth().user()
const isSelfHosted = computed(() => useFeatureFlag('self_hosted'))
const canManageInstanceSettings = computed(() => isSelfHosted.value && !!workspaces.value?.some(candidate => candidate.is_admin))
+const canViewMcpSettings = computed(() => !isSelfHosted.value || canManageInstanceSettings.value)
const canManageLicense = canManageInstanceSettings
// Modal state is now derived from the presence of an active tab
diff --git a/client/test/nuxt/mcp-settings.spec.ts b/client/test/nuxt/mcp-settings.spec.ts
index 1d03e3af2..22ba04999 100644
--- a/client/test/nuxt/mcp-settings.spec.ts
+++ b/client/test/nuxt/mcp-settings.spec.ts
@@ -25,6 +25,7 @@ vi.mock('~/composables/useAlert.js', () => ({
}))
const readySettings = {
+ self_hosted: true,
enabled: false,
available: false,
configured_value: null,
@@ -185,4 +186,25 @@ describe('MCP self-hosted settings', () => {
expect(mocks.status).toHaveBeenCalledTimes(2)
expect(wrapper.text()).toContain('Ready to connect')
})
+
+ it('shows cloud connection instructions without an availability switch', async () => {
+ mocks.status.mockResolvedValue({
+ ...readySettings,
+ self_hosted: false,
+ enabled: true,
+ available: true,
+ server_url: 'https://api.opnform.com/mcp',
+ settings_url: 'https://opnform.com/?user-settings=mcp',
+ })
+
+ const wrapper = mountSettings()
+ await flushPromises()
+
+ expect(wrapper.text()).toContain('OpnForm MCP is ready')
+ expect(wrapper.text()).toContain('Create private drafts without signing in')
+ expect(wrapper.text()).toContain('Cloud')
+ expect(wrapper.find('[data-testid="mcp-enabled-switch"]').exists()).toBe(false)
+ expect(wrapper.get('[data-testid="server-url"]').text()).toBe('https://api.opnform.com/mcp')
+ expect(wrapper.find('[data-testid="mcp-snippet-settings"]').exists()).toBe(true)
+ })
})
diff --git a/client/test/nuxt/user-settings-modal.spec.ts b/client/test/nuxt/user-settings-modal.spec.ts
index 792ca3927..19fe9c5a8 100644
--- a/client/test/nuxt/user-settings-modal.spec.ts
+++ b/client/test/nuxt/user-settings-modal.spec.ts
@@ -104,4 +104,14 @@ describe('User settings instance administration', () => {
expect(wrapper.find('[data-page-id="license"]').exists()).toBe(false)
expect(wrapper.find('[data-page-id="mcp"]').exists()).toBe(false)
})
+
+ it('shows the MCP guide to every cloud user', () => {
+ mocks.isSelfHosted = false
+ mocks.workspaces = [mocks.currentWorkspace]
+
+ const wrapper = mountModal()
+
+ expect(wrapper.find('[data-page-id="license"]').exists()).toBe(false)
+ expect(wrapper.find('[data-page-id="mcp"]').exists()).toBe(true)
+ })
})
diff --git a/docs/images/mcp/client-configuration.png b/docs/images/mcp/client-configuration.png
new file mode 100644
index 000000000..63844393e
Binary files /dev/null and b/docs/images/mcp/client-configuration.png differ
diff --git a/docs/images/mcp/connection-endpoint.png b/docs/images/mcp/connection-endpoint.png
new file mode 100644
index 000000000..b294b37c1
Binary files /dev/null and b/docs/images/mcp/connection-endpoint.png differ
diff --git a/docs/images/mcp/enable-mcp.png b/docs/images/mcp/enable-mcp.png
new file mode 100644
index 000000000..fcb2240ea
Binary files /dev/null and b/docs/images/mcp/enable-mcp.png differ
diff --git a/docs/integrations/mcp.mdx b/docs/integrations/mcp.mdx
index d147e98e4..81777eb8f 100644
--- a/docs/integrations/mcp.mdx
+++ b/docs/integrations/mcp.mdx
@@ -1,19 +1,69 @@
---
-title: "Connect AI assistants with MCP"
-description: "Enable the OpnForm MCP server on a self-hosted instance and connect Cursor, Claude Code, ChatGPT, Codex, or another MCP client."
+title: "Use OpnForm with AI assistants through MCP"
+description: "Connect ChatGPT, Cursor, Claude Code, Codex, or another MCP client to OpnForm Cloud or a self-hosted OpnForm instance."
---
-OpnForm includes a remote [Model Context Protocol](https://modelcontextprotocol.io) server. It lets AI assistants create and manage forms, then search, analyze, and export submissions using the permissions of the connected OpnForm account.
+OpnForm includes a remote [Model Context Protocol](https://modelcontextprotocol.io) server. It lets AI assistants build forms from a conversation, show you a private preview, manage forms, and help you work with submissions.
-Your MCP endpoint uses your API origin:
+The setup depends on whether you use **OpnForm Cloud** or a **self-hosted OpnForm instance**.
+
+## Choose your OpnForm setup
+
+<Tabs>
+<Tab title="OpnForm Cloud">
+The hosted MCP server is already enabled at:
+
+```text
+https://api.opnform.com/mcp
+```
+
+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.
+</Tab>
+
+<Tab title="Self-hosted OpnForm">
+Your MCP endpoint uses the API origin of your instance:
```text
https://forms.example.com/mcp
```
-MCP is disabled by default. A workspace administrator must verify the instance configuration and enable it from OpnForm settings.
+MCP is disabled by default. An administrator must configure OAuth and enable MCP from **Settings → MCP & AI agents**. Self-hosted MCP connections always require an OpnForm account; guest draft creation is not exposed.
+</Tab>
+</Tabs>
+
+## Create a form with OpnForm Cloud
+
+You can ask a compatible AI assistant to create a form before connecting your OpnForm account.
+
+<Steps>
+<Step title="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.
+</Step>
-## Prerequisites
+<Step title="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.
+</Step>
+
+<Step title="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.
+</Step>
+
+<Step title="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.
+</Step>
+</Steps>
+
+<Note>
+Guest draft links are private bearer links. Do not share them publicly. If a preview expires, ask the assistant to generate a fresh preview.
+</Note>
+
+## Enable MCP on a self-hosted instance
+
+### Prerequisites
Before you enable MCP, verify that your instance has:
@@ -26,11 +76,9 @@ Before you enable MCP, verify that your instance has:
Do not expose a production MCP endpoint over plain HTTP. Localhost URLs are suitable only for local client testing.
</Warning>
-## Enable MCP
-
<Steps>
<Step title="Open the MCP settings">
-Sign in as a workspace administrator, then open **Settings → MCP & AI agents**.
+Sign in as an administrator, then open **Settings → MCP & AI agents**.
</Step>
<Step title="Resolve the setup checks">
@@ -38,7 +86,11 @@ OpnForm verifies the public URLs and Passport keys. If a requirement is missing,
</Step>
<Step title="Enable the server">
-Turn on **Enable MCP**. The connection URL and client-specific setup instructions appear immediately.
+Turn on **Enable MCP**.
+
+<Frame>
+ <img src="/images/mcp/enable-mcp.png" alt="Enable MCP in the settings of a self-hosted OpnForm instance" />
+</Frame>
<Check>
The status changes to **MCP is available** and the page displays your `/mcp` endpoint.
@@ -53,9 +105,21 @@ MCP_ENABLED=false
MCP_OBSERVABILITY_ENABLED=true
```
+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
-The settings page generates the correct command or configuration for your instance. Select a client, then copy the displayed value.
+For OpnForm Cloud, use `https://api.opnform.com/mcp`. For a self-hosted instance, copy the endpoint displayed in **Settings → MCP & AI agents**.
+
+<Frame>
+ <img src="/images/mcp/connection-endpoint.png" alt="Copy the MCP server URL from OpnForm settings" />
+</Frame>
+
+The settings page generates the correct command or configuration for your client. Select your client, then copy the displayed value.
+
+<Frame>
+ <img src="/images/mcp/client-configuration.png" alt="Select an AI client and copy its generated MCP configuration" />
+</Frame>
<Tabs>
<Tab title="Cursor">
@@ -63,15 +127,17 @@ Use **Install in Cursor** for one-click setup, or copy the generated `mcpServers
</Tab>
<Tab title="Claude Code">
-Run the generated command:
+For OpnForm Cloud, run:
```bash
-claude mcp add --transport http opnform https://forms.example.com/mcp
+claude mcp add --transport http opnform https://api.opnform.com/mcp
```
+
+Replace the URL with your own `/mcp` endpoint when you use a self-hosted instance.
</Tab>
<Tab title="ChatGPT">
-On a plan that supports custom MCP apps, enable [ChatGPT developer mode](https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-connectors-in-chatgpt), create an app, and paste your server URL. Select OAuth when prompted. ChatGPT discovers the authorization metadata from the endpoint.
+On a plan that supports custom MCP apps, enable [ChatGPT developer mode](https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-connectors-in-chatgpt), create an app, and paste the server URL. Select OAuth when prompted. ChatGPT discovers the authorization metadata from the endpoint.
<Note>
ChatGPT plan and workspace controls determine whether custom apps and write actions are available. An administrator may need to enable developer mode before you can add the server.
@@ -79,22 +145,24 @@ ChatGPT plan and workspace controls determine whether custom apps and write acti
</Tab>
<Tab title="Codex">
-Run the generated command:
+For OpnForm Cloud, run:
```bash
-codex mcp add opnform --url https://forms.example.com/mcp
+codex mcp add opnform --url https://api.opnform.com/mcp
```
+
+Replace the URL with your own `/mcp` endpoint when you use a self-hosted instance.
</Tab>
<Tab title="Other clients">
-Use the generated streamable HTTP configuration in any OAuth-capable MCP client:
+Use a streamable HTTP configuration in any OAuth-capable MCP client:
```json
{
"mcpServers": {
"opnform": {
"type": "http",
- "url": "https://forms.example.com/mcp"
+ "url": "https://api.opnform.com/mcp"
}
}
}
@@ -102,44 +170,47 @@ Use the generated streamable HTTP configuration in any OAuth-capable MCP client:
</Tab>
</Tabs>
-Open the advanced section on the settings page if you need the portable [Agent Plugins](https://agent-plugins.org) configuration.
+Open **Portable Agent Plugin configuration** in OpnForm settings if your client supports [Agent Plugins](https://agent-plugins.org).
To share instructions for a particular client, include the selected client in the settings URL:
```text
-https://forms.example.com/?user-settings=mcp&agent=cursor
+https://opnform.com/?user-settings=mcp&agent=cursor
```
-Supported values are `cursor`, `claude_code`, `chatgpt`, `codex`, and `other`.
+On self-hosted instances, replace `https://opnform.com` with your frontend URL. Supported `agent` values are `cursor`, `claude_code`, `chatgpt`, `codex`, and `other`.
-## Authenticate the connection
+## Authenticate your OpnForm account
-Form, workspace, and submission tools always require 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.
+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.
-The schema resources, field catalog, and `validate_form_definition` tool remain available before authentication because they do not read or store instance data.
+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.
<Note>
-After authenticating a local Codex connection, start a new conversation with OpnForm selected so the MCP client loads the stored credential.
+After authenticating a Codex connection, start a new conversation with OpnForm selected so the MCP client loads the stored credential.
</Note>
A connected user can revoke the current access and refresh tokens by sending an authenticated `DELETE` request to `/mcp-oauth/session`.
## Available capabilities
-After OAuth, an assistant can:
-
-- list accessible workspaces;
-- list and inspect forms;
-- create a form as an unpublished draft in a writable workspace;
-- return an `edit_url` so you can review the draft in the OpnForm editor;
-- update, publish, and move forms to the trash;
-- list, search, filter, inspect, summarize, and export submissions.
+| Capability | OpnForm Cloud | Self-hosted |
+| --- | --- | --- |
+| Create and preview a guest draft | Available without an account | Not available |
+| Validate a form definition | Available before authentication | Available before authentication |
+| List accessible workspaces | OAuth required | OAuth required |
+| List, inspect, create, and update forms | OAuth required | OAuth required |
+| Publish or move a form to trash | OAuth and explicit confirmation | OAuth and explicit confirmation |
+| Search, analyze, and export submissions | OAuth required, read-only | OAuth required, read-only |
+| Enable or disable the MCP server | Managed by OpnForm | Self-hosted administrator |
-Workspace administration and submission mutations are unavailable. Publishing and moving a form to the trash require explicit confirmation. MCP does not expose permanent form deletion, form restoration, submission deletion, or submission restoration.
+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.
-## OAuth and callback configuration
+## Self-hosted OAuth configuration
+
+The following settings apply only to self-hosted instances.
Configure the callback destinations accepted by your instance:
@@ -153,7 +224,7 @@ 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.
-## Rate limits
+## Self-hosted rate limits
The default limits are permissive for normal agent use:
@@ -167,7 +238,7 @@ The default limits are permissive for normal agent use:
## Privacy and observability
-When `MCP_OBSERVABILITY_ENABLED=true`, OpnForm records only the MCP method, tool name, authentication mode, outcome, HTTP status, and duration.
+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.
@@ -177,19 +248,27 @@ Set `MCP_OBSERVABILITY_ENABLED=false` to disable MCP usage events and their stru
<AccordionGroup>
<Accordion title="The Enable MCP switch is unavailable">
-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.
+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.
</Accordion>
<Accordion title="The client connects but account tools require authentication">
-Enabling MCP only exposes the server. Complete the OAuth flow from the MCP client. For local Codex testing, start a new conversation after authentication.
+Complete the OAuth flow from the MCP client. Guest drafts on OpnForm Cloud do not authenticate your account automatically.
+</Accordion>
+
+<Accordion title="OAuth succeeds but the conversation still appears unauthenticated">
+Start a new conversation after authentication. Some clients retain the tool and authentication state that existed when the conversation started.
+</Accordion>
+
+<Accordion title="A guest preview is unavailable">
+Ask the assistant to create a fresh preview. Preview links are private and expire automatically.
</Accordion>
-<Accordion title="OAuth returns to the wrong host">
+<Accordion title="OAuth returns to the wrong host on a self-hosted instance">
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.
</Accordion>
-<Accordion title="The client cannot reach the MCP server">
-Confirm that `https://forms.example.com/mcp` 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.
+<Accordion title="The client cannot reach a self-hosted MCP server">
+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.
</Accordion>
</AccordionGroup>