MCP

Connect Voiceform to AI assistants with the Model Context Protocol (MCP). The Voiceform MCP server runs locally on your machine (stdio). Clients like Cursor, Claude Desktop, Claude Code, VS Code, Windsurf, and Gemini CLI spawn it and talk over stdin/stdout.

📘

ChatGPT and many hosted Gemini surfaces only support remote (HTTP) MCP today — they cannot launch this local server. See ChatGPT and Limitations.

Prerequisites

1. Node.js 18+ — run node -v
2. Voiceform API access — your plan must include API access
3. API token — Dashboard → Account → API Tokens → Create token
   Copy it once (it is not shown again). The token needs the public-api-call ability.

Install the MCP server

Install once on the machine where your AI client runs:

cd /path/to/voiceform-api
npm install

Remember the absolute path to that folder (every client config needs it), for example:

• macOS/Linux: /Users/you/voiceform-api
• Windows: C:\Users\you\voiceform-api

Smoke check:

VOICEFORM_API_TOKEN=your-token npm start
# Should start quietly (stdio). Ctrl+C to stop.

Shared server block

Every stdio client uses the same idea: run node on src/index.js with your token.

{
  "voiceform": {
    "command": "node",
    "args": ["/ABSOLUTE/PATH/TO/voiceform-api/src/index.js"],
    "env": {
      "VOICEFORM_API_TOKEN": "vf_xxxxxxxx",
      "VOICEFORM_API_BASE": "https://app.voiceform.com/api/v1"
    }
  }
}

Replace /ABSOLUTE/PATH/TO/voiceform-api and vf_xxxxxxxx.
Omit VOICEFORM_API_BASE to use production; set it only if you need a non-production API base.

Cursor

1. Open Cursor Settings → MCP (or Features → MCP)
2. Click Add new MCP server / edit config
3. Paste the server under mcpServers

Config files

{
  "mcpServers": {
    "voiceform": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/voiceform-api/src/index.js"],
      "env": {
        "VOICEFORM_API_TOKEN": "vf_xxxxxxxx",
        "VOICEFORM_API_BASE": "https://app.voiceform.com/api/v1"
      }
    }
  }
}

4. Save → ensure the server shows green / connected
5. Use Agent chat and ask: “List my Voiceform memberships”

If the server fails to start, run npm install in the MCP folder and use an absolute path in args.

Claude Desktop

Config file

{
  "mcpServers": {
    "voiceform": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/voiceform-api/src/index.js"],
      "env": {
        "VOICEFORM_API_TOKEN": "vf_xxxxxxxx",
        "VOICEFORM_API_BASE": "https://app.voiceform.com/api/v1"
      }
    }
  }
}

Fully quit Claude Desktop and reopen. Confirm tools appear under the hammer / MCP indicator. Ask: “Use Voiceform to list my memberships.”

GUI apps often lack your shell PATH. If node is not found, set command to the full binary (for example /usr/local/bin/node or the output of which node).

Claude Code

Recommended

claude mcp add voiceform --scope user -- \
  node /ABSOLUTE/PATH/TO/voiceform-api/src/index.js

Then set the token in your environment (or client env UI):

export VOICEFORM_API_TOKEN=vf_xxxxxxxx
export VOICEFORM_API_BASE=https://app.voiceform.com/api/v1

Or add a project .mcp.json (do not commit tokens):

{
  "mcpServers": {
    "voiceform": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/voiceform-api/src/index.js"],
      "env": {
        "VOICEFORM_API_TOKEN": "vf_xxxxxxxx"
      }
    }
  }
}

Verify:

claude mcp list

VS Code

Project file: .vscode/mcp.json
(Note: the root key is often servers, and type may be required.)

{
  "servers": {
    "voiceform": {
      "type": "stdio",
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/voiceform-api/src/index.js"],
      "env": {
        "VOICEFORM_API_TOKEN": "vf_xxxxxxxx",
        "VOICEFORM_API_BASE": "https://app.voiceform.com/api/v1"
      }
    }
  }
}

Reload the window, enable the MCP server in Copilot chat, then try listing memberships.

Windsurf

Global config is typically under Windsurf’s MCP settings / ~/.codeium/windsurf/mcp_config.json (path may vary by version). Use the same mcpServers.voiceform block as Cursor.

Gemini

Gemini CLI (local)

Config lives in settings JSON:

{
  "mcpServers": {
    "voiceform": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/voiceform-api/src/index.js"],
      "cwd": "/ABSOLUTE/PATH/TO/voiceform-api",
      "env": {
        "VOICEFORM_API_TOKEN": "vf_xxxxxxxx",
        "VOICEFORM_API_BASE": "https://app.voiceform.com/api/v1"
      }
    }
  }
}

Or via CLI:

gemini mcp add --scope user voiceform \
  node /ABSOLUTE/PATH/TO/voiceform-api/src/index.js

export VOICEFORM_API_TOKEN=vf_xxxxxxxx
gemini mcp list

Prefer putting the token in env inside settings.json (user scope) rather than committing it.

Gemini / AI Studio web apps

Remote connectors only in most hosted UIs — this local stdio server will not attach there until a hosted MCP URL is available.

ChatGPT

Not plug-and-play with the local MCP server today.

ChatGPT’s MCP support expects a hosted HTTP MCP endpoint (often with OAuth), not a local node src/index.js process.

Options:

1. Use Cursor / Claude Desktop / Claude Code / VS Code with this local server (recommended now)
2. Call the Public REST API directly from Custom GPTs / Actions

Quick verification

After connecting any client:

1. Server status is connected / no spawn error
2. Tools include at least list_memberships, list_surveys, create_question
3. Prompt: “Call list_memberships on Voiceform”
4. You get team/membership JSON back (not HTTP 401/403)

Limitations

• Local only (stdio) — not a public URL; ChatGPT / many cloud Gemini UIs cannot attach it directly
• Token in config — treat like a password; prefer user-level config over committed project files

Security tips

• Never commit VOICEFORM_API_TOKEN
• Revoke tokens from the Voiceform dashboard if a machine or config leaks
• Use the narrowest machine that needs survey write access

Related

• API Reference — REST endpoints the MCP tools call
• Webhooks — push completions to your own HTTPS endpoint