MCP & AI Access

Formtress runs a Model Context Protocol (MCP) server so AI clients can read your workspace: list forms, search submissions, check webhook deliveries, and report on usage. No glue code required: point any MCP-capable client at the endpoint and your agent can answer questions about your forms.

Access is read-only and workspace-scoped, and can be revoked at any time.

Tip

Recommended: Claude (and most clients) connects with OAuth, no token to paste. The client signs you in, you pick the workspace, done. API tokens below are a fallback for scripts and clients without OAuth.

Endpoint

https://app.formtress.com/api/mcp

• Transport: Streamable HTTP (stateless, JSON responses)
• Server name: formtress
• Methods: POST, GET, DELETE (plus OPTIONS for CORS preflight)
• CORS: enabled, so browser-based clients work too

Authentication

There are two ways to authenticate, depending on your client:

• OAuth (recommended): supported natively by Claude connectors, ChatGPT Desktop, and most clients that follow the MCP authorization spec. Nothing to create or paste; you just sign in to Formtress and pick the workspace to expose.
• API tokens: the fallback for scripts, CLIs, and clients without OAuth. MCP requests are authenticated with the same tokens as the public API. Create them in your dashboard under Connect → MCP & AI.

1. Go to Connect → MCP & AI in your workspace dashboard.
2. Click New token and give it a descriptive name (e.g. “Claude desktop”).
3. Copy the token immediately; it is shown only once.

Caution

Tokens look like fmt_live_xxxxxxxxxxxxxxxxxxxx and grant read access to your submissions. Treat them like passwords.

Send the token as an Authorization header:

Authorization: Bearer fmt_live_xxxxxxxxxxxxxxxxxxxx

For MCP clients that cannot set custom headers, you can pass the token as a query parameter instead: https://app.formtress.com/api/mcp?token=fmt_live_.... The token is part of the URL in that case, so treat the link like a password.

Connecting a client

Claude

Works with claude.ai, the Claude Desktop app, and Claude mobile via OAuth (no token needed).

Setting up the Formtress connector in Claude (00:38)

1. Open Claude → Settings → Connectors.
2. Click + Add → Add custom connector.
3. Fill in the information: Name: Formtress, MCP server URL: https://app.formtress.com/api/mcp, then Continue.
4. Claude opens a Formtress sign-in. Authenticate, then pick the workspace to expose. Auth completes automatically.

Tip

If a client can’t sign in with OAuth, you can paste a pre-authorized connector URL (https://app.formtress.com/api/mcp?token=fmt_live_...) instead; the in-app MCP page gives you one right after creating a token.

ChatGPT Desktop

ChatGPT Desktop connects via OAuth too: no token needed.

Setting up the Formtress MCP server in ChatGPT Desktop (00:34)

1. Open ChatGPT → Plugins, click Add → Add custom MCP server.
2. Fill in the information: Name: Formtress, Server URL: https://app.formtress.com/api/mcp, check the checkbox, and create the plugin.
3. ChatGPT opens a Formtress sign-in. Authenticate, then pick the workspace to expose. Auth completes automatically.

Claude Code

The Claude Code CLI accepts remote HTTP servers natively:

claude mcp add --transport http formtress https://app.formtress.com/api/mcp --header "Authorization: Bearer fmt_live_..."

Replace fmt_live_... with one of your tokens. Add --scope user to make the server available in every project, or leave it out to scope it to the current project.

Tip

The in-app MCP page shows this command with your token already included right after you create one.

Tip

Create a dedicated token per client (e.g. “Claude desktop”, “Cursor local”) so you can revoke them independently if a device is lost.

Manual configuration

For clients configured via config files rather than OAuth, here are copy-paste snippets.

Cursor / VS Code / other

Any client that supports manual MCP config works with a standard HTTP entry. For Cursor, add to ~/.cursor/mcp.json (global) or .cursor/mcp.json in your repo:

{
  "mcpServers": {
    "formtress": {
      "type": "http",
      "url": "https://app.formtress.com/api/mcp",
      "headers": {
        "Authorization": "Bearer fmt_live_..."
      }
    }
  }
}

Claude Desktop config file

Claude Desktop supports OAuth natively for remote servers; try the connector flow above first. If you’d rather use a token, add this to claude_desktop_config.json (requires mcp-remote via npx):

{
  "mcpServers": {
    "formtress": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.formtress.com/api/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${FORMTRESS_MCP_AUTH}"
      ],
      "env": {
        "FORMTRESS_MCP_AUTH": "Bearer fmt_live_..."
      }
    }
  }
}

Available tools

The agent can call any of these tools once your token is configured. It’ll typically call list_forms first to discover ids, then use them for follow-up queries.

Tool	Description
get_workspace	Workspace id, name, slug, allowed URLs, and plan.
get_usage	Current billing-period submission count vs plan limit, percent used, remaining, and period dates.
list_forms	All forms in the workspace (id, name, field count, redacted integration summaries).
get_form	Full form details - fields, ban rules, and configured integrations. Webhook URLs are redacted to host-only so secret paths are never exposed.
list_submissions	Recent submissions, optionally filtered by form, type (clean, sus, spam, test), and date range. Paginated via cursor.
get_submission	A single submission with all field data and metadata.
search_submissions	Full-text search over submission field values and email (case-insensitive substring match).
list_webhook_attempts	Recent webhook delivery attempts for a form, with success/failure status and HTTP response codes.
analytics_timeseries	Daily breakdown of clean, suspicious, and bot-blocked submissions across the workspace.
analytics_top_forms	Forms ranked by clean submission count.
analytics_top_countries	Top submission countries (anonymised aggregate).
analytics_top_pages	Top pages where submissions originated.

Resources

Forms are also exposed as MCP resources at formtress://forms/{formId}, so clients with a resource browser (Claude Desktop, Cursor) can list and attach them directly.

Example prompts

Once connected, try asking your assistant things like:

• “Show me new submissions on my contact form today.”
• “Find submissions mentioning acme.com.”
• “Did my Zapier webhook fire? Any failures?”
• “How close am I to my plan’s submission limit?”
• “Which form got the most submissions this month?”

Rate limits

MCP requests are rate limited separately from the REST API so AI clients don’t trip on connection bursts:

Plan	REST API	MCP
Free	60 requests/min	120 requests/min
Paid	60 requests/min	600 requests/min

Exceeding a limit returns 429. If you’re building a heavy integration, batch your reads and cache responses where possible.

Token limits

Free workspaces can keep up to 2 active tokens; paid plans allow 10. MCP and the REST API are available on all plans.

Underlying REST API

The MCP server is a thin layer over Formtress’s read-only public API (https://app.formtress.com/api/v1), which is CORS-enabled and uses the same fmt_live_ tokens. The MCP page in your dashboard links to the full API & MCP reference.