Setup guide

Connect Askery to any AI agent

One API key, twelve agents. Pick yours below, paste the snippet, restart, done. The whole Askery surface - 29 MCP tools covering forms, responses, AI generation, intelligence, webhooks, and workspace secrets - becomes available inside the agent.

Mint your API key →See the REST API

1Mint an API key (every agent needs this)

Go to /dashboard/api-keys.
Pick scopes. For a general MCP integration we suggest forms:read, forms:write, responses:read, and ai:run. Add webhooks:write / secrets:write if the agent will manage those too.
Copy the key. It looks like ak_live_…. You see it once - save it to your password manager now.

One key, every agent. The same ASKERY_API_KEY env var works in every config below. You don't need a separate key per IDE.

2Verify the key works (30 seconds)

Before pasting the key into an agent config, prove it works with a one-liner. This catches typos, scope mismatches, and revoked keys before they turn into mysterious agent errors.

bash
curl -s https://askery.app/api/v1/workspace \
  -H "Authorization: Bearer ak_live_..." \
  | jq .

You should see your workspace name, plan, and credit balance. If you see { error: { code: "invalid_token" } } the key is wrong; if you see insufficient_scope mint a new key with the right scopes.

New

ChatGPT (web) and Claude.ai - remote MCP

Browser agents can't spawn local processes, so they connect to a remote MCP endpoint over HTTPS and authenticate via OAuth. No install, no env vars - paste this URL into your agent's connector UI and click through the consent screen.

Remote MCP URL

https://askery.app/api/mcp

ChatGPT (Pro / Teams / Enterprise)

1. Settings → Connectors → Add a custom connector
2. Paste https://askery.app/api/mcp
3. Sign in to Askery when prompted
4. Pick which tools to enable + confirm

Claude.ai (Pro / Team / Enterprise)

1. Settings → Connectors → Add custom
2. Paste https://askery.app/api/mcp
3. Authenticate via the OAuth consent screen
4. Use it in any conversation: “Build me a 3-question NPS form on Askery.”

How auth works:The agent dynamically registers itself with our OAuth server (RFC 7591), PKCE-protects the code grant (RFC 7636), and binds the issued token to this MCP resource (RFC 8707). You see a normal Askery consent screen - Allow once and you're done. Same scope model as the API keys above, same audit log, same per-tool consent.

3Or set up a local agent

Claude Desktop Claude Code Cursor VS Code (GitHub Copilot)Windsurf (Cascade)Cline Continue.dev Zed Goose (Block)JetBrains AI Assistant OpenAI Codex CLI Gemini CLI

Claude Desktop

Anthropic's reference client. Every snippet below is a variant of this one.

Official docs

Where it lives

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Config file

json
{
  "mcpServers": {
    "askery": {
      "command": "npx",
      "args": ["-y", "@askeryforms/mcp"],
      "env": {
        "ASKERY_API_KEY": "ak_live_..."
      }
    }
  }
}

Gotcha: Fully quit Claude (Cmd+Q) and relaunch. A single JSON syntax error silently disables every server. Logs: ~/Library/Logs/Claude/mcp*.log

Claude Code

Anthropic's terminal agent. Use the CLI; project-scope writes to ./.mcp.json so the team picks it up.

Official docs

Where it lives

./.mcp.json (project scope) or ~ via `claude mcp add`

Quick install (CLI)

bash
claude mcp add --transport stdio --scope user \
  --env ASKERY_API_KEY=ak_live_... \
  askery -- npx -y @askeryforms/mcp

Equivalent config file

bash
{
  "mcpServers": {
    "askery": {
      "command": "npx",
      "args": ["-y", "@askeryforms/mcp"],
      "env": {
        "ASKERY_API_KEY": "ak_live_..."
      }
    }
  }
}

Gotcha: Flags (--transport, --env, --scope) MUST come before the server name. Everything after `--` is the literal spawn command. Verify with `claude mcp list`.

Cursor

Cursor reads the same JSON shape as Claude Desktop. Project scope is the right choice for teams.

Official docs

Where it lives

Project: ./.cursor/mcp.json  ·  Global: ~/.cursor/mcp.json

