API reference
MCP server for AI agents
Connect Claude, ChatGPT, Cursor, VS Code or any MCP client to your workspace and let the agent build and publish forms, connect websites, set up flows, work the inbox and, with admin access, run the team and billing. It signs in with a link, or with an API key, and does the same things as the dashboard and the API, with the same limits.
On this page you will learn
- The server address and how to connect your agent app with a link sign-in
- How to connect with an API key instead, for scripts and agents that run on their own
- What read only, full and admin access let the agent do
- All 61 tools, grouped by what they work on
- An example of an agent setting up a form from start to finish
- How the sign-in works and what the messages look like, for building your own client
- How to keep an agent from doing more than you want
Server address
https://formpik.com/api/mcpThe server speaks the Model Context Protocol over Streamable HTTP. Each request is a POST with one JSON-RPC message and a token, and every answer is plain JSON, so there are no sessions to keep open. It supports protocol versions 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05.
Connect your agent
- 01
Add the address to your agent app
Paste the setup for your app below. It is only the address: there is no key to copy. The same setup sits on the API keys page. - 02
Sign in and allow access
Your app opens Formpik in the browser. Sign in, pick the workspace and choose read only for an agent that only looks, full access for one that builds, publishes and changes things, or, as an owner or admin, admin access for one that also runs the team and billing, then click Allow access. - 03
Ask for what you want
Ask in plain words, such as "make a contact form for my Webflow site and send sales questions to Slack". The agent picks the tools and shows you what it did.
Add custom connector
Name: Formpik
Remote MCP server URL: https://formpik.com/api/mcp- Claude: Click Connect next to Formpik, sign in and allow access. It works in claude.ai, Claude Desktop and the Claude apps.
- ChatGPT: ChatGPT opens Formpik to sign in. Allow access and the tools show up in your chats.
- Claude Code: Then run /mcp in Claude Code, pick formpik and choose Authenticate. Your browser opens to sign in.
- Cursor: Cursor shows Needs login next to formpik in its MCP settings. Click it to sign in.
- VS Code: VS Code asks you to sign in the first time it starts the server. Allow it and pick your workspace.
Menu names in Claude and ChatGPT can change between versions. Any other app that supports MCP sign-in works the same way: point it at https://formpik.com/api/mcp and it finds the sign-in on its own.
With an API key instead
For scripts, scheduled jobs and agents that run without a person to sign in, create a key under API keys in the workspace menu, read only, full or admin access, and send it as Authorization: Bearer <key>. The key is shown once.
claude mcp add --transport http formpik https://formpik.com/api/mcp \
--header "Authorization: Bearer fp_live_your_api_key"- Replace
fp_live_your_api_keywith your key. VS Code asks for it the first time it connects and keeps it out of the file. - Any other client works the same way: point it at
https://formpik.com/api/mcpwith the headerAuthorization: Bearer <key>.
What the agent can do
The access you pick decides it, whether the agent signed in with a link or uses an API key. The server only offers the tools that access allows, so the agent never sees a tool it would be refused.
| Access | Tools | What the agent can do |
|---|---|---|
| Read only | 16 | Read the workspace, its numbers, forms, sources, flows, destinations and submissions, and open uploaded files. Destination addresses are masked. |
| Full access | 39 | Everything above, plus creating, changing, duplicating and deleting forms, sources, flows and destinations, publishing forms on their share link, drafting forms with AI, testing flows, sending test submissions, marking spam and running flows again. |
| Admin access | 61 | Everything above, plus the team (invitations, roles, removing members), API keys, connected apps, workspace settings and billing (plan changes, cancelling and the billing portal). |
An agent signed in with a link acts as the person who connected it, with the permissions of their role. A role that changes nothing can give it read access only, and webhook addresses and signing secrets stay with roles that have the Webhook secrets permission, as in the dashboard. If that person leaves the workspace, the agent stops working.
Only admin access reaches your team, roles, billing and API keys, so an agent with read or full access can never invite people, change a role, change your plan or make itself a new key. Admin access is offered to owners and admins only, an agent never gives anyone more than its person's role has, and the workspace can never be deleted or handed over by an agent. Each agent message counts as one API request toward the 120 a minute of its connection or key, and plan limits apply exactly as in the dashboard.
Tools
Every tool runs the API endpoint named next to it and takes the same names, in snake_case, so the API reference explains every property in detail. Tools marked Removes or Delivers are flagged to your client as tools that change things for real, so most clients ask you before running them.
Workspace
| Tool | What it does | Access | Kind |
|---|---|---|---|
get_workspace | The workspace this API key belongs to: its name, timezone, preferences, plan, every plan limit (null means unlimited), what it uses now, and whether the key has read, full or admin access. Call it first. GET /api/v1/workspace | Read only | Reads |
get_stats | The overview numbers for the last 7, 14, 30 or 90 days: submissions by outcome and against the period before, per day, per form and per source, and every flow's runs by outcome. Test submissions are left out. GET /api/v1/stats | Read only | Reads |
update_workspace | Changes the workspace name, its timezone and its preferences, like the Settings page. Only what you send changes. PATCH /api/v1/workspace | Admin access | Changes |
set_workspace_logo | Uploads the workspace logo shown in the workspace menu: a square PNG, JPEG or WebP picture, at most 512 KB, as base64 or a data URL. POST /api/v1/workspace/logo | Admin access | Changes |
remove_workspace_logo | Deletes the uploaded workspace logo, so the workspace shows its initials again. DELETE /api/v1/workspace/logo | Admin access | Removes |
Forms
| Tool | What it does | Access | Kind |
|---|---|---|---|
list_forms | Every form with all its fields and settings. GET /api/v1/forms | Read only | Reads |
get_form | One form with all its fields and settings. GET /api/v1/forms/{id} | Read only | Reads |
create_form | Creates a form with its fields and settings. Connect a website to it with create_source, which answers with the endpoint address the website posts to. POST /api/v1/forms | Full access | Changes |
update_form | Changes only what you send. fields replaces the whole list: repeat the id of every field to keep, and leave the id out for new ones. A renamed key or option value is rewritten in the form's flows too. PATCH /api/v1/forms/{id} | Full access | Changes |
delete_form | Deletes a form for good, with every submission it holds, and pauses its flows. Ask the person first. DELETE /api/v1/forms/{id} | Full access | Removes |
draft_form_with_ai | Drafts a form name, description and fields from a sentence, or only the fields an existing form is missing when form_id is given. Nothing is saved: pass the draft to create_form, or add its fields with update_form. Uses one of the workspace's daily AI drafts (the answer's usage says how many are left; a failed draft is not counted, and the same request again within 10 minutes answers the same draft for free). POST /api/v1/ai/form-draft | Full access | Reads |
publish_form | Publishes a form on its own share link, a public page anyone can fill in, and answers with the link and the embed codes (inline, popup and iframe) for any website. Without a slug a first publish takes one made from the form name when it is free. Call it again with a slug to move the link. Answers can be filled in from the link, such as ?email=jane@example.com. POST /api/v1/forms/{id}/publish | Full access | Changes |
unpublish_form | Takes the form's share link and embeds offline. The slug is kept, so publish_form brings the same link back. Websites connected as sources keep working. POST /api/v1/forms/{id}/unpublish | Full access | Changes |
duplicate_form | Copies a form with its fields and settings into a new draft form that is not published. Counts toward the plan's forms. POST /api/v1/forms/{id}/duplicate | Full access | Changes |
Sources
| Tool | What it does | Access | Kind |
|---|---|---|---|
list_sources | The websites and tools that send submissions, each with its endpoint address and status. GET /api/v1/sources | Read only | Reads |
get_source | One source with its endpoint address, status and when it last sent a submission. GET /api/v1/sources/{id} | Read only | Reads |
create_source | Connects a website or tool to a form and answers with endpoint_url, the address its form posts to (as the form action, or with fetch and JSON). POST /api/v1/sources | Full access | Changes |
update_source | Changes only what you send. status paused refuses its submissions; active takes them again. PATCH /api/v1/sources/{id} | Full access | Changes |
rotate_source_key | Gives the source a new endpoint address. The old one stops working at once, so the website has to be updated. Ask the person first. POST /api/v1/sources/{id}/rotate-key | Full access | Removes |
delete_source | Disconnects a source: its endpoint stops taking submissions. The submissions it brought in stay. Ask the person first. DELETE /api/v1/sources/{id} | Full access | Removes |
Flows
| Tool | What it does | Access | Kind |
|---|---|---|---|
list_flows | Every flow with its steps and connections. GET /api/v1/flows | Read only | Reads |
get_flow | One flow with its steps, connections and checks: whether it can go live and what blocks it. GET /api/v1/flows/{id} | Read only | Reads |
create_flow | Creates a flow, either from a template for form_id (route: validate, then send each option of a dropdown to a different place; notify: validate and email every submission to your team; confirm: email the team and send the sender a confirmation; blank: start with the trigger and build the rest yourself) or from nodes and edges. Create it as draft, read its checks with get_flow, then make it active with update_flow. POST /api/v1/flows | Full access | Changes |
update_flow | Changes only what you send. nodes replaces every step and needs edges too. A flow that is or becomes active has to pass its checks. Changes to a live flow apply to the next submission. PATCH /api/v1/flows/{id} | Full access | Changes |
test_flow | Runs one flow on answers you send, whatever its status, the way the editor test panel does: every step is simulated, nothing is delivered or stored, waits are skipped and AI steps use a stand-in answer. Answers with each step and the path it took. POST /api/v1/flows/{id}/test | Full access | Reads |
duplicate_flow | Copies a flow with every step into a new draft flow. Counts toward the plan's flows. POST /api/v1/flows/{id}/duplicate | Full access | Changes |
delete_flow | Deletes a flow. Past runs stay on their submissions. Ask the person first. DELETE /api/v1/flows/{id} | Full access | Removes |
Destinations
| Tool | What it does | Access | Kind |
|---|---|---|---|
list_destinations | The connected chat channels and webhooks flow steps deliver to. Read only keys see each address masked. GET /api/v1/destinations | Read only | Reads |
get_destination | One destination. GET /api/v1/destinations/{id} | Read only | Reads |
create_destination | Connects a chat channel or a webhook from its incoming webhook address. Email needs no destination: email steps send on their own. POST /api/v1/destinations | Full access | Changes |
update_destination | Changes the name, target or address. The kind stays. PATCH /api/v1/destinations/{id} | Full access | Changes |
delete_destination | Disconnects a destination. Flow steps that delivered to it need a new one before those flows can go live again. Ask the person first. DELETE /api/v1/destinations/{id} | Full access | Removes |
Submissions
| Tool | What it does | Access | Kind |
|---|---|---|---|
list_submissions | The inbox, newest first, without test submissions unless asked. To page back, call again with before set to the next_before it answered. GET /api/v1/submissions | Read only | Reads |
get_submission | One submission with its answers, page, country, files and every flow run step by step. GET /api/v1/submissions/{id} | Read only | Reads |
get_submission_file | A private link to a file uploaded with a submission. It works for 15 minutes, so never store it. GET /api/v1/submissions/{id}/files/{fileId} | Read only | Reads |
mark_submission_spam | spam true marks a submission as spam. spam false releases it, and one that was held back as spam then runs its flows, delivering for real. PATCH /api/v1/submissions/{id} | Full access | Delivers |
rerun_submission | Runs every live flow of a submission again. A real submission delivers for real again: emails, chat messages and webhooks. Ask the person first. POST /api/v1/submissions/{id}/rerun | Full access | Delivers |
send_test_submission | Stores a test submission for a form and runs its live flows on it, simulated. Nothing is delivered, it is marked as a test, and it does not count toward the monthly submissions. POST /api/v1/submissions/test | Full access | Changes |
delete_submission | Deletes a submission with its files, for good. Ask the person first. DELETE /api/v1/submissions/{id} | Full access | Removes |
Team, roles and access
| Tool | What it does | Access | Kind |
|---|---|---|---|
list_permissions | Every permission a role can have, with what it allows. Every member reads the whole workspace; a permission is what lets a role change one part of it. GET /api/v1/permissions | Read only | Reads |
list_roles | Every role: the default ones (owner, admin, editor, viewer), which never change, then the workspace's own, each with its permissions and how many people hold it. GET /api/v1/roles | Read only | Reads |
get_role | One role with its permissions and how many people and open invitations hold it. GET /api/v1/roles/{id} | Read only | Reads |
create_role | Creates a role of the workspace's own from a name and permissions, such as Support with only inbox. Give it to people with change_member_role, or invite someone with it. POST /api/v1/roles | Admin access | Changes |
update_role | Changes the name, description or permissions of one of the workspace's own roles. Everyone holding it gets the new permissions at once. The default roles cannot be changed. Ask the person before taking permissions away. PATCH /api/v1/roles/{id} | Admin access | Changes |
delete_role | Deletes one of the workspace's own roles. Everyone holding it, and every open invitation with it, moves to move_to first (Viewer when left out). Ask the person first. DELETE /api/v1/roles/{id} | Admin access | Removes |
get_member | One member with their role and permissions. GET /api/v1/members/{id} | Admin access | Reads |
list_members | Every member of the workspace, owner first, with their role and what it lets them change, and the invitations still waiting for an answer. GET /api/v1/members | Admin access | Reads |
invite_member | Emails an invitation to join the workspace, with a link that works for 7 days. Inviting the same address again sends a fresh link. Counts toward the plan's team seats, at most 10 invitations a day. POST /api/v1/invitations | Admin access | Delivers |
resend_invitation | Emails a fresh invitation link, valid for another 7 days. The old link stops working. POST /api/v1/invitations/{id}/resend | Admin access | Delivers |
withdraw_invitation | Withdraws an invitation, so its link stops working. DELETE /api/v1/invitations/{id} | Admin access | Removes |
change_member_role | Gives a member another role, a default one or one of the workspace's own, never with more than your own access allows. The owner keeps their role, and handing the workspace over stays with the owner in the dashboard. Ask the person first. PATCH /api/v1/members/{id} | Admin access | Changes |
remove_member | Removes someone from the workspace. They lose access at once. The owner cannot be removed. Ask the person first. DELETE /api/v1/members/{id} | Admin access | Removes |
list_api_keys | The workspace's API keys with their access and when each was last used. The keys themselves are never shown again. GET /api/v1/api-keys | Admin access | Reads |
create_api_key | Makes an API key and answers it once, in secret. Hand it to the person to store safely: it cannot be shown again. Counts toward the plan's API keys. POST /api/v1/api-keys | Admin access | Changes |
revoke_api_key | Revokes a key: anything using it gets refused from then on, the key you are using too. Ask the person first. DELETE /api/v1/api-keys/{id} | Admin access | Removes |
list_connected_apps | The AI agent apps signed in to the workspace with a link, with who connected each and its access. GET /api/v1/connected-apps | Admin access | Reads |
disconnect_app | Ends an app's sign-in at once. It has to be connected again to come back. Ask the person first. DELETE /api/v1/connected-apps/{id} | Admin access | Removes |
Billing
| Tool | What it does | Access | Kind |
|---|---|---|---|
get_billing | The plan and subscription, the card on file, the latest invoices, and every plan with its monthly price in cents and its limits. GET /api/v1/billing | Admin access | Reads |
change_plan | Moves the workspace to pro or max. Without a paid plan it answers checkout_url, a Stripe page the person opens to pay. With one it changes the plan at once and charges the card on file the prorated difference for an upgrade. Always confirm the plan and price with the person first. POST /api/v1/billing/checkout | Admin access | Delivers |
set_plan_cancellation | With cancel_at_period_end true, the paid plan ends when the period already paid for ends and the workspace moves to Starter; false keeps it. Nothing is refunded or deleted. Ask the person first. PATCH /api/v1/billing/subscription | Admin access | Removes |
open_billing_portal | Answers portal_url, a Stripe page where the person changes the card or billing details and downloads invoices. POST /api/v1/billing/portal | Admin access | Delivers |
An example
Asked to "set up a quote form for our Webflow site and send big jobs to Slack", an agent with full access typically runs these tools in order:
get_workspacechecks the plan, what is left and that the key has full accesscreate_forma Quote request form with name, email, move date and an estimated budgetcreate_sourceconnects the Webflow site and gets the endpoint address to put in the formlist_destinationsfinds the #sales-leads Slack channel the team already connectedcreate_flowa Route by answer flow from the template, sending big budgets to Slack and the rest by emailget_flowreads the checks, sees the flow is ready to go liveupdate_flowsets the status to activesend_test_submissionsends a test and reads which steps ran
Asked to "make a feedback form I can send to our customers", two tools are enough: create_form with the questions, then publish_form, which answers the share link to send and the embed codes for a website.
How the sign-in works
You only need this to build your own agent app. Formpik follows the MCP authorization spec: OAuth 2.1 with PKCE, where Formpik is both the MCP server and the place people sign in. A request without a token gets a 401 whose WWW-Authenticate header points at the protected resource metadata, and everything else is found from there.
| What | Address |
|---|---|
| Protected resource metadata | https://formpik.com/.well-known/oauth-protected-resource/api/mcp |
| Authorization server metadata | https://formpik.com/.well-known/oauth-authorization-server |
| Allow access page | https://formpik.com/oauth/authorize |
| Token | https://formpik.com/api/oauth/token |
| Client registration | https://formpik.com/api/oauth/register |
| Revocation | https://formpik.com/api/oauth/revoke |
- Register with dynamic client registration (a JSON
POSTwithclient_nameandredirect_uris), or use an https address that serves a client metadata document as yourclient_id. - Redirect URIs are https addresses,
http://localhostorhttp://127.0.0.1on any port, or your app's own scheme. - PKCE with
S256is required. The one-time code works for 10 minutes and only once. - Scopes are
read,fullandadmin. The person can always give less than the app asked for, and the token answer'sscopesays what they gave. - Access tokens work for 60 minutes and only at the MCP server, never at the REST API. Refresh tokens change on every use, and an old one used again ends the connection. A connection unused for 90 days ends too.
- Disconnecting an app on the API keys page, or sending its refresh token to the revocation endpoint, stops it at once.
Messages
You only need this to build your own client. The server answers initialize, ping, tools/list and tools/call, accepts notifications with 202, and takes a list of messages in one request too.
curl -X POST "https://formpik.com/api/mcp" \
-H "Authorization: Bearer $FORMPIK_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "list_forms", "arguments": {"status": "active"}}}'{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{ "type": "text", "text": "{\"data\":[{\"id\":\"frm_q8w2e4r6t1\",\"name\":\"Quote request\", ...}]}" }
],
"structuredContent": {
"data": [{ "id": "frm_q8w2e4r6t1", "name": "Quote request", "status": "active", "fields": [] }]
}
}
}A tool answers with the same JSON as its API endpoint, as text and as structuredContent. When the API refuses a call, the tool result carries isError: true and the API's message and code, so the agent can read what went wrong and try again.
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"content": [
{ "type": "text", "text": "Starter includes 3 forms. Pro gives you 25 forms.\nCode: plan-limit (HTTP 402)" }
],
"isError": true
}
}| Status | When |
|---|---|
| 200 | A request was answered, including tool results with isError. |
| 202 | Only notifications were sent, which need no answer. |
| 401 | No token, or one that is not valid or has expired. The answer carries WWW-Authenticate: Bearer with resource_metadata, which tells agent apps where to sign in. |
| 405 | A GET. The server has no event stream to open. |
| 429 | More than 120 requests a minute from one connection or key. Wait for Retry-After. |
Keep it safe
- Give an agent read only access unless it needs to make changes. You can connect it again with full access later.
- Check Connected apps on the API keys page now and then, and disconnect agents you no longer use. Each shows who connected it and when it last worked.
- Deleting, rotating an endpoint address and running flows again on real submissions are marked as tools that change things for real. Keep your app asking before it runs them.
- A connection or key works on one workspace. An agent connected to one workspace never sees another.