eCardWidget MCP Server #

The eCardWidget MCP server lets an AI assistant (Claude Desktop, Claude Code, Cursor, and any other Model Context Protocol client) work in your eCardWidget account on your behalf — search and send eCards, manage your directory, list campaigns/widgets/automations, and more — using an API key you generate and scope yourself.

It is built around one principle: the assistant can only ever do what your API key permits. On startup the server asks the API what the key is allowed to do (GET /v2/api/key/info) and registers only the tools that key is scoped for. A view-only key exposes read tools; a key with no directory access never even shows the directory tools. All scope enforcement, rate limiting, and audit logging happen server-side regardless of the client.

1. Generate a scoped API key #

  1. In your dashboard, go to Settings → Developers → API Keys.
  2. Click Generate API Key, give it a name (e.g. "Claude MCP"), and choose its permissions — grant only the areas you want the assistant to touch (e.g. eCards: Manage, Directory: View).
  3. Copy the key. Treat it like a password.

Tip: start least-privilege. You can always widen the key's scope later — the MCP picks up the new capabilities on its next start.

2. Install it #

Pick whichever fits your client. The server runs locally over stdio and is on npm, so there's no separate install step for the npx-based options.

Option A — Claude Desktop (one click) #

Download ecardwidget-mcp.mcpb from the releases page and open it. Claude Desktop shows an install dialog that prompts you for your API key and stores it in your operating system's keychain — no config files, no commands.

Option B — Sign in once (Claude Code, Cursor, or any client) #

Run login once; it prompts for your key, verifies it, and saves it locally (0600). Then the client command needs no key:

npx ecardwidget-mcp login
claude mcp add ecardwidget -- npx -y ecardwidget-mcp

(npx ecardwidget-mcp logout removes the saved key.)

Option C — Put the key in your client config (manual) #

{
  "mcpServers": {
    "ecardwidget": {
      "command": "npx",
      "args": ["-y", "ecardwidget-mcp"],
      "env": {
        "ECW_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Config file locations:

  • Claude Desktop: claude_desktop_config.json (Settings → Developer → Edit Config).
  • Claude Code: claude mcp add ecardwidget --env ECW_API_KEY=YOUR_API_KEY -- npx -y ecardwidget-mcp.
  • Cursor: .cursor/mcp.json in your project (or the global equivalent).

Restart the client. It will connect and show the tools your key is scoped for. An explicit ECW_API_KEY always takes precedence over a key saved via login.

Environment variables #

Variable Required Default Description
ECW_API_KEY yes — Your scoped API key (Bearer).
ECW_BASE_URL no https://app.ecardwidget.com Override only for a custom domain / testing.

3. What the assistant can do #

Tools are namespaced ecw_*. Only the ones your key is scoped for appear.

Tool Needs scope What it does
ecw_whoami (always available) Report the account + exactly what this key can do.
ecw_describe_fields (always available) List the settable fields (types/enums/required) for creating widgets, eCards, campaigns, or automations.
ecw_search_ecards ecards: view List / search your eCards.
ecw_get_widget_ecards ecards: view List the eCards in a widget (to get an ecard_id).
ecw_create_ecard ecards: manage Create an eCard (image via URL or base64) on a widget.
ecw_send_ecard ecards: manage Send, schedule, or share a single eCard.
ecw_list_widgets widgets: view List your widgets.
ecw_create_widget widgets: manage Create a new widget and configure any option.
ecw_duplicate_widget widgets: manage Create a new widget by duplicating an existing one.
ecw_list_automations automations: view List your automations.
ecw_create_automation automations: manage Create a birthday / anniversary / onboarding automation.
ecw_list_campaigns campaigns: view List your campaigns.
ecw_list_team_members directory: view List / search directory members.
ecw_find_team_member directory: view Look up one member by email / external id.
ecw_upsert_team_member directory: manage Add or update one member.
ecw_import_team_members directory: manage Bulk add/update members (throttle-aware).
ecw_deactivate_team_member directory: manage Deactivate a member (reversible).
ecw_delete_team_member directory: manage Permanently delete a member (two-step confirm).
ecw_delete_widget widgets: manage Permanently delete a widget (two-step confirm).
ecw_delete_ecard ecards: manage Permanently delete an eCard (two-step confirm).
ecw_create_campaign campaigns: manage Create a campaign as a draft (does not send).
ecw_send_campaign campaigns: manage Send a campaign to all recipients (two-step confirm).

Destructive actions use a two-step confirmation: call once for a preview + a one-time token, then again with the token to execute. Deleting automations or campaigns, and sending gift-card campaigns, requires confirmation in the dashboard for security — the tools will tell you when that applies.

Ask naturally, e.g. "Send a birthday eCard from our Thank-You widget to [email protected]" or "Import these 20 new hires into the directory." The assistant will call ecw_whoami to see what it can do, then chain the right tools.

Security model #

  • Least privilege by construction — the key's scope is the ceiling; the server registers only permitted tools and the API rejects anything out of scope (403).
  • Rate limited — each key is throttled (120 req/min by default); the server backs off on 429.
  • Audited — every key use is logged server-side (usage + audit trail), same as any API call.
  • No secret exposure — the API key is read from the environment and never logged; /key/info never returns key values.
  • Destructive actions are gated — high-blast-radius operations (bulk sends, deletes) require an explicit two-step confirmation (a dry-run preview first, then a confirmation token).

Programmatic introspection (no MCP required) #

Any API consumer can discover its own scope with the same endpoint the MCP uses:

curl "https://app.ecardwidget.com/v2/api/key/info" \
  -H "Authorization: Bearer $ECW_API_KEY"

See the API reference (GET /key/info) for the full response shape.

← PreviousDeveloper PortalNext →Send an eCard
Documentation
Getting Started