Config file

json
{
  "mcpServers": {
    "askery": {
      "command": "npx",
      "args": ["-y", "@askeryforms/mcp"],
      "env": {
        "ASKERY_API_KEY": "ak_live_..."
      }
    }
  }
}

Gotcha: After editing, run Cmd+Shift+P → Reload Window. Cursor has a ~40 active-tool ceiling across ALL MCP servers - past it, tools silently drop.

VS Code (GitHub Copilot)

Different root key (`servers`, not `mcpServers`), `type: stdio` required, and a slick prompted-secret pattern via `inputs`.

Official docs

Where it lives

Workspace: ./.vscode/mcp.json  ·  User: Command Palette → MCP: Open User Configuration

Config file

json
{
  "servers": {
    "askery": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@askeryforms/mcp"],
      "env": {
        "ASKERY_API_KEY": "${input:askery-api-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "askery-api-key",
      "description": "Askery API key (ak_live_...)",
      "password": true
    }
  ]
}

Gotcha: Root key is `servers`, not `mcpServers`. `type: "stdio"` is required. Use `${input:...}` so the key is never committed.

Windsurf (Cascade)

Same shape as Claude Desktop. Supports `${env:VAR}` and `${file:/path}` for secret-from-disk.

Official docs

Where it lives

macOS/Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

Config file

json
{
  "mcpServers": {
    "askery": {
      "command": "npx",
      "args": ["-y", "@askeryforms/mcp"],
      "env": {
        "ASKERY_API_KEY": "${env:ASKERY_API_KEY}"
      }
    }
  }
}

Gotcha: File and parent directory are NOT created on first launch. Create them manually. The `${env:VAR}` interpolation reads from your shell environment at launch.

Cline

Adds `disabled` and `autoApprove` fields on top of the standard shape. Keep `autoApprove` empty unless you really trust a tool.

Official docs

Where it lives

Cline panel → MCP Servers icon → Configure → 'Configure MCP Servers'

Config file

