Skip to main content

MCP Integration

Create FormLeap forms using AI assistants through the Model Context Protocol (MCP).

What is MCP?

Model Context Protocol (MCP) is an open standard that allows AI assistants like Claude to interact with external services and tools.

With FormLeap's MCP integration, you can:

  • Create forms from natural language - Describe your form, AI builds it
  • Upload PDF forms - Convert paper forms to digital forms instantly
  • Edit existing forms - Modify forms using conversational commands
  • Retrieve submissions - Query and analyze form data
  • Automate workflows - Bulk operations on forms and submissions

Example:

You: Create a customer feedback form with rating scales for
     product quality, customer service, and delivery speed.
     Include a comments field and collect email addresses.

Claude: I'll create that feedback form for you...
        [Creates form with 3 rating fields, textarea, and email field]

Availability

Plans: Business and Enterprise

Supported AI Assistants:

  • Claude Desktop (Mac, Windows)
  • Claude Code CLI
  • Any MCP-compatible AI assistant

Getting Started

Prerequisites

  1. FormLeap Business or Enterprise account
  2. Claude Desktop or Claude Code CLI installed
  3. FormLeap API key

Installation

For Claude Desktop

  1. Get your API key:

    • Log in to FormLeap
    • Go to Account Settings → API
    • Click Create API Key
    • Name it "Claude Desktop"
    • Copy and save the key securely

  2. Configure Claude Desktop:

    Edit your Claude Desktop configuration file:

    macOS: 

    ~/Library/Application\ Support/Claude/claude_desktop_config.json

    Windows: 

    %APPDATA%\Claude\claude_desktop_config.json

  3. Add FormLeap MCP server: 

    {
  "mcpServers": {
    "formleap": {
      "url": "https://formleap.app/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

  4. Restart Claude Desktop

  5. Verify installation:

    In Claude Desktop, type: 

    List my FormLeap forms

    Claude should connect to FormLeap and show your forms.

For Claude Code CLI

  1. Configure Claude Code:

    Edit ~/.config/claude-code/settings.json: 

    {
  "mcpServers": {
    "formleap": {
      "url": "https://formleap.app/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

  2. Restart Claude Code

Available Tools

The FormLeap MCP server provides these tools:

Form Management

create_form

Create a new form from a schema or natural language description.

Parameters:

  • workspace_id (required) - Target workspace ID
  • name (required) - Form name
  • description (optional) - Form description
  • fields (required) - Array of field definitions
  • settings (optional) - Form settings object

Example:

{
  "workspace_id": "ws_123abc",
  "name": "Customer Feedback",
  "description": "Collect feedback from customers",
  "fields": [
    {
      "type": "text",
      "label": "Full Name",
      "required": true
    },
    {
      "type": "email",
      "label": "Email Address",
      "required": true
    },
    {
      "type": "rating",
      "label": "How satisfied are you?",
      "min": 1,
      "max": 5,
      "required": true
    },
    {
      "type": "textarea",
      "label": "Additional Comments",
      "required": false
    }
  ],
  "settings": {
    "access_control": "public",
    "confirmation_message": "Thank you for your feedback!"
  }
}

get_form

Retrieve form details by ID.

Parameters:

  • form_id (required) - Form identifier

Returns: Complete form object including fields, settings, and AST.

update_form

Update an existing form.

Parameters:

  • form_id (required) - Form identifier
  • name (optional) - New form name
  • description (optional) - New description
  • fields (optional) - Updated field definitions
  • settings (optional) - Updated settings

delete_form

Delete a form permanently.

Parameters:

  • form_id (required) - Form identifier

Warning: This action cannot be undone.

list_forms

List all forms in a workspace.

Parameters:

  • workspace_id (required) - Workspace identifier
  • status (optional) - Filter by status (draft, published)
  • limit (optional) - Maximum results (default: 50)
  • offset (optional) - Pagination offset

Submission Access

get_submissions

Retrieve submissions for a form.

Parameters:

  • form_id (required) - Form identifier
  • limit (optional) - Maximum results (default: 50)
  • offset (optional) - Pagination offset
  • status (optional) - Filter by status (completed, incomplete)

Returns: Array of submission objects with responses.

search_submissions

Full-text search across submissions.

Parameters:

  • form_id (required) - Form identifier
  • query (required) - Search query
  • limit (optional) - Maximum results

Returns: Ranked search results.

Workspace Management

list_workspaces

List all accessible workspaces.

Returns: Array of workspaces with IDs and names.

invite_member

Invite a team member to a workspace.

Parameters:

  • workspace_id (required) - Workspace identifier
  • email (required) - Email address
  • role (required) - "owner" or "member"

Form Schema & AST

Field Types

FormLeap supports these field types via MCP:

Text Input:

  • text - Single-line text
  • textarea - Multi-line text
  • email - Email address
  • phone - Phone number
  • url - Website URL

Number & Date:

  • number - Numeric input
  • date - Date picker
  • time - Time picker
  • datetime - Date and time picker

Selection:

  • dropdown - Single-select dropdown
  • radio - Radio button group
  • checkbox - Multiple-select checkboxes
  • yes_no - Binary toggle

Advanced:

  • file_upload - File upload field
  • composite - Group of fields
  • rating - Star or numeric rating
  • range - Slider input

Content:

  • heading - Section heading
  • paragraph - Explanatory text
  • divider - Visual separator

Field Properties

Each field type supports common properties:

{
  "type": "text",
  "label": "Field Label",          // Required
  "placeholder": "Hint text",      // Optional
  "help_text": "Additional info",  // Optional
  "required": true,                // Optional (default: false)
  "validation": {                  // Optional
    "min_length": 3,
    "max_length": 100,
    "pattern": "^[A-Za-z]+$"
  }
}

Composite Fields

Group related fields together:

{
  "type": "composite",
  "label": "Mailing Address",
  "layout": "grid_2",              // stack, row, grid_2, grid_3, grid_4
  "repeatable": false,             // Allow multiple entries
  "min": 1,                        // Min entries (if repeatable)
  "max": 5,                        // Max entries (if repeatable)
  "children": [
    {
      "type": "text",
      "label": "Street Address",
      "col_span": 2              // Column spanning in grid
    },
    {
      "type": "text",
      "label": "City"
    },
    {
      "type": "text",
      "label": "State"
    }
  ]
}

Logic Jumps

Add conditional logic to fields:

{
  "type": "text",
  "label": "Company Name",
  "conditions": [
    {
      "action": "show",          // show, hide, or skip (steps only)
      "operator": "all",          // all (AND) or any (OR)
      "rules": [
        {
          "field_id": "employment_status",
          "operator": "equals",
          "value": "Employed"
        }
      ]
    }
  ]
}

Operators:

  • equals, not_equals
  • contains
  • is_empty, is_not_empty
  • greater_than, less_than
  • greater_than_or_equal, less_than_or_equal

AST Structure

FormLeap stores forms as an Abstract Syntax Tree (AST):

{
  "version": "1.0",
  "steps": [
    {
      "id": "step_1",
      "title": "Personal Information",
      "fields": [
        {
          "id": "field_1",
          "type": "text",
          "label": "Full Name",
          "required": true
        },
        {
          "id": "field_2",
          "type": "email",
          "label": "Email",
          "required": true
        }
      ]
    }
  ],
  "settings": {
    "access_control": "public",
    "confirmation_message": "Thank you!"
  }
}

The AST is what you manipulate when creating or updating forms via MCP.

Example Workflows

Creating a Contact Form

Natural Language:

You: Create a simple contact form with name, email, and message fields.
     Make all fields required.

Claude: I'll create a contact form with those fields...

Explicit Schema:

You: Create a form using this schema:
     {
       "name": "Contact Form",
       "fields": [
         {"type": "text", "label": "Full Name", "required": true},
         {"type": "email", "label": "Email", "required": true},
         {"type": "textarea", "label": "Message", "required": true}
       ]
     }

Claude: Creating your contact form...

Converting PDF to Form

Upload and Convert:

You: I have a PDF job application form. Can you convert it to a digital form?
     [Attach PDF file]

Claude: I'll analyze the PDF and create a matching digital form...

        I found these fields in the PDF:
        - Full Name (text)
        - Email Address (email)
        - Phone Number (phone)
        - Resume Upload (file)
        - Cover Letter (textarea)

        Creating the form now...

        Form created: "Job Application"
        URL: https://formleap.app/f/job_123abc

The AI analyzes the PDF structure and creates matching fields automatically.

Bulk Form Operations

Create Multiple Forms:

You: Create 5 event feedback forms for:
     - Tech Conference 2025
     - Marketing Summit
     - Product Launch
     - Team Retreat
     - Customer Appreciation Day

     Each should collect name, email, rating (1-5), and comments.

Claude: I'll create all 5 forms with consistent structure...

        Created:
        1. Tech Conference 2025 Feedback
        2. Marketing Summit Feedback
        3. Product Launch Feedback
        4. Team Retreat Feedback
        5. Customer Appreciation Day Feedback

        All forms include name, email, rating, and comments fields.

Analyzing Submissions

Search and Export:

You: Search our "Customer Feedback" form for mentions of "shipping"
     and show me the results.

Claude: Searching submissions for "shipping"...

        Found 12 submissions mentioning shipping:

        1. John Doe (john@example.com): "Shipping was delayed by 3 days..."
        2. Jane Smith (jane@example.com): "Fast shipping, arrived early!"
        ...

        Would you like me to export these to CSV?

Modifying Existing Forms

Natural Language Edits:

You: Add a "Phone Number" field to the "Contact Form" after the email field.
     Make it optional.

Claude: I'll add an optional phone field after the email...

        Updated "Contact Form":
        - Full Name (required)
        - Email Address (required)
        - Phone Number (optional) ← NEW
        - Message (required)

Authentication

API Key Authentication

The simplest method for MCP integration:

{
  "env": {
    "FORMLEAP_API_KEY": "fl_key_abc123..."
  }
}

API keys have full access to your account. Keep them secure.

OAuth 2.1 (Coming Soon)

For third-party MCP servers or apps:

  1. Register your application
  2. Implement OAuth flow
  3. Receive access token
  4. Use token in API requests

OAuth provides scoped, revocable access.

Best Practices

Security

  1. Protect API keys - Never commit keys to version control
  2. Use environment variables - Store keys in secure locations
  3. Rotate keys regularly - Generate new keys every 90 days
  4. Limit scope - Use workspace-specific keys when possible
  5. Monitor usage - Review API access logs

Form Creation

  1. Start simple - Create basic forms first, add complexity later
  2. Test thoroughly - Submit test entries after creation
  3. Use templates - Reference existing forms for consistency
  4. Validate fields - Include proper validation rules
  5. Add help text - Provide context for complex fields

Performance

  1. Batch operations - Create multiple forms in one request when possible
  2. Cache form data - Don't fetch the same form repeatedly
  3. Paginate submissions - Use offset/limit for large datasets
  4. Filter queries - Use status and search filters
  5. Respect rate limits - Implement backoff strategies

Error Handling

  1. Check responses - Verify form creation success
  2. Handle failures gracefully - Retry transient errors
  3. Log errors - Track API issues for debugging
  4. Validate input - Check schemas before submission
  5. Provide feedback - Inform users of operation status

Rate Limits

MCP requests count toward API rate limits:

  • Business Plan: 1,000 requests/hour
  • Enterprise Plan: 10,000 requests/hour

Exceeded limits return HTTP 429 with retry headers:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Retry after 3600 seconds.",
  "retry_after": 3600
}

Troubleshooting

MCP Server Not Connecting

Symptoms: Claude doesn't recognize FormLeap commands

Solutions:

  1. Verify API key is correct
  2. Check config file syntax (valid JSON)
  3. Restart Claude Desktop/Code
  4. Check MCP server logs

Logs Location:

macOS:

~/Library/Logs/Claude/mcp.log

Windows:

%APPDATA%\Claude\Logs\mcp.log

Authentication Errors

Error: 401 Unauthorized

Solutions:

  1. Verify API key is valid
  2. Check key hasn't been revoked
  3. Ensure key has necessary permissions
  4. Try generating a new key

Form Creation Fails

Error: 422 Unprocessable Entity

Solutions:

  1. Validate field schema
  2. Check required fields are present
  3. Ensure field types are supported
  4. Verify workspace_id exists

Slow Responses

Symptoms: Requests taking 10+ seconds

Solutions:

  1. Reduce payload size
  2. Use pagination for large datasets
  3. Check network connectivity
  4. Contact support if persistent

Support

Resources

Contact

  • Email: support@formleap.app

What's Next?

Happy building with AI!

Previous
API Reference
Next
Webhooks