Connecting AI Agents

Formspace provides a remote Model Context Protocol (MCP) server for supported AI agents. A connected agent can work with the Formspaces available to your Formspace account without requiring a separate API key.

Supported clients include ChatGPT, Claude, and Microsoft 365 Copilot. Use the Formspace connector in the client’s marketplace when available. Clients that support a custom remote MCP connection can use:

https://app.formspace.com/mcp

The connection redirects to Formspace for sign-in and consent. Formspace never asks you to paste your Formspace password into the AI client.

Discovery and authentication

The API catalog and website AI index link to the production MCP endpoint and this guide. The catalog uses the RFC 9727 Linkset format; it is not an API key or an authorization grant.

MCP clients connect using Streamable HTTP and discover OAuth configuration from the server’s WWW-Authenticate challenge and public metadata:

• Protected resource metadata: https://app.formspace.com/.well-known/oauth-protected-resource/mcp
• OAuth issuer: https://app.formspace.com/api/auth
• Authorization server metadata: https://app.formspace.com/.well-known/oauth-authorization-server/api/auth
• OpenID Connect metadata: https://app.formspace.com/api/auth/.well-known/openid-configuration

Use the client’s OAuth authorization-code flow with PKCE (S256) to sign in and consent. Supported platform clients use CIMD or a provisioned OAuth client; arbitrary dynamic client registration is not enabled. Reading public discovery metadata does not give an agent access to any forms or responses. The server checks the current grant and your organization permissions when tools run.

Discovering the endpoint does not install a connector or grant consent. Marketplace availability depends on each platform’s listing and review process.

Permissions

The authorization screen lists the access requested by the client:

• Read your Formspace data allows the agent to search public documentation, list Formspaces and forms, inspect schemas, read responses, analyze selected answer fields, list form invitations, and inspect workflow runs.
• Manage forms and invitations allows the agent to create and publish forms, upload form assets, update schemas, themes and settings, and create, resend or revoke form invitations. Publishing and invitation actions require explicit confirmation.

Existing connections that were authorized with read-only access must be reconnected before they can make changes. Connections with write access can use the new management tools without additional scopes.

Documentation lookup

Connected agents can use search_docs for targeted questions about schema properties, expressions, themes, settings, and Formspace capabilities. It returns short documentation excerpts and source links, not a generated answer. No selected Formspace or additional OAuth permission is required beyond the connection’s read access.

Queries should contain the feature or property being researched, not customer answers or secrets. For example: dropdown choicesByUrl or visibleIf expression. If an excerpt is shortened, the result marks it as truncated; the agent can follow the source link if its host supports browsing, or refine the query.

Documentation describes the whole product, including features only available in the dashboard. The connector’s available tools determine which actions an agent can perform; finding a feature in the docs does not grant access or add a tool. The public docs remain available independently of the connector.

Building forms

A connected agent can:

• Create a form draft from a complete, validated form schema.
• Read an existing draft before making changes.
• Apply a small targeted patch or replace the complete schema.
• Upload files into a form’s owned storage and use the returned asset URLs in its schema or theme.
• Update the form theme.
• Change access, closing, progress saving, duplicate-response, notification, branding, custom-path and PDF settings with update_form_settings.
• Publish the current draft and return its verified public URL.

Creating or editing a form does not publish it automatically. Publishing is a separate operation and the agent must send an explicit publish confirmation. Repeating a publish request when the draft has not changed does not create another version.

For schema patches, complete-schema replacements, theme updates, and publishing, Formspace checks that the draft has not changed since the agent read it. If a person or another agent edited the form in the meantime, the operation is rejected so the agent can reload and review the current draft before continuing.

Settings updates also require the revision from get_form. Unlike schema and theme changes, settings take effect immediately, including on published forms. Nested settings objects replace their previous value, so the agent should read and preserve settings that you did not ask it to change. The same plan restrictions and safety checks apply as in the dashboard.

Invalid form schemas are rejected before saving. The agent receives the actual validation messages, including expression errors, so it can correct the draft and try again.

To add images or other files, create or select the form first, then ask the agent to upload each file with upload_form_asset. Each call copies one file into the selected form and applies the same per-file plan limit as the dashboard. The agent must use the returned assetUrl exactly in a subsequent schema or theme update; uploading alone does not edit or publish the form.

Transfers have a two-minute deadline covering download redirects and storage. MCP uploads are throttled to 10 attempts per minute per Formspace at each Cloudflare location; this is an abuse guard, not a globally exact quota. A rate-limit error asks the agent to wait one minute. A transfer error may require a fresh temporary download URL. Repeating a successful upload creates another stored copy.

