# MCP server & API keys

Connect Claude, Cursor, VS Code, n8n AI agents or any Model Context Protocol client to your organization, with a scoped API key.

## What you can do

The form2wf MCP server gives an AI agent the same abilities you have in the dashboard, limited to one organization and one access level. Useful prompts:

-   “Create a job application form with a résumé upload that posts to https://n8n.example.com/webhook/jobs, then give me the embed code.”
-   “Which forms had failed submissions this week, and what did n8n return?”
-   “Add a required phone field after the email field on the contact form.”
-   “Build a customer list page from my list-customers webhook with Edit and Delete actions.”
-   “Create a Brand theme with primary #0f766e and apply it to every form.”

## Server details

<table><tbody><tr><td>Endpoint</td><td><code>https://form2wf.com/mcp</code></td></tr><tr><td>Transport</td><td>Streamable HTTP, stateless (<code>POST</code> only; no SSE stream, no session)</td></tr><tr><td>Authentication</td><td><code>Authorization: Bearer f2w_…</code> (or <code>X-API-Key: f2w_…</code>)</td></tr><tr><td>Tools</td><td>24 — see the <a href="https://form2wf.com/docs/mcp-tools">tool reference</a></td></tr><tr><td>Rate limit</td><td>60 requests per minute per key owner</td></tr></tbody></table>

## Creating an API key

1.  In the dashboard, open **API Keys** in the sidebar. You must be an organization **admin** or **owner**.
    
2.  Click **Create API Key**, name it after where it will be used (“Claude Code — laptop”, “n8n reporting agent”), and choose an access level.
    
3.  Copy the key. It is shown **once** — form2wf stores only a hash. The dialog also shows a ready-to-paste Claude Code command.
    

### Access levels

| Level | Acts as | Can |
| --- | --- | --- |
| viewer | User | Read forms and their config, webhook call history, usage, folders, themes, roles, form users, form access; get embed snippets. |
| editor | Creator | Viewer, plus create and update forms (fields, layout, webhooks, active flag) and manage folders. |
| admin | Admin | Editor, plus delete forms, change form access, create and update themes, create form users and assign them to forms. |

A key acts as the member who created it, and **never exceeds that member's current role**: demote them and their admin keys drop to their new level; remove them from the organization and their keys stop working. No key can create, list or revoke API keys, manage the team or touch billing.

### Revoking a key

Click the trash icon next to a key on the API Keys page. Revocation is immediate and permanent. The page shows each key's preview (`f2w_1a2b…9f0e`), creator and last-used time, so you can spot unused keys.

## Connecting a client

**Claude Code**

terminal:

```bash
claude mcp add --transport http form2wf https://form2wf.com/mcp \
  --header "Authorization: Bearer f2w_your_key_here"
```

Add `--scope user` to make it available in every project, or `--scope project` to share it through `.mcp.json` (keep the key itself out of version control — see below). Check with `claude mcp list`, then ask Claude to “run whoami on form2wf”.

Install the [form2wf Claude Code skill](https://form2wf.com/docs/claude-skill) too — it teaches Claude the safe editing sequence and the gotchas.

**Claude Desktop**

Edit `claude_desktop_config.json` (Settings → Developer → Edit Config) and restart Claude Desktop. Requires Node.js.

claude_desktop_config.json:

```json
{
  "mcpServers": {
    "form2wf": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://form2wf.com/mcp", "--header", "Authorization:${F2W_AUTH}"],
      "env": { "F2W_AUTH": "Bearer f2w_your_key_here" }
    }
  }
}
```

The header value lives in `env` because some systems split arguments containing spaces.

**Cursor**

~/.cursor/mcp.json:

```json
{
  "mcpServers": {
    "form2wf": {
      "url": "https://form2wf.com/mcp",
      "headers": { "Authorization": "Bearer f2w_your_key_here" }
    }
  }
}
```

**VS Code**

VS Code can prompt for the key instead of storing it in the file:

.vscode/mcp.json:

```json
{
  "inputs": [
    { "type": "promptString", "id": "f2w-key", "description": "form2wf API key", "password": true }
  ],
  "servers": {
    "form2wf": {
      "type": "http",
      "url": "https://form2wf.com/mcp",
      "headers": { "Authorization": "Bearer ${input:f2w-key}" }
    }
  }
}
```

**n8n AI Agent**

Add an **MCP Client Tool** node to an AI Agent:

| Field | Value |
| --- | --- |
| Endpoint | `https://form2wf.com/mcp` |
| Server Transport | HTTP Streamable |
| Authentication | Header Auth — name `Authorization`, value `Bearer f2w_…` |

See [n8n recipes](https://form2wf.com/docs/n8n-recipes#agent-mcp) for an example.

**Other / raw HTTP**

Any client that supports remote Streamable HTTP servers with custom headers works. To test from a terminal:

curl:

```bash
curl -s https://form2wf.com/mcp \
  -H "Authorization: Bearer f2w_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}'
```

Because the server is stateless, every request stands alone — `initialize` is optional for raw calls.

## Security

-   **Least privilege:** reporting and support agents get viewer. Use admin only for agents that must delete forms or manage access.
-   **One key per agent or machine**, named clearly, so you can revoke one without breaking the others.
-   **Keep keys out of git.** Use your client's secret/prompt features or environment variables. If a key leaks, revoke it and create a new one.
-   **Secrets stay hidden:** webhook header values are never returned through MCP — tools show `[redacted]`, and writing the placeholder back is rejected so an agent can't wipe a real secret.
-   **Review destructive actions:** most clients ask before running tools; approve `delete_form` and `set_form_access` deliberately.

## Troubleshooting

| Symptom | Cause and fix |
| --- | --- |
| HTTP 401, “API key required” | No key sent, or the header isn't `Authorization: Bearer f2w_…` / `X-API-Key`. |
| HTTP 401, “invalid or has been revoked” | Typo, or the key was revoked. Create a new one. |
| HTTP 403 on connect | The key's creator left the organization or was deactivated. Create a new key as a current admin. |
| Tool result with status 403 | The key's access level (or its creator's role) is too low for that tool. |
| HTTP 405 | The client tried to open an SSE stream (`GET`). Use a client with Streamable HTTP support, or `mcp-remote`. |
| HTTP 429 | More than 60 requests a minute. Slow the agent down. |
| `FORM_QUOTA_EXCEEDED` | Your plan's form limit is reached. See [Plans & limits](https://form2wf.com/docs/limits). |

---
Source: https://form2wf.com/docs/mcp — Form2Workflow documentation (AI agents)