Connect approved AI clients to Whatsly

Before you start

MCP access connects an AI-capable client to real Whatsly functions. Confirm the plan feature, device and permissions before adding the server.

• Use an MCP-compatible client that supports local stdio servers.
• Connect and verify the WhatsApp device in Whatsly.
• Enable MCP access for the workspace plan where required.
• Create a dedicated API key with only the required send, read or device-status scopes.
• Use a test recipient and a review process before allowing customer-facing messages.

Install the server

The package can be run by an MCP-compatible client through npx. Keep the package definition in the client configuration and keep secrets in environment values.

npx -y @whatsly/mcp-server

Configure your MCP client

Copy the API base URL, key identifier, secret and default device identifier from your own Whatsly workspace. Do not commit real credentials to a repository.

{
  "mcpServers": {
    "whatsly": {
      "command": "npx",
      "args": ["-y", "@whatsly/mcp-server"],
      "env": {
        "WHATSLY_API_BASE_URL": "<copy-from-your-workspace>",
        "WHATSLY_API_KEY_ID": "<your-api-key-id>",
        "WHATSLY_API_KEY_SECRET": "<your-api-key-secret>",
        "WHATSLY_DEFAULT_DEVICE_ID": "<your-device-id>"
      }
    }
  }
}

Available tool categories

The server exposes a focused toolset. The tools available to a client remain limited by the API scopes and workspace feature access assigned to its credential.

whatsly_send_text_message

Send a reviewed text message through the configured device.

whatsly_send_template_message

Send a saved Whatsly template with supplied variables.

whatsly_send_media_message

Send supported media from an accessible URL.

whatsly_get_device_status

Check whether the selected device is available.

whatsly_list_conversations

List supported conversations where the credential has read access.

whatsly_get_conversation_messages

Read supported messages from a selected conversation.

Use messaging tools safely

A tool call can create a real customer-facing message. The business remains responsible for the recipient, consent, content, timing and any action initiated by the AI client.

• Require confirmation before high-impact or sensitive messages.
• Do not allow the client to invent prices, policies, availability or delivery commitments.
• Do not use scraped, purchased or unlawfully obtained contacts.
• Honor opt-outs and suppression records across manual, automated and MCP-initiated sends.
• Keep device and API credentials out of prompts, logs and shared configuration examples.
• Revoke the MCP credential when the client is removed.

Troubleshooting

Check the connection in layers: client process, environment configuration, credential access and device state.

1. 1

   Server does not start

   Confirm Node.js and npx are available to the MCP client and that the package command can run in the client environment.

2. 2

   Authentication fails

   Copy the API base URL and credentials again, remove accidental spaces and confirm the key has not been revoked.

3. 3

   A tool is missing

   Review the key scopes and workspace plan feature. Read tools require the corresponding read permission.

4. 4

   Messages do not send

   Check the device state, recipient format, required tool arguments, usage limits and Whatsly message logs.