# MCP server

Connect AI agents to Form Plume with the official MCP server, or point any tool generator at the OpenAPI spec that describes the whole Form Plume API.

The [Form Plume API](/docs/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](https://formplume.com/skills/form-plume-api/SKILL.md)
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](/docs/api/authentication). 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:

```json
{
  "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:

```bash
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:

```bash
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:

```toml
[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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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`](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](/docs/api-reference).