Tool Reference

Complete reference for all 22 MCP tools available in the Surface Forms MCP server

The Surface Forms MCP server exposes 22 tools organized into six categories. All tools are automatically scoped to your environment via your API key.

Forms

`list_forms`

List all forms in your environment with response counts and pagination.

pagebodynumber

Page number for pagination.

limitbodynumber

Number of forms to return per page.

searchbodystring

Search forms by name.

sortBybodystring

Sort by "name", "updatedAt", or "createdAt".

sortOrderbodystring

Sort direction: "asc" or "desc".

dateRangebodyobject

Filter by date range with from and to fields. Response counts are scoped to this range.

›Example use cases

List all my forms with response counts
Search forms by name (e.g. "contact us")
Get forms sorted by most recently updated
See how many total/completed/partial responses a form has within a date range

`get_form`

Get a single form's full configuration, including all questions, styles, and settings.

formIdbodystringrequired

The ID of the form to retrieve.

Generate a new form from an existing source form used as a style template. The new form inherits all visual settings (fonts, colors, backgrounds, component styles) from the source form. The form is automatically published and ready to use.

This is the only mutation tool in the MCP server. Use list_forms first to find a suitable source form ID.

sourceFormIdbodystringrequired

The ID of an existing form to use as a style template.

namebodystringrequired

Display name for the generated form.

stepsbodyarrayrequired

Array of step objects (minimum 2). Each step represents a page/screen in the form.

›Step object properties

namebodystringrequired

Display name for the step.

componentsbodyarrayrequired

Array of component objects (minimum 1). Each component has a type and content.

Supported component types:

Type	Description	Key content fields
`ShortInput`	Single-line text input	`question`
`LongInput`	Multi-line text area	`question`
`IdentityInfo`	Name, email, company fields	`fields` (array of `{ key, label }`)
`Dropdown`	Dropdown select menu	`question`, `options`
`MultipleOptionsQuestion`	Single/multi-select choices	`question`, `choices`, `isMulti`
`CalendlyScreen`	Calendar scheduling widget	`dataUrl`, `message`, `calendarType`
`DynamicScheduler`	Routing scheduler	`defaultCalendar`
`NextButton`	Advance to next step	`label`
`Header`	Heading text	`title`, `subheading`
`Disclaimer`	Legal/disclaimer text	`text`

See the Generate Form API reference for full content field details per component type.

›Example use cases

Create a demo booking form with identity fields and a Calendly scheduler
Generate a feedback survey with dropdowns and multiple choice questions
Build a contact form with name, email, company, and a submit button
Create a lead capture form styled like an existing form

Responses

`list_responses`

List responses for a form with filtering, full-text search, and sorting.

formIdbodystringrequired

The form to list responses for.

limitbodynumber

Number of responses to return.

finishedbodyboolean

Filter by completion status. true = completed, false = partial/abandoned.

dateRangebodyobject

Filter responses by date range (from, to).

filterbodyarray

Filter responses by answer values. Each filter has type, filter, and operator (e.g. "contains", "equals").

searchbodyarray

Full-text search across response data. Each entry has type and value.

sortbodyarray

Sort by specific fields. Each entry has field and direction.

›Example use cases

Get the latest 10 responses for a specific form
Get only completed responses
Filter responses by answer value (e.g. contains "enterprise")
Get responses within a date range

`get_response`

Get a single response with all answer data, notes, tags, and associated person info.

responseIdbodystringrequired

The ID of the response to retrieve.

`search_responses`

Full-text search across all response data in your environment.

searchTermbodystringrequired

The text to search for across response data (email, name, answer values, etc.).

formIdbodystring

Optionally scope the search to a specific form.

›Example use cases

Find all responses containing a specific email address
Search for responses mentioning "enterprise"
Find all responses from a specific company

Leads

`list_leads`

List qualified leads with their attributes (email, name, company) and scores.

pagebodynumber

Page number for pagination.

limitbodynumber

Number of leads to return per page.

searchbodystring

Search leads by email, name, or company.

sourcebodystring

Filter by lead source: "surfaceForm", "htmlForm", "websiteDeAnon", or "webhook".

dateRangebodyobject

Filter leads by creation date range (from, to).

›Example use cases

List all qualified leads
Search leads by email or company name
Filter leads by source (e.g. only website de-anonymization leads)
Get leads created in a specific date range

`get_leads_count`

Get total lead counts with optional breakdowns by source or funnel stage.

bySourcebodyboolean

Break down count by lead source (Surface Form, HTML Form, Website De-Anon, Webhook).

byEventTypebodyboolean

Break down count by funnel stage (visited, submitted, completed, meeting booked).

dateRangebodyobject

Scope counts to a date range (from, to).

›Example use cases

Get total count of qualified leads
Break down leads by source
Break down leads by funnel stage
Get lead counts in a date range broken down by source and event type

Analytics

`get_form_analytics`

Get completion rate and dropoff analysis for a form, including email open rates and top referrer URLs.

formIdbodystringrequired

