MCP server: manage forms with AI agents

The Form Plume API is built to be driven by AI agents. You can wire one up two ways: the official MCP server, which exposes the API surface as ready-made tools, or the OpenAPI spec, which any tool generator or agent framework can consume directly. Give the agent the form-plume-api skill for the routing, scope, secret-handling, and verification rules that apply to both approaches.

The official MCP server

@formplume/mcp is a Model Context Protocol server that runs over stdio. It exposes forms, submissions, analytics, webhooks, integrations, spam controls, and blocklists as tools.

Before you connect

You need Node 20+ and an organization API key. Set the key as FORMPLUME_API_KEY when you configure the server. Use a read-scope key for reporting and triage, or a full-scope key when the agent needs to create or change resources.

@formplume/mcp does not load a project's .env file. Put the key in the MCP server's own env configuration or use the client's --env setup option, as shown below. This makes the configured key independent of whichever shell or desktop environment happened to launch the client.

The agent can do whatever the key allows. Start with a read-scope key, then switch to a full-scope key only when the workflow needs write access.

Claude Desktop

Open Claude Desktop's developer settings, edit claude_desktop_config.json, and add:

{
  "mcpServers": {
    "formplume": {
      "command": "npx",
      "args": ["-y", "@formplume/mcp"],
      "env": {
        "FORMPLUME_API_KEY": "fp_sk_live_..."
      }
    }
  }
}

Restart Claude Desktop after saving the file. Form Plume will appear in the available MCP tools.

Claude Code

Run this command in your terminal:

claude mcp add formplume --env FORMPLUME_API_KEY=fp_sk_live_... -- npx -y @formplume/mcp

Open a Claude Code session and run /mcp to confirm that formplume is connected.

Codex

Codex CLI, the IDE extension, and the ChatGPT desktop app share the same MCP configuration. Add Form Plume from your terminal:

codex mcp add formplume --env FORMPLUME_API_KEY=fp_sk_live_... -- npx -y @formplume/mcp

Run codex mcp list to check the connection, or enter /mcp inside a Codex session. You can also add the same stdio server from Settings → MCP servers in the IDE extension or ChatGPT desktop app.

In a hand-written Codex config.toml, use the server's env table rather than env_vars = ["FORMPLUME_API_KEY"]. env_vars forwards the value Codex inherited when it launched; it does not read .env, and a desktop app can therefore keep forwarding an older key even after .env changes.

The equivalent hand-written configuration is:

[mcp_servers.formplume]
command = "npx"
args = ["-y", "@formplume/mcp"]
 
[mcp_servers.formplume.env]
FORMPLUME_API_KEY = "fp_sk_live_..."

Cursor

Open Cursor Settings → MCP → Add new global MCP server, then add:

{
  "mcpServers": {
    "formplume": {
      "command": "npx",
      "args": ["-y", "@formplume/mcp"],
      "env": {
        "FORMPLUME_API_KEY": "fp_sk_live_..."
      }
    }
  }
}

You can use the same entry in a project-level .cursor/mcp.json when the server should only be available in that project.

Visual Studio Code

Create .vscode/mcp.json in your project. This version prompts for the key instead of saving it in the repository:

{
  "servers": {
    "formplume": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@formplume/mcp"],
      "env": {
        "FORMPLUME_API_KEY": "${input:formplume-api-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "formplume-api-key",
      "description": "Form Plume organization API key",
      "password": true
    }
  ]
}

Run MCP: List Servers from the Command Palette and start formplume.

Windsurf

Open Windsurf Settings → Cascade → MCP Servers → Add custom server and use:

{
  "mcpServers": {
    "formplume": {
      "command": "npx",
      "args": ["-y", "@formplume/mcp"],
      "env": {
        "FORMPLUME_API_KEY": "fp_sk_live_..."
      }
    }
  }
}

Zed

Open your Zed settings and add a custom context server:

{
  "context_servers": {
    "formplume": {
      "command": "npx",
      "args": ["-y", "@formplume/mcp"],
      "env": {
        "FORMPLUME_API_KEY": "fp_sk_live_..."
      }
    }
  }
}

Other MCP clients

Use these values in any client that supports local stdio servers:

Command: npx
Arguments: -y @formplume/mcp
Environment variable: FORMPLUME_API_KEY=fp_sk_live_...

If you are connecting to a local API during development, set FORMPLUME_API_URL as well. It defaults to https://api.formplume.com.

Rotate or replace a key

Replace FORMPLUME_API_KEY in the MCP server configuration, then fully restart the client so it starts a new MCP process. A new chat alone may keep the existing process and its old environment. Use whoami after restarting to verify the key name, scope, and organization before running other tools.

Try it

Once connected, ask your agent to:

“Check which Form Plume organization this key belongs to.”
“List my forms and show their submission counts.”
“Create a form named Contact with the mailbox emoji.”
“Find unread submissions for the Contact form that mention pricing.”
“Star those submissions and export them as CSV.”
“Show failed webhook deliveries for this form and redeliver the latest one.”
“Give me this month's submission usage and the submission trend for the last 30 days.”

Using the OpenAPI spec directly

If you would rather generate your own tools or client, use the spec at https://api.formplume.com/v1/openapi.json. It describes every endpoint, every field, and every accepted value. The API serves it itself, so it can never drift from what is deployed. The same spec powers the interactive API Reference.

MCP server