File transfer depends on the AI host. ChatGPT can pass a selected attachment through its MCP file parameter support. Other hosts, such as Microsoft 365 Copilot, can use the same tool with a temporary download URL from the host or a direct public HTTPS link to the file itself. Links to a web page that displays the file, such as an image host’s sharing page, are rejected. Formspace validates redirects and accepts only public HTTPS locations, then streams the file into form-owned storage. Repeating a successful call creates another stored copy.

Tip

Ask the agent to create or edit the draft first, summarize what it changed, and publish only after you have reviewed the result.

Previewing forms in chat

Ask the agent to call preview_form after saving a draft. Compatible MCP Apps hosts display an interactive preview with page navigation, validation and conditional questions. The preview sizes itself to the current form page without an internal scrollbar, subject to the host’s own display limits. Open in Formspace opens the form builder’s Preview tab; other hosts can use the same returned dashboard link. Previewing requires only the existing read permission and does not publish the form.

Answers exist only in the preview’s temporary memory. They are not saved as responses or sent back to the agent. Submissions, uploads, signatures, completion redirects, triggers and remote choice lists are disabled. External images, embedded content and unsupported private assets are hidden. This is an author preview, not a test of respondent sign-in or invitation access.

Private raster images belonging to the form or its Formspace use GET-only signed links that expire after five minutes. Refresh checks the current OAuth grant, organisation membership and form access again, loads the latest saved draft, renews image links and resets answers. The widget does not receive OAuth tokens or dashboard cookies.

Revoking a connection prevents subsequent authorised reads, but cannot recall data already delivered to the chat. An already-issued image link remains usable until expiry, and downloaded images may remain cached. Treat the preview as shared form data, not a continuously authorised live view.

The regular dashboard build produces both the dashboard and preview entry points. For local widget development through MCP, run bun run build --watch from apps/dashboard/web alongside the normal dev stack so the Worker can serve the built preview assets. The widget uses the deployment’s existing DASHBOARD_ORIGIN; no separate widget-domain configuration is needed. Publishers configure OPENAI_APPS_CHALLENGE for ChatGPT’s public domain-verification endpoint before submission. Neither setting changes OAuth permissions. Test the deployed resource/CSP in each supported host before publishing a listing.

Managing invitations

• list_form_invites returns recipients, expiry, prefill data, email timestamps and submitted-response counts. Set includePrefill=false when the prefill data is unnecessary or too large.
• create_form_invites creates and emails up to 20 invitations after explicit confirmation, subject to plan and rate limits.
• resend_form_invite sends another email after confirmation and the five-minute cooldown.
• revoke_form_invite invalidates an invitation link without deleting submitted responses. It does not disable any separate public form URL.

Batch invitation creation can partially succeed. The agent receives successes and failures separately and should inspect existing invitations before retrying failures, since an invitation may have been saved before email delivery failed. Invitation IDs grant access to the form; treat them as sensitive.

Analyzing responses

list_responses returns response metadata and answers together, replacing the separate list_response_answers tool. It defaults to submitted responses and supports one form or an entire Formspace, submission-date filters, and optional question names in fields. Use get_form to find exact question names and request only the answers needed for the analysis. Set includeAnswers=false for a lightweight response index.

Results use cursor pagination: pass nextCursor with the same filters until it is null. Pages are ordered by creation time and ID. Results are live rather than a frozen snapshot, so changes during a long analysis can affect its totals. Individual response details remain available through get_response.

list_formspaces, list_forms, and list_form_invites also use cursor pagination, ordered by ID. These tools and list_responses default to 25 items and accept at most 100; list_responses reports the matching total only on the first page. Pages may return fewer items to keep their JSON item data within 128 KiB; always follow nextCursor rather than assuming a short page is the last page. If a single item is too large, the tool returns an actionable error instead of silently truncating it. For responses, select fewer fields or use includeAnswers=false; for invitations, use includePrefill=false. Other oversized items can be inspected in the dashboard. Workflow-run lists retain numbered pages and return an error asking for a smaller page if the JSON result exceeds 128 KiB.

Respondent email is excluded unless includeIdentity=true. Answers can themselves contain personal information; selecting only relevant fields minimizes what is shared. Omitting fields returns all answers.

Current limitations

The MCP connection does not currently edit, delete, or export responses.

Use the Formspace dashboard for these operations.

Reviewing and revoking access

Open My Profile → Security → Authorized Apps to review connected applications. Revoking an application removes its Formspace access and invalidates its access and refresh tokens. Reconnect the application if you want to use it again later.

What’s next?

• Creating a Form — Understand form fields, schemas, themes, and draft history.
• Publishing & Sharing — Configure access and share a published form.
• Managing Responses — Review, filter, edit, and export responses in the dashboard.