The form to analyze.

dateRangebodyobject

Scope analytics to a date range (from, to).

›Example use cases

Get completion rate and dropoff analysis
See which question has the highest dropoff
Get email open rates for a form
Get top referrer URLs

`get_daily_form_stats`

Get day-by-day response counts for a specific form.

formIdbodystringrequired

The form to get daily stats for.

dateRangebodyobject

Scope to a date range (from, to).

`get_daily_stats`

Get daily environment-level metrics including visitors, leads, responses, and workflow runs.

dateRangebodyobject

Scope to a date range (from, to). Defaults to the last 30 days.

`get_lead_source_analytics`

Get landing page performance metrics — visitors, form starts, completions, meetings, and conversion rates. Automatically includes comparison with the previous period.

pagebodynumber

Page number for pagination.

limitbodynumber

Number of landing pages to return.

searchbodystring

Search landing pages by URL.

urlsbodyarray

Filter to specific URLs.

dateRangebodyobject

Scope analytics to a date range (from, to). Previous period comparison is included automatically.

›Example use cases

See which landing pages have the best conversion rates
Compare landing page performance with the previous period
Search landing page analytics by URL

`get_user_journey_analytics`

Get UTM and traffic source breakdown for a form, including AI traffic sources (ChatGPT, Perplexity, etc.) and click IDs (gclid, fbclid).

formIdbodystringrequired

The form to analyze.

dateRangebodyobject

Scope analytics to a date range (from, to).

›Example use cases

Get UTM breakdown (source, medium, campaign) for a form
See AI traffic sources (ChatGPT, Perplexity, etc.)
See click IDs (gclid, fbclid) for ad attribution

`get_conversion_funnel`

Get per-URL conversion funnel breakdown: form starts, completed/partial, qualified/disqualified, meetings booked/not booked.

pagebodynumber

Page number for pagination.

limitbodynumber

Number of URLs to return.

urlbodystring

Filter to a specific landing page URL.

dateRangebodyobject

Scope to a date range (from, to).

›Example use cases

Get the full conversion funnel for the last 7 days
Get conversion funnel for a specific landing page
Compare funnel performance across different URLs

Number of results to return.

orderbodystring

Sort order: "desc" for highest scores first, "asc" for lowest.

formIdbodystring

Scope to a specific form.

minScorebodynumber

Minimum AI score threshold.

›Example use cases

Get the top 10 highest-scored leads
Get the lowest-scored responses
Get responses scoring above 80

`get_ai_score_stats`

Get AI score statistics including average, min, max, and distribution across buckets (0-19, 20-39, 40-59, 60-79, 80-100).

formIdbodystring

Scope statistics to a specific form.

`get_responses_with_ai_scores`

Get responses for a form enriched with their AI scores.

formIdbodystringrequired

The form to get responses for.

sortBybodystring

Sort by "score" to rank by AI score.

finishedbodyboolean

Filter by completion status.

`get_leads_with_ai_scores`

Get leads ranked by their AI score.

sortBybodystring

Sort by "score" to rank by AI score.

orderbodystring

Sort direction: "desc" or "asc".

minScorebodynumber

Minimum score threshold.

maxScorebodynumber

Maximum score threshold.

›Example use cases

Get leads ranked by AI score (highest first)
Get leads scoring between 50 and 80

`compare_forms`

Compare forms side-by-side by response count, completion rate, and average AI score.

formIdsbodyarray

Array of form IDs to compare. Omit to compare all forms in the environment.

›Example use cases

Compare all forms by completion rate and AI score
Compare two specific forms side-by-side

Workflows

`list_workflow_runs`

List workflow runs with filtering by status, response, lead, or workflow.

pagebodynumber

Page number for pagination.

limitbodynumber

Number of runs to return.

sortOrderbodystring

Sort direction: "asc" or "desc".

responseIdbodystring

Filter to runs triggered by a specific response.

leadIdbodystring

Filter to runs for a specific lead.

workflowIdbodystring

Filter to runs for a specific workflow.

successbodyboolean

Filter by outcome: true for successful, false for failed runs.

›Example use cases

List recent workflow runs
Get only failed workflow runs
Get runs triggered by a specific response or lead

`get_workflow_run`

Get full details of a workflow run including per-step task breakdown, payloads, errors, and timing.

runIdbodystringrequired

The ID of the workflow run to retrieve.

Forms

`list_forms`

`get_form`

`generate_form`

Responses

`list_responses`

`get_response`

`search_responses`

Leads

`list_leads`

`get_leads_count`

Analytics

`get_form_analytics`

`get_daily_form_stats`

`get_daily_stats`

`get_lead_source_analytics`

`get_user_journey_analytics`

`get_conversion_funnel`

`get_environment_overview`

AI Lead Scoring

`get_top_ai_scores`

`get_ai_score_stats`

`get_responses_with_ai_scores`

`get_leads_with_ai_scores`

`compare_forms`

Workflows

`list_workflow_runs`

`get_workflow_run`

On this page