The MCP server uses the same API tokens as the REST API. Every request carries the token in the Authorization header; each tool checks the token holds the right ability before running.
Mint a token
- Open API tokens.
- Click Create token, name it (e.g. "Claude Code").
- Pick the abilities. Less is more - you can always mint another.
- Copy the value. It's shown once.
Set it in your client config (Authorization: Bearer ... for HTTP, AUTH_TOKEN env var for stdio).
Abilities
| Ability | Powers |
|---|---|
forms:read |
List, fetch forms; framework integration catalog |
forms:write |
Create, update, publish, archive, restore |
forms:test-email |
Send test autoresponder / notification emails |
submissions:read |
Read submissions, files, signed URLs, form stats |
submissions:write |
Update, delete, bulk action, mark spam |
submissions:export |
Inline JSON export (up to 500 rows) |
webhooks:read |
List webhooks and deliveries (Pro and above) |
webhooks:write |
Create, update, delete, replay (Pro and above) |
surveys:read |
List, fetch surveys (Pro and above) |
surveys:write |
Create, update, publish, unpublish, delete surveys (Pro and above) |
polls:read |
List and fetch polls and results. |
polls:write |
Create and edit polls. |
polls:publish |
Publish and unpublish polls. |
polls:delete |
Archive and permanently delete polls. |
polls:present |
Run live poll events (start, open, close, reveal, moderate Q&A) without being able to create or edit polls. |
feedback:read |
Read feedback boards, posts, and the roadmap. |
feedback:write |
Create and edit boards and posts. |
feedback:moderate |
Change post status, merge, and moderate comments. |
feedback:publish |
Publish changelog announcements. |
feedback:delete |
Delete boards, posts, and comments. |
desk:read |
Read Response Desk threads and analytics. |
desk:reply |
Reply to customers from the Response Desk. |
desk:assign |
Assign, resolve, and route threads. |
desk:admin |
Manage Response Desk channels, macros, and settings. |
contacts:read |
List and fetch contacts. |
contacts:write |
Create, edit, merge, and delete contacts. |
crm:read |
Read the CRM data model and the records of every object, standard or custom. contacts:read also grants it. |
crm:write |
Create and change custom objects, fields, relations, views, and records. contacts:write also grants it. |
action-classes:read |
List in-app survey triggers. |
action-classes:write |
Create and edit in-app survey triggers. |
segments:read |
List and preview audience segments. |
segments:write |
Create and edit audience segments. |
data-tables:read |
List data tables and read their rows. |
data-tables:write |
Create, rename, and delete data tables and push rows into them. |
sdk-keys:read |
List website SDK keys. |
sdk-keys:write |
Create, rotate and revoke website SDK keys. |
displays:read |
Read survey impressions and delivery analytics. |
funnels:read |
List, fetch funnels (Pro and above) |
funnels:write |
Create, update, delete; add screens/blocks; set logic, score, pixels, CAPI (Pro and above) |
funnels:publish |
Publish or unpublish a funnel (Pro and above) |
funnels:analytics |
Funnel analytics and session lists (Pro and above) |
funnels:delete |
Restore and permanently delete funnels |
funnels:export |
Export funnel submissions |
funnels:reveal |
Reveal encrypted sensitive funnel fields |
links:read |
List, fetch short links (all plans) |
links:write |
Create, update, delete short links (all plans) |
links:analytics:read |
Read link analytics |
bio:read |
List and fetch bio pages. |
bio:write |
Create and edit bio pages and blocks. |
bio:analytics:read |
Bio page views, visitors, and clicks. |
bio:audience:export |
Export and sync the Bio audience (personal data) |
bookings:read |
Read bookings (pages, appointments, calendars) |
bookings:write |
Create and edit booking pages, manage appointments and calendars |
bookings:publish |
Publish and unpublish booking pages |
bookings:delete |
Delete, restore and permanently delete booking pages |
orders:read |
Read orders, line items, refunds, disputes and payment totals |
orders:refund |
Ask the payment provider to refund a form or funnel order |
knowledge:read |
Read knowledge base |
knowledge:write |
Manage knowledge base and help center |
support:write |
Contact Formspring support |
automations:read |
List automations, runs, run details (all plans) |
automations:write |
Create, update, enable, disable, delete automations (all plans) |
automations:run |
Manually trigger or replay automation runs (all plans) |
billing:read |
Team summary, plan, usage, subscription state |
billing:write |
Manage subscription, coupons and credit packs (team owner) |
insights:read |
Read AI insights (Pro and above) |
insights:write |
Trigger regeneration (Pro and above) |
account:read |
Read profile, dashboard, search and setup guide |
account:write |
Update setup guide progress |
projects:read |
Read projects |
projects:write |
Create, edit and restore projects |
projects:delete |
Archive and permanently delete projects |
team:read |
Read workspace settings and theme |
team:write |
Change workspace settings, theme and address; create workspaces |
team:delete |
Delete the workspace |
members:read |
Read members and invitations |
members:write |
Invite, remove and change roles of members |
approvals:read |
Read approval requests |
approvals:write |
Approve or reject approval requests |
sso:read |
Read single sign-on settings |
sso:write |
Manage single sign-on |
email:read |
Read email sending settings |
email:write |
Manage SMTP and sending domain |
agency:read |
Read agency settings, client workspaces and the agency portal |
agency:write |
Manage client workspaces, project assignment and the agency portal |
tokens:read |
List your own tokens |
tokens:write |
Mint and revoke tokens (subset of caller's abilities) |
Abilities are independent of plan: you can mint surveys:write on Free, but survey tools are hidden from tools/list and return plan errors if invoked. The in-app setup wizard defaults to every ability except the sensitive ones: tokens:write, team:delete, billing:write, members:write, sso:write, email:write, funnels:reveal, and bio:audience:export. Tick those on only when the agent needs them.
Plan vs. ability
- Ability - does the token include what the tool needs?
- Plan - does the team's subscription include the product (surveys, funnels, webhooks, AI)? Paid-only tools, resources, and prompts are filtered out of list responses on Free.
- Policy - for mutations, does the user have the dashboard permission?
- Team - does the record belong to the calling team?
Miss any check and the tool refuses (or never appears in the client's tool picker).
Team scoping
Every token is minted in one workspace and stays bound to it: it keeps acting in that workspace even after you switch to another one in the dashboard, and it is refused if you leave the workspace. Cross-team lookups return "not found" (not "forbidden") so an agent can't enumerate other teams. Older tokens that were minted before binding existed keep following your current workspace; mint a new token to bind it. The API token list shows each token's team_id.
Ask me before risky actions
A token can wait for your approval before it does anything risky. When that is on, the first time the token calls a risky tool nothing runs. The tool result tells the assistant where you approve the call, and it runs only after you do.
It is on by default for:
- tokens created by the device sign-in flow and the in-app setup wizard,
- the Ask me before this token does anything risky box when you create a token in the dashboard (untick it if you want the token to run on its own),
- tokens an assistant creates with the
create_tokentool (it can passconfirm_destructive: falseto opt out, unless its own token needs approval; a token that needs approval only ever creates tokens that need it too).
Tokens created through POST /api/v1/tokens ask only when you send confirm_destructive: true.
Risk classes
Every tool has one risk class, shown on the approval page. Reads and ordinary edits never wait. The other five classes always do, for a token that asks for approval:
| Risk class | What it covers | Examples |
|---|---|---|
read |
Reads only. Never waits. | list_forms, get_submission |
write |
Ordinary edits you can change or undo. Never waits. | create_form, update_contact, publish_form |
destructive |
Deletes, overwrites wholesale, revokes or rolls back. | delete_contact, force_delete_form, bulk_submissions, merge_contacts |
external_send |
Reaches people or systems outside your workspace. | reply_desk_thread, send_contact_email, send_survey_wave, send_signing_request, invite_portal_client, replay_webhook_delivery |
financial |
Moves money, changes a subscription or records revenue. | subscribe_to_plan, purchase_ai_credit_pack, request_booking_balance, refund_booking_payment |
credential |
Creates, rotates, stores or reveals a key, secret, token or sending setup. | create_token, rotate_webhook_secret, update_smtp_config, set_sending_domain, connect_issue_tracker |
access_control |
Changes who can get in or what they may do. | invite_team_member, update_team_member_role, remove_team_member, create_sso_connection |
A tool that has not been given a class is treated as risky until it is classified, so a new tool never skips approval by accident. The class is separate from the ability: the ability (forms:write, billing:write and so on) decides whether the token may call the tool at all; the class decides whether you also have to approve each call.
What the assistant sees
{
"error": "confirmation_required",
"confirmation_id": "cnf_01j...",
"confirm_url": "https://formspring.io/mcp/confirm/cnf_01j...",
"expires_at": "2026-10-27T10:15:00+00:00",
"risk_class": "external_send",
"abilities": ["desk:reply"],
"summary": { "thread_id": "thr_123", "body": "Hello..." }
}
You open confirm_url while signed in and approve or decline. The page shows the tool, the kind of action, the permission it needs and the arguments (anything that looks like a secret is hidden). After you approve, the assistant calls the same tool again with the same arguments plus confirmation_id, and it runs once.
An approval is tied to you, to that token, to that tool and to those exact arguments. It expires after 15 minutes and cannot be used twice. Changing even one character of the arguments needs a new approval. Text inside the arguments, such as a note that claims you already approved, never counts: only you can approve, and only from your signed-in browser session, never with a token. If the token does not hold the ability the tool needs, an approved call is still refused.
Reviewing tokens you already have
Tokens created before approval became the default keep working exactly as they did. Open API tokens: tokens that run without asking are flagged, and Ask first switches approval on for a token. You can also turn it off again with Stop asking. A token cannot change this setting for itself.
Local subprocess transport
The local transport that some desktop clients start as a subprocess has no signed-in user, so it refuses every tool call. Connect over the hosted endpoint with a token or the device sign-in flow instead.
Revocation
Pull a token from API tokens in one click. The next call from the agent fails. No grace period.
Refusal message
Token missing required ability `submissions:write`.
The agent sees this in the tool result and either asks you, or falls back to a tool that's in scope.
