# Backforms MCP Server (`backforms-mcp`)

[![npm version](https://img.shields.io/npm/v/backforms-mcp.svg?style=flat-square&color=10b981)](https://www.npmjs.com/package/backforms-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Compatible-06b6d4.svg?style=flat-square)](https://modelcontextprotocol.io)
[![Edge Ready](https://img.shields.io/badge/Edge-Sub--100ms-8b5cf6.svg?style=flat-square)](https://backforms.com)

Official **Model Context Protocol (MCP)** server for **[Backforms](https://app.backforms.com)**. Connect serverless forms, anti-spam shields, and lead telemetry directly to **Cursor**, **Windsurf**, **Claude Code**, and **Claude Desktop**.

---

## ⚡ The Zero-Click Advantage

Instead of leaving your IDE, opening a browser, manually provisioning forms, and copying IDs:

Your AI coding agent executes the complete lifecycle in a single chat prompt:
> *"Create a Contact Us form in Next.js with honeypot spam protection and connect it to Backforms"*

The agent automatically calls `create_form`, receives the live action URL (`https://app.backforms.com/f/[uuid]`), and injects ready-to-run HTML or Next.js code directly into your project.

---

## 🚀 Quick Setup

### 1. Get Your API Key
1. Sign in to your dashboard: **[Backforms Dashboard → API Keys & MCP](https://app.backforms.com/dashboard/settings/api-keys)**.
2. Click **Create API Key** and copy your secret personal access token (`bf_live_sec_...`).

---

### 2. Configure Your IDE

#### Cursor (`.cursor/mcp.json` or Settings → Features → MCP)
Add to your project's `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "backforms": {
      "command": "npx",
      "args": ["-y", "backforms-mcp"],
      "env": {
        "BACKFORMS_API_KEY": "bf_live_sec_your_token_here"
      }
    }
  }
}
```

#### Windsurf (`~/.codeium/windsurf/mcp_config.json`)
```json
{
  "mcpServers": {
    "backforms": {
      "command": "npx",
      "args": ["-y", "backforms-mcp"],
      "env": {
        "BACKFORMS_API_KEY": "bf_live_sec_your_token_here"
      }
    }
  }
}
```

#### Claude Desktop (`claude_desktop_config.json`)
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "backforms": {
      "command": "npx",
      "args": ["-y", "backforms-mcp"],
      "env": {
        "BACKFORMS_API_KEY": "bf_live_sec_your_token_here"
      }
    }
  }
}
```

#### Claude Code (CLI)
```bash
claude mcp add backforms --env BACKFORMS_API_KEY=bf_live_sec_your_token_here -- npx -y backforms-mcp
```

---

## 🛠️ Complete Tool Catalog

| Tool | Parameters | Description |
|---|---|---|
| `create_form` | `name`, `redirect_url?`, `honeypot_enabled?`, `allowed_domains?` | Provisions a new form endpoint with action URL and JSX snippets. |
| `list_forms` | `limit?`, `offset?` | Lists all forms in the workspace with throughput metrics. |
| `get_form_details` | `form_id` | Retrieves security config, access keys, and active integrations. |
| `get_form_submissions` | `form_id`, `limit?`, `status?` (`all`, `valid`, `spam`) | Retrieves leads, contact inquiries, and spam analysis. |
| `update_form_settings` | `form_id`, `name?`, `redirect_url?`, `allowed_domains?`, `is_active?` | Modifies form settings, allowed CORS origins, or custom redirects. |
| `setup_webhook` | `form_id`, `webhook_url?`, `webhook_enabled?`, `notification_email?`, `secondary_emails?` | Configures webhook endpoints and email notification routing. |
| `send_test_submission` | `form_id`, `data?` | Dispatches an authenticated test submission to verify the live pipeline. |
| `delete_form` | `form_id` | Permanently deletes a form endpoint from the workspace. |
| `check_workspace_usage` | *(none)* | Checks monthly quota consumption, spam blocked, and storage. |

---

## 🔒 Security & Privacy Architecture

- **Stateless & Serverless:** Runs locally via standard I/O (`stdio`). Zero long-lived streaming overhead.
- **SHA-256 Authentication:** Personal Access Tokens are verified with secure hash comparisons.
- **No Sensitive Credential Storage:** Tokens and database credentials are never logged or stored in plain text.
- **Strict CORS & Domain Origin Locks:** Perimeter origin restrictions protect against unauthorized cross-site form posting.

---

## 📦 Links & Community

- **SaaS Platform:** [https://backforms.com](https://backforms.com)
- **Web App Console:** [https://app.backforms.com](https://app.backforms.com)
- **NPM Package:** [https://www.npmjs.com/package/backforms-mcp](https://www.npmjs.com/package/backforms-mcp)
- **Issues & Contributions:** [https://github.com/Arneld18/backforms-mcp/issues](https://github.com/Arneld18/backforms-mcp/issues)

---

## License

MIT © [AC Softworks, LLC](https://acsoftworks.com) (contact: `info@acsoftworks.com`)