formbase

Formstep MCP server

The hosted MCP server for Formstep. Request information without the back-and-forth.

Your agent sends a request to one person, the recipient: a form in your brand and their language, prefilled with what you know, so they only confirm or correct it. They upload files, sign, book or pay on the same page, without an account. The answers come back under your field keys, with your external ID and, when the form has a decision question, an approve, decline or changes outcome. Your agent reads them with request_get, or Formstep calls your callback URL the moment the recipient submits.

The server lives at:

https://api.formstep.io/api/mcp

This repository holds documentation, example configs and a Grok Build plugin manifest. There is nothing to install or run.

• What an agent can do
• Connect your AI tool
• Try it
• Tools
• Limits
• Protocol details
• Docs
• Report a problem

What an agent can do

• Send requests. Ask one named person for information, with answers filled in or locked, and read what they answered. Use a form you published, or have the agent build the form in the same call.
• Build forms. Create a form and add, edit or remove its questions, pages and logic.
• Publish and share. Publish a form, create share links, translate it, and set its theme and settings.
• Read results. List a form's submissions and read its analytics.

Most AI tools sign in to Formstep with OAuth: you paste the URL, sign in to Formstep in the browser, and pick a workspace. Scripts and headless agents send an API token instead.

Connect your AI tool

Leave any client ID, secret or token field empty. The AI tool finds the Formstep sign-in page from the server and registers itself.

Claude Code

claude mcp add --transport http formstep https://api.formstep.io/api/mcp

Then type /mcp in Claude Code to sign in.

To share the server with everyone who works on a project, commit a .mcp.json to the project instead:

{

"mcpServers": { "formstep": { "type": "http", "url": "https://api.formstep.io/api/mcp" } } }

Claude desktop and claude.ai

Open Customize › Connectors › + › Add custom connector and paste the URL. A connector added on claude.ai also works in the desktop and mobile apps.

On Team and Enterprise, an owner adds the connector first under Organization settings › Connectors. Members then click Connect on it. On Free you can add one custom connector. Claude's own guide: Get started with custom connectors.

ChatGPT

Turn on developer mode under Settings › Apps › Advanced settings. Then open Settings › Apps › Create, paste the URL, choose OAuth, click Scan Tools, sign in to Formstep, and click Create.

Developer mode works on the web only. On Pro, ChatGPT can only read: tools that change something, such as sending a request or editing a form, need Business, Enterprise or Edu. On Business, only admins and owners can use developer mode. OpenAI's own guide: Developer mode and MCP apps in ChatGPT.

Cursor

Add this to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project:

{

"mcpServers": { "formstep": { "url": "https://api.formstep.io/api/mcp" } } }

Cline

Cline connects with an API token (see below for how to create one). Add this to Cline's cline_mcp_settings.json:

{

"mcpServers": { "formstep": { "type": "streamableHttp", "url": "https://api.formstep.io/api/mcp", "headers": { "Authorization": "Bearer fs_YOUR_TOKEN" } } } }

Or ask Cline to install it: llms-install.md has the steps it follows.

Grok Build

This repository is also a Grok Build plugin: .grok-plugin/plugin.json, the .mcp.json server config and one skill, formstep-requests. The plugin runs nothing on your machine. It calls one network endpoint, https://api.formstep.io/api/mcp, and signs in with Formstep OAuth, or with an API token you add as a header.

Other tools

Any tool that supports remote MCP servers with sign-in works the same way: look for where it adds a server by URL. The connect guide links each tool's own instructions.

Sign in and pick a workspace

The first time the agent uses Formstep, your AI tool opens a Formstep page in the browser. Sign in, pick the workspace, and click Authorize.

A connection reaches that one workspace only. To use another workspace, add Formstep a second time and pick the other one.

To check that it works, ask:

List my Formstep forms and whether each one is published.

To remove the connection, open OAuth and API Keys in the Formstep workspace sidebar. Under Connected apps, click the trash icon next to the connection and confirm with Disconnect.

Scripts and headless agents: use an API token

Anything that cannot open a browser, such as a script, a CI job or a headless agent, sends an API token as a header instead.

1. Open OAuth and API Keys in your workspace sidebar and click Create token (API tokens).
2. Copy the token. It starts with fs_.
3. Send it as an Authorization: Bearer header.

A token reaches exactly one workspace, like an OAuth connection. It expires 30 days after you create it and cannot be extended, so plan to replace it. Keep it out of git.

Claude Code, from the command line:

claude mcp add --transport http formstep https://api.formstep.io/api/mcp \

