Skip to main content
The Surface Forms MCP server exposes 21 read-only 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.
page
number
Page number for pagination.
limit
number
Number of forms to return per page.
Search forms by name.
sortBy
string
Sort by "name", "updatedAt", or "createdAt".
sortOrder
string
Sort direction: "asc" or "desc".
dateRange
object
Filter by date range with from and to fields. Response counts are scoped to this range.
  • 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.
formId
string
required
The ID of the form to retrieve.

Responses

list_responses

List responses for a form with filtering, full-text search, and sorting.
formId
string
required
The form to list responses for.
limit
number
Number of responses to return.
finished
boolean
Filter by completion status. true = completed, false = partial/abandoned.
dateRange
object
Filter responses by date range (from, to).
filter
array
Filter responses by answer values. Each filter has type, filter, and operator (e.g. "contains", "equals").
search
array
Full-text search across response data. Each entry has type and value.
sort
array
Sort by specific fields. Each entry has field and direction.
  • 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.
responseId
string
required
The ID of the response to retrieve.

search_responses

Full-text search across all response data in your environment.
searchTerm
string
required
The text to search for across response data (email, name, answer values, etc.).
formId
string
Optionally scope the search to a specific form.
  • 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.
page
number
Page number for pagination.
limit
number
Number of leads to return per page.
search
string
Search leads by email, name, or company.
source
string
Filter by lead source: "surfaceForm", "htmlForm", "websiteDeAnon", or "webhook".
dateRange
object
Filter leads by creation date range (from, to).
  • 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.
bySource
boolean
Break down count by lead source (Surface Form, HTML Form, Website De-Anon, Webhook).
byEventType
boolean
Break down count by funnel stage (visited, submitted, completed, meeting booked).
dateRange
object
Scope counts to a date range (from, to).
  • 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.
formId
string
required
The form to analyze.
dateRange
object
Scope analytics to a date range (from, to).
  • 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.
formId
string
required
The form to get daily stats for.
dateRange
object
Scope to a date range (from, to).

get_daily_stats

Get daily environment-level metrics including visitors, leads, responses, and workflow runs.
dateRange
object
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.
page
number
Page number for pagination.
limit
number
Number of landing pages to return.
search
string
Search landing pages by URL.
urls
array
Filter to specific URLs.
dateRange
object
Scope analytics to a date range (from, to). Previous period comparison is included automatically.
  • 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).
formId
string
required
The form to analyze.
dateRange
object
Scope analytics to a date range (from, to).
  • 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.
page
number
Page number for pagination.
limit
number
Number of URLs to return.
url
string
Filter to a specific landing page URL.
dateRange
object
Scope to a date range (from, to).
  • Get the full conversion funnel for the last 7 days
  • Get conversion funnel for a specific landing page
  • Compare funnel performance across different URLs

get_environment_overview

Get a high-level summary of your environment: total forms, leads, responses, and workflows. No parameters required.

AI Lead Scoring

get_top_ai_scores

Get top responses/leads ranked by AI score.
limit
number
Number of results to return.
order
string
Sort order: "desc" for highest scores first, "asc" for lowest.
formId
string
Scope to a specific form.
minScore
number
Minimum AI score threshold.
  • 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).
formId
string
Scope statistics to a specific form.

get_responses_with_ai_scores

Get responses for a form enriched with their AI scores.
formId
string
required
The form to get responses for.
sortBy
string
Sort by "score" to rank by AI score.
finished
boolean
Filter by completion status.

get_leads_with_ai_scores

Get leads ranked by their AI score.
sortBy
string
Sort by "score" to rank by AI score.
order
string
Sort direction: "desc" or "asc".
minScore
number
Minimum score threshold.
maxScore
number
Maximum score threshold.
  • 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.
formIds
array
Array of form IDs to compare. Omit to compare all forms in the environment.
  • 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.
page
number
Page number for pagination.
limit
number
Number of runs to return.
sortOrder
string
Sort direction: "asc" or "desc".
responseId
string
Filter to runs triggered by a specific response.
leadId
string
Filter to runs for a specific lead.
workflowId
string
Filter to runs for a specific workflow.
success
boolean
Filter by outcome: true for successful, false for failed runs.
  • 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.
runId
string
required
The ID of the workflow run to retrieve.