AI Forms MCP Server

SmartForm exposes a Model Context Protocol (MCP) server that AI agents use to create and manage forms. This is the primary integration surface for agent-to-human data collection.

Architecture

AI agents connect to the MCP server and invoke tools to manage forms. The MCP server translates tool calls into REST API requests to SmartForm.

AI Agent (Claude, Cursor, etc.)
    │  MCP (stdio or HTTP SSE)
    ▼
SmartForm MCP Server  ──HTTP──►  SmartForm API (smartform.dev)
    │
    ▼
SmartForm Database (PostgreSQL)

Connecting to the MCP Server

Quick Setup

The easiest way to get started is to visit our MCP Setup Guide which provides:

• One-command download for the MCP server
• Step-by-step configuration instructions
• Examples for Claude Desktop, Cursor, and Cline
• Troubleshooting tips

Manual Setup

1. Download the MCP Server

Choose one of these methods:

Using curl:

curl -o smartform-mcp.js https://www.smartform.dev/mcp-server/index.js

Using wget:

wget -O smartform-mcp.js https://www.smartform.dev/mcp-server/index.js

Direct download: Visit https://www.smartform.dev/mcp-server/index.js in your browser and save as smartform-mcp.js

2. Get Your API Key

1. Go to your Settings page
2. Click "Regenerate API Key" if needed
3. Copy your API key (starts with sf_)

3. Configure Your AI Agent

Claude Desktop:

{
  "mcpServers": {
    "smartform": {
      "command": "node",
      "args": ["/path/to/smartform-mcp.js"],
      "env": {
        "SMARTFORM_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor:

{
  "mcpServers": {
    "smartform": {
      "command": "node",
      "args": ["/path/to/smartform-mcp.js"],
      "env": {
        "SMARTFORM_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cline:

{
  "mcpServers": [
    {
      "name": "smartform",
      "command": "node",
      "args": ["/path/to/smartform-mcp.js"],
      "env": {
        "SMARTFORM_API_KEY": "your_api_key_here"
      }
    }
  ]
}

Note: Replace /path/to/smartform-mcp.js with the actual path to your downloaded file, and your_api_key_here with your actual API key from settings.

Available Tools

create_form

Create a form from A2UI JSON definition.

Input:

• a2ui_json (object, required) — A2UI v0.9.1 form definition
• title (string, optional) — Human-readable title
• expiry_days (number, optional) — Days until expiry (default: 7)
• callback_url (string, optional) — Webhook URL for submissions
• webhook_secret (string, optional) — HMAC secret for webhook signing
• post_submit_type (string, optional) — "message" or "redirect"
• post_submit_value (string, optional) — Message text or redirect URL

Returns: Form ID, hosted URL, embed code, expiry, post-submit config

get_form

Get form details and submission count.

Input:

• form_id (string, required) — Form UUID

Returns: Form details including status, A2UI JSON, submission count

get_submissions

List form submissions with pagination.

Input:

• form_id (string, required) — Form UUID
• limit (number, optional) — Max results (default: 50)
• offset (number, optional) — Pagination offset

Returns: Array of submissions with data and metadata

deactivate_form

Deactivate a form — stops accepting new submissions.

Input:

• form_id (string, required) — Form UUID

Returns: Confirmation with updated status

Example: AI Agent Creates a Feedback Form

An AI agent can use these tools to create, embed, and manage forms without writing REST code:

1. Agent calls create_form with A2UI JSON for a feedback form
2. Agent returns the embed_code to the user to paste on their website
3. User fills out the form
4. Agent calls get_submissions to retrieve responses
5. Agent processes the structured data

Environment Variables

Deployment

The MCP server runs as a local process that communicates with the SmartForm API. For most users, simply download and run the pre-built server as described in the setup guide.

Coming Soon: npm package for easier installation (npx @smartform/mcp).