--header "Authorization: Bearer fs_YOUR_TOKEN"

Or in a config file. This is .mcp.json for Claude Code; Cursor takes the same headers object in its mcp.json:

{

"mcpServers": { "formstep": { "type": "http", "url": "https://api.formstep.io/api/mcp", "headers": { "Authorization": "Bearer fs_YOUR_TOKEN" } } } }

Other tools take the same URL and header. See their documentation for where.

Try it

Send a request to one person. Use the name of one of your published forms:

Send a Formstep request with the "Supplier onboarding" form to Ada Lovelace (ada@acme.example). Fill in the company name "Analytical Engines Ltd" and lock it so it cannot be changed. Use supplier-2041 as the external ID. Don't send the invitation email; give me the link and I will send it myself.

The agent reads the form's field keys with fields_list, creates the request with request_create, and gives you the request link.

No form yet? The agent can build one in the same call:

Ask Ada Lovelace (ada@acme.example) for her last three payslips and a 40 EUR processing fee, and let her book a 15 minute call. Use our logo at https://acme.example/logo.png and a dark blue cover. Give me the link.

The agent checks the workspace's Stripe and Cal.com connections with workspaceConnection_list, then calls request_create with a form object instead of a formId: a name, the blocks, and the logo and cover you gave it. Formstep builds the form, publishes it and creates the request in one step, and returns the field keys the answers will come back under. The same definition again reuses that form, so a hundred requests make one form.

If the form has Send reminders on, Formstep still emails the recipient its scheduled reminders. To prevent that, also say _no reminders_.

The agent is not told when the recipient submits, so ask it later:

Has the Formstep request supplier-2041 been answered? Show me the answers.

The agent finds the request by its external ID with request_list, then reads it with request_get. Once the request is completed, the answers come back keyed by field key.

Step by step: Send a request with an AI agent, Create a form and a request in one call and Build a form with an AI agent.

Tools

Every tool is on tools/list with its full input schema as soon as an AI tool connects. The MCP server reference describes them in detail.

Requests

Ask one named person for information and read the result.

• fields_list: list the field keys a request can address on a published form. Call it before request_create with a formId.
• request_create: assign a form to one recipient, with prefill, locked fields, context, delivery, expiry and an optional callback. Pass formId for a published form, or form to build the form in the same call (see below).
• request_get: read one request by its ID. Returns the status, the timeline and, once completed, the answers keyed by field key.
• request_list: list requests for a form or a workspace, filtered by status, outcome or your own external ID.
• request_cancel: withdraw a pending request.
• request_remind: send the recipient a reminder email now.
• request_replayCallback: send a callback again when it never reached your endpoint.
• document_create: reserve an upload for a file a request hands to its recipient. One upload can serve any number of requests.
• workspaceConnection_list: the Stripe and Cal.com accounts the workspace has connected, and the connectUrl to connect a missing one. Read it before building a form with a payment or a booking.
• scheduler_listEventTypes: the Cal.com event types a booking block can name, and whether each one can be booked from a form.
• paymentConnection_setDefault: choose the Stripe account payments charge through by default. Workspace owner only.

Forms built inside a request

request_create takes form in place of formId. Formstep builds an ordinary form from it, publishes it and creates the request in one step: both exist or neither does. The agent needs no editor tool and no fields_list call.

{

"form": { "name": "Documents and fee for your mortgage application", "logo": { "type": "image", "url": "https://acme.example/logo.png" }, "cover": { "type": "color", "color": "#0f4c81" }, "blocks": [ { "type": "paragraph", "content": "Hi {{first_name}}, upload the documents and pay the fee." }, { "type": "hiddenField", "key": "first_name" }, { "type": "file", "key": "payslips", "title": "Your last three payslips", "maxFiles": 3 }, { "type": "payment", "key": "fee", "title": "Processing fee", "amount": 40, "currency": "EUR" }, { "type": "scheduleAppointment", "key": "call", "title": "Pick a time", "eventType": "15 min call" } ] }, "recipient": { "email": "ada@example.com", "name": "Ada" }, "context": { "first_name": "Ada" } }

• `form` takes name and blocks (1 to 200, in form order), and optionally language, the brand (logo, cover, emoji), theme (a preset id per color mode), settings and translations (every string of the form per extra language). Formstep fetches each image URL once and keeps its own copy; it must be a public JPEG, PNG or WebP.
• Blocks take the parameters of the matching editor_insert* tool, without formId and after, plus a key. Every block type is there: questions, documents, payment, scheduleAp