Superforms

Superforms developers

Superforms MCP documentation

Discover and connect the Superforms MCP server for agent-native human-input workflows.

Endpoints

  • https://superforms.co/mcp/account — authenticated coding-agent endpoint.
  • https://superforms.co/mcp/app — authenticated native plugin endpoint; MCP 2026-07-28 and legacy 2025-06-18 are supported.
  • https://superforms.co/mcp — anonymous and backward-compatible endpoint.
  • https://superforms.co/.well-known/mcp — public discovery card.

What agents can do

The native plugin exposes nine tools: create_form, list_forms, get_form, get_form_responses, wait_for_form_responses, get_completed_response, open_superforms, get_shared_form, and submit_form_response. create_form immediately publishes a public respondent link. Share that link manually; respondents do not need a creator account.

One form can collect multiple external responses. Multi-step organizational routing and automated escalation are not yet exposed as dedicated workflow primitives; agents can coordinate those patterns by creating and monitoring forms explicitly.

Answer from another agent conversation

Give the second conversation the public Superforms link. get_shared_form accepts formUrl (the canonical https://superforms.co/a/<slug> link or its slug) and returns public question IDs, text, settings, status and canSubmit. It does not reveal private creator context or other responses. Both respondent tools require the responding agent's own authenticated Superforms connection; that account can differ from the creator.

Only when the responding user authorizes submission, call submit_form_response with formUrl, requestId, respondentName and answers containing questionId and answerText. Send only the relevant answers the user authorized, not the conversation transcript or hidden instructions. The native tool requires exactly one answer for every scripted question before writing; missing, duplicate or unknown question IDs are rejected. It completes those answers without adaptive follow-ups. Ask for missing information or submit an honest unknown only if authorized; never invent an answer. The existing public respondent form design is unchanged.

Use a new requestId for each intended submission and retain it with the same respondent name and answers across retries. Request IDs contain 1–128 ASCII letters, numbers, underscores or hyphens. The server binds the response to the connected account, client, form and request ID. An exact retry returns its receipt without another response or event; changed answers conflict. The returned sessionId is not the retry key.

For an API-only respondent, read GET /api/public-ask/{slug} and POST authorized answers to /api/public-ask/{slug}/agent-response using session_id, respondent: { type: agent, name }, and answers: [{ question_id, answer_text }]. Retain the same session_id before the first request and across retries; omitting it creates a fresh response. This public respondent API needs no creator OAuth token and uses the same completion service. It preserves the legacy ability to complete a valid subset of answers, while native MCP requires every scripted question.

Agent submissions and human submissions create the same durable response.submitted completion event. The creator's successfully subscribed host can retrieve the response and continue previously authorized work. Submission success alone does not prove host continuation.

Native preview and completed-response events

open_superforms provides an optional MCP App in supported hosts: browse your forms, preview questions and the share link, open the respondent page, and inspect saved responses. It is a creator view, not an inline respondent form or a separate publishing step. The tools remain useful when the host cannot render it.

When events are enabled, server/discover advertises events and events/list exposes response.submitted. Subscribe for a formId to receive completed responses later. The host owns the callback and continuation instructions; confirm success before claiming monitoring. A webhook receipt alone does not prove the agent resumed the task.

OpenAI MCP Events and Claude Code channels are separate integrations. The existing Claude installation remains supported for tools; do not promise that it resumes a closed session or supports the OpenAI return loop.

Install

For the native ChatGPT or Codex plugin, connect the Superforms plugin to /mcp/app and complete OAuth. These direct coding-agent commands use the separate /mcp/account tools endpoint and do not by themselves install a plugin UI or event automation.

codex mcp add superforms --url https://superforms.co/mcp/account --oauth-resource https://superforms.co/mcp/account
claude mcp add --transport http --scope user superforms https://superforms.co/mcp/account
npx -y superforms-mcp

Discovery and authorization

The discovery card is public and cacheable. Account operations still require OAuth and the declared forms:read, responses:read, or forms:write scopes. Discovery does not weaken operation-level authentication.