json
{
  "mcpServers": {
    "askery": {
      "command": "npx",
      "args": ["-y", "@askeryforms/mcp"],
      "env": {
        "ASKERY_API_KEY": "ak_live_..."
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Gotcha: Always edit via the in-extension button - the file path varies by extension version and global-storage location. `autoApprove: []` means every tool call is confirmed; safer.

Continue.dev

Continue is the odd one: drop a YAML (or JSON) file into a folder and it auto-discovers. Works only in Agent mode.

Official docs

Where it lives

./.continue/mcpServers/askery.yaml - every file in that folder is auto-loaded.

Config file

yaml
name: Askery
version: 0.0.1
schema: v1
mcpServers:
  - name: askery
    type: stdio
    command: npx
    args:
      - "-y"
      - "@askeryforms/mcp"
    env:
      ASKERY_API_KEY: ${{ secrets.ASKERY_API_KEY }}

Gotcha: MCP only works in Agent mode - Chat and Edit ignore it. Secrets use `${{ secrets.NAME }}` syntax (double-brace), not the `${env:...}` other clients use.

Zed

Zed names them 'context servers'. No manual restart - it respawns on file save.

Official docs

Where it lives

User: ~/.config/zed/settings.json  ·  Project: ./.zed/settings.json  ·  Or: Command Palette → 'zed: open settings'

Config file

json
{
  "context_servers": {
    "askery": {
      "command": "npx",
      "args": ["-y", "@askeryforms/mcp"],
      "env": {
        "ASKERY_API_KEY": "ak_live_..."
      }
    }
  }
}

Gotcha: Root key is `context_servers`. Tools are namespaced as `mcp:askery:<tool>` in Zed's tool-permission settings.

Goose (Block)

Field names differ: `cmd` not `command`, `envs` not `env`, and the root key is `extensions`.

Official docs

Where it lives

~/.config/goose/config.yaml

Quick install (CLI)

bash
goose configure  # interactive: 'Add Extension' → 'Command-line Extension'

Equivalent config file

yaml
extensions:
  askery:
    name: Askery
    type: stdio
    cmd: npx
    args:
      - "-y"
      - "@askeryforms/mcp"
    envs:
      ASKERY_API_KEY: ak_live_...
    enabled: true
    timeout: 300

Gotcha: Three field-name traps: `cmd` (not command), `envs` (not env), and the root key is `extensions` (not mcpServers). Restart Goose after editing.

JetBrains AI Assistant

IntelliJ / PyCharm / WebStorm / GoLand etc. Pasted as JSON inside an IDE settings dialog.

Official docs

Where it lives

Settings | Tools | AI Assistant | Model Context Protocol (MCP)

Config file

json
{
  "mcpServers": {
    "askery": {
      "command": "npx",
      "args": ["-y", "@askeryforms/mcp"],
      "env": {
        "ASKERY_API_KEY": "ak_live_..."
      }
    }
  }
}

Gotcha: Two pages have similar names: AI Assistant → MCP (client, what you want) and MCP Server (lets external agents drive the IDE - different thing). Requires 2025.2+.

OpenAI Codex CLI

TOML, not JSON. Section header is `[mcp_servers.NAME]` and env vars get a nested table.

Official docs

Where it lives

~/.codex/config.toml

Quick install (CLI)

bash
codex mcp add askery -- npx -y @askeryforms/mcp

Equivalent config file

toml
[mcp_servers.askery]
command = "npx"
args = ["-y", "@askeryforms/mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 60
enabled = true

[mcp_servers.askery.env]
ASKERY_API_KEY = "ak_live_..."

Gotcha: TOML. Underscore + plural in `[mcp_servers.NAME]`. To forward a host env var instead of hard-coding, use `env_vars = ["ASKERY_API_KEY"]` at the server level.

Gemini CLI

Same JSON shape as Claude Desktop, but Gemini CLI sanitises the host environment - you must explicitly forward env vars.

Official docs

Where it lives

Global: ~/.gemini/settings.json  ·  Project: ./.gemini/settings.json

Config file

json
{
  "mcpServers": {
    "askery": {
      "command": "npx",
      "args": ["-y", "@askeryforms/mcp"],
      "env": {
        "ASKERY_API_KEY": "$ASKERY_API_KEY"
      },
      "timeout": 30000,
      "trust": false
    }
  }
}

Gotcha: Gemini CLI redacts most host env vars by default. Reference them in the `env` block with bare `$VAR` so they get forwarded. Keep `trust: false` so each tool call is confirmed.

When it doesn't work

Agent says "server didn't respond" / tools never appear. Open the agent's MCP log (path varies - Claude Desktop: ~/Library/Logs/Claude/mcp*.log; Cursor: View → Output → MCP). The first stderr line tells you what's wrong - usually the env var didn't get through.
invalid_token on every call. The agent is forwarding a different env var than you set. Check the config's env block - it must contain "ASKERY_API_KEY": "ak_live_…" as a literal string (or use the agent's interpolation syntax - see the per-agent gotcha).
insufficient_scope on a specific tool. Your key doesn't carry the scope that tool needs. Either mint a new key with the right scope or stop calling that tool. The MCP tool description tells you the required scope.
The agent picks npx from a weird PATH. Some agents launch their server with a stripped PATH (no Volta / nvm / Bun shims). If npx isn't reachable, use an absolute path: /usr/local/bin/npx on macOS with the official Node installer.
Cursor says "tool ceiling exceeded." Cursor caps active MCP tools across all servers at ~40. Disable other servers you don't need or split the Askery server into smaller scoped instances using two API keys.

From source (no npm publish)

If your agent host can't reach the npm registry, or you want to run a development build, clone the repo and point the agent at the local file.

bash
git clone https://gitlab.com/ambasync/askery.git
cd askery/mcp
bun install
echo "Then point the agent at: `bun /full/path/to/askery/mcp/server.ts`"

Replace npx -y @askeryforms/mcp in any snippet above with bun /full/path/to/askery/mcp/server.ts (use node /…/dist/server.jsif your host doesn't have Bun).

1Mint an API key (every agent needs this)

2Verify the key works (30 seconds)

ChatGPT (web) and Claude.ai - remote MCP

3Or set up a local agent

When it doesn't work

From source (no npm publish)

Keep exploring