@wa-campaigns/agent-toolkit

@wa-campaigns/agent-toolkit

WhatsApp-branded agent skins for the agent gateway (/api/agent/*): an MCP server (wa-mcp) and a CLI (wa).

Renamed. This package was published as @wa-templates/agent-toolkit up to and including 0.1.4, when the product became WhatsApp Campaigns (MSG-1867). Same bins, same tool catalog, same gateway — only the scope changed. The old package is deprecated and stops at 0.1.4; install this one.

This package is a thin alias over @rcs-campaigns/agent-toolkit. There is no second implementation — same gateway, same tool catalog, same client, same build. Each bin here is a single require() into that package.

The only difference is what "unspecified" means. Launched as wa / wa-mcp, the process defaults the channel to WhatsApp and prefers WA_* environment variables. Launched as rcs / rcs-mcp, it leaves the channel to the server — which falls back to your org's own brand channel. An explicit channel argument always wins, and both environment prefixes are accepted under either bin.

Use this package if you think in WhatsApp. Use @rcs-campaigns/agent-toolkit if you think in RCS. They are interchangeable.

Setup

1. Get an agent key

In the app: Settings → API keys → Create key (Admin only). Pick the scopes the agent needs, then copy the key — it is shown exactly once (rcsk_live_…). Treat it like a password; revoke and rotate from the same screen.

The rcsk_ prefix is not a mistake. A key authenticates an org, and an org can drive both WhatsApp and RCS — the channel is chosen per call, so there is one key shape for both.

2. Set your key

export WA_AGENT_KEY=rcsk_live_…

That's all the configuration production needs — the toolkit talks to the hosted gateway by default. Set WA_GATEWAY_URL (or pass --url) only to target dev or a local gateway.

RCS_GATEWAY_URL / RCS_AGENT_KEY work too. When both are set, the pair matching the bin you ran wins.

A key is tied to the environment it was minted in — a key from one environment 401s against another (different databases).

3. Run it

This package ships two bins (wa and wa-mcp) and neither is named agent-toolkit, so under npx you must name the package with -p and the bin after it:

npx -y -p @wa-campaigns/agent-toolkit wa capabilities

Without -p, npx looks for a bin called agent-toolkit, finds none, and fails with "could not determine executable to run".

Or install globally and call the bins directly:

npm i -g @wa-campaigns/agent-toolkit
wa capabilities
wa-mcp              # stdio MCP server

MCP server

Listed in the official MCP Registry as com.wa-campaigns/whatsapp-campaigns, so hosts that browse the registry can install it without being told the package name.

Register wa-mcp with any MCP host. For Claude Code:

claude mcp add wa-campaigns \
  --env WA_AGENT_KEY=rcsk_live_… \
  -- npx -y -p @wa-campaigns/agent-toolkit wa-mcp

The gateway's tools then appear natively in the agent. Call capabilities first: it returns the full catalog plus the scopes your key actually holds, so the agent can plan against what it is allowed to do rather than against documentation.

CLI

JSON in, JSON out — it composes with jq, drops into CI, and works as a step in a shell-driven agent loop.

wa capabilities
wa search "appointment reminder" --category EVENTS --sort rating
wa get <id>
wa render <id> --var firstName=Ada
wa create --file template.json
wa clone <id>
wa submit <id>
wa send <blueprintId> --to [phone] --var firstName=Ada
wa usage

# Surveys
wa surveys [query] [--status ACTIVE]
wa survey get <id>
wa survey send-test <id> --to [phone]
wa survey send <id> --audience <audienceId>
wa survey results <id>

# Grounding knowledge
wa knowledge <id> --get | --set-file doc.md | --delete | --enable | --disable

Run wa --help for the full list. Config flags override the environment: --url, --key, --channel.

The CLI covers the common path. Some gateway calls — audience management and template update/duplicate/delete — are available over HTTP and MCP but have no CLI verb yet.

Library use

const { GatewayClient, TOOLS } = require('@wa-campaigns/agent-toolkit');

const client = GatewayClient.fromEnv({ defaultChannel: 'WHATSAPP' });
const { items } = await client.call({
  method: 'GET',
  path: '/templates',
  query: { q: 'promo' }
});

Imported as a library there is no bin name to read, so no channel is assumed — pass defaultChannel (or a per-call channel) if you want one.

Sending is real

send_message, send_survey, and send_survey_test deliver to actual phone numbers, bill your org, and cannot be undone. Rehearse with send_survey_test, and note that a template only delivers as rich WhatsApp once it has been submitted and provider-approved — until then it falls back to SMS.

Docs

Full API reference, including every endpoint's arguments and an OpenAPI document: https://www.wa-campaigns.com/docs