WhatsApp Business Tools MCP Guide: Set Up Messaging with Codex or Claude
Setting up WhatsApp Business Platform usually means moving among the Developer Console, Business Manager, API documentation, and a code editor while you align a business, an app, a phone number, message templates, and webhooks. Meta announced WhatsApp Business Tools MCP on September 15, 2026 to bring that sequence into AI coding tools such as Claude Code, Codex, and ChatGPT.
This is not a license to hand production messaging to an autonomous agent. The server is in beta, is rolling out gradually, and is intended for development and testing workflows rather than production sending at scale. Actions that register a number, change account configuration, or send a message still require careful review of permissions, targets, and cost. Based on Meta's official announcement and documentation checked on September 22, 2026, this guide explains what to prepare, how to connect safely, and where a human should stop and verify the result.
- The remote server endpoint is
https://mcp.facebook.com/whatsapp_business_tools. It uses Streamable HTTP and OAuth. - You need admin access to both the business and its WhatsApp-enabled app, plus accepted WhatsApp Business Cloud API terms.
- Tools cover discovery, phone onboarding, templates, webhooks, account setup, and test messaging.
- Verify the connection with read-only discovery before allowing any state-changing action.
- WhatsApp Platform pricing and policies still apply separately. The MCP release is not a bulk production-sending system.
What changed: the consoles remain, but the workflow is coordinated
In the traditional flow, you create or select an app, connect it to a business, check the phone-number state and terms, then configure templates and webhooks in separate places. A missing app-admin role, payment method, or business-verification requirement may not become obvious until a later step fails.
WhatsApp Business Tools MCP exposes those steps as tools an agent can call in sequence. You can ask it to list the businesses you administer, inspect the WhatsApp accounts under one business, and then check the status of its phone numbers. When a prerequisite is missing, Meta says the tool returns an actionable error and a link to the relevant settings page. The consoles have not disappeared. The practical change is that the agent can coordinate the checks and route you to the right official screen without asking you to paste an access token into a prompt.
Prerequisites: three permissions and one operational decision
| Check | Required state | What fails if it is missing |
|---|---|---|
| Business role | Admin access, identified by Meta as the MANAGE role | Business discovery or asset operations may be unavailable |
| App role | Admin of a WhatsApp-enabled app connected to that business | A business admin can still be blocked from app-level actions |
| Cloud API terms | WhatsApp Business Cloud API Terms of Service accepted | Messaging and phone-number registration are blocked |
| Operational boundary | A test number, test recipient, and test webhook are separated from production | The agent may target a real customer or production system by mistake |
A payment method and business verification are not required for every read operation, but they can become prerequisites for billable messaging and broader deployment. Decide which assets are safe for testing before connecting the server, and identify who is allowed to approve changes.
Connect Claude Code, Codex, or ChatGPT
Meta's documentation lists the server name as WhatsApp Business Tools, the endpoint as https://mcp.facebook.com/whatsapp_business_tools, and authentication as OAuth. Clients that support remote MCP servers can connect directly. A client limited to local stdio servers needs a bridge such as mcp-remote.
1. Claude Code
claude mcp add --transport http whatsapp_business_tools https://mcp.facebook.com/whatsapp_business_toolsAfter adding the server, run /mcp in a Claude Code session, select whatsapp_business_tools, and complete authentication. In Claude Desktop, Meta directs users to Settings > Connectors > Add custom connector and asks for the same name and URL.
2. Codex app
Open Settings > MCP Servers > Add servers, choose Streamable HTTP, enter the name and endpoint, and set authentication to OAuth. Select Authenticate to complete the Meta sign-in and consent flow.
3. ChatGPT
Meta's current instructions use Settings > Plugins > Browse plugins, followed by the plus button for a new plugin. Enter the same name and URL and select OAuth. Menu names and availability can vary by client version and account rollout, so a missing menu does not necessarily mean the endpoint is broken.
Understand the OAuth scopes before granting access
During sign-in, you choose which businesses and WhatsApp-enabled apps the server can access. Meta documents three requested scopes:
business_managementdiscovers and acts on the selected businesses you administer.whatsapp_business_managementmanages accounts, phone numbers, message templates, and webhooks.whatsapp_business_messagingsends messages from registered phone numbers.
Meta says Facebook Login for Business and scoped consent keep access tokens out of prompt history. Tool calls run in the signed-in viewer's context and are logged. Operations that change state require an authenticated person rather than relying only on an app-level credential. You can later review or revoke the integration under Facebook Settings > Business Integrations.
Verify with discovery before changing anything
Do not register a number or send a message immediately after OAuth succeeds. Use a read-first sequence to confirm that the agent is operating on the intended business.
- Restart the client. Meta notes that sign-in may need to be completed again after a restart.
- Ask the agent to list the tools exposed by the
whatsapp_business_toolsserver. - Run
whatsapp_biz_businessesto list only the businesses available under the consent you granted. - Read back the selected business ID, then run
whatsapp_biz_accountsandwhatsapp_biz_phone_numbers. - Record the business name, account ID, last digits of the number, and onboarding state before approving a change.
A useful first instruction is: “List the WhatsApp businesses I can manage, but do not change anything.” If the result is unexpected, check whether the wrong business was selected during consent and whether you have app-admin access in addition to the business role.
Practical workflow 1: onboard a test phone number
Goal: Register a test number for Cloud API messaging without losing track of the sequence across several consoles.
Flow: Discover the business and WhatsApp account first and have the agent show the target IDs for approval. Add the number with whatsapp_biz_add_phone_number, request an SMS code with whatsapp_biz_send_verification_code, provide the received code to whatsapp_biz_verify_phone_number, and finally use whatsapp_biz_register_phone_number.
Completion check: Query the phone-number list again and confirm the changed registration state. Match the country code, display number, and attached account to the test assets you intended to use.
Constraint: An OTP is sensitive authentication data. Do not post it to a public channel or save it in long-lived documentation. Adding and registering a number changes real assets, so compare the selected business and app against the official settings screen before approving the calls.
Practical workflow 2: draft an order-update template
Goal: Create a structured notification template and shorten the review loop before submission.
Prepare: Decide the language code, template name, purpose, variable meanings, example values, and whether buttons are needed. Separate drafting from creation with an instruction such as: “Draft an English order-shipped template with variables for order number and tracking URL. Show me the final copy and proposed category before creating it.”
Flow and review: Use whatsapp_biz_list_templates and whatsapp_biz_get_template to check for duplicates. The server provides create, update, and delete tools for templates. Before submission, verify that the category matches the purpose, each variable is understandable in context, and sample values contain no personal data.
Constraint: Creating a template through an agent does not guarantee Meta approval. Copy changes may affect policy review and pricing classification, so follow the approval status link and check the current official policy.
Practical workflow 3: test a webhook and message round trip
Goal: Send a constrained test message and confirm that inbound or status events reach the server you prepared.
Flow: Prepare an externally reachable HTTPS callback and a verification token. Configure the callback and allowed fields with whatsapp_biz_configure_webhooks, then subscribe the WhatsApp account to the app's webhook with whatsapp_biz_subscribe_webhook. Reconfirm the registered sender and test recipient before using whatsapp_biz_send_message.
Completion check: Do not stop at a successful API response. Check your webhook logs for the message ID and expected event. Meta's documentation states that free-form text is delivered only inside the 24-hour customer-service window; outside that window, an approved template is required.
Constraint: Do not point the callback at an admin page or an unsecured temporary development address. Protect the verification token and keep personal message content out of unnecessary logs. Meta explicitly describes this MCP release as a development and testing tool, not a production bulk-sending system.
WhatsApp Business Tools MCP vs. Meta Social Technologies MCP
| Server | Primary role | Example |
|---|---|---|
| WhatsApp Business Tools MCP | Manage WhatsApp accounts, numbers, templates, webhooks, and test messages | Register a number or create a template |
| Meta Social Technologies MCP | Explore Graph API endpoints, search documentation, and troubleshoot errors | Find an endpoint or investigate an API error |
The WhatsApp-specific server changes and inspects business-messaging assets. Meta Social Technologies MCP is the broader documentation and debugging companion. If both are installed, ask the agent to state which server and tool it plans to use before it performs an action.
Costs, rollout, and security limits to keep in view
- Beta and gradual rollout: The documentation can be public even when the feature is not yet available to every account. The interface and tool set may change.
- Rate limits: Requests are limited per user and per tool. If a tool returns a rate-limit error, wait before retrying instead of building an aggressive retry loop.
- Messaging cost: MCP connectivity and WhatsApp messaging charges are separate. Meta's pricing documentation says charges depend on delivered messages, recipient country code, and message category. It also lists changes scheduled for October 1, 2026, so check the current rate card before production use rather than copying a fixed number into a budget.
- Target confirmation: Meta says the send-message tool confirms the target before sending. A person should still verify the number, template, language, recipient consent, and test boundary.
- Plugin supply chain: Verify the remote endpoint and OAuth domain and do not confuse a similarly named community server with Meta's official service. For a broader checklist on coding-agent plugin provenance and updates, see the Plugin4Shell response guide.
Troubleshooting in the right order
The server was added, but no tools appear
Confirm that the client supports remote Streamable HTTP MCP, check the endpoint for typos, restart the client, and complete OAuth again. If the menu or server is still unavailable, check the gradual account rollout. A stdio-only client needs the bridge described in Meta's documentation.
The business appears, but app or phone actions fail
Business-admin and app-admin roles are separate. Confirm that the app is connected to the selected business, has the WhatsApp Business Messaging use case enabled, and that the Cloud API terms have been accepted.
A message is not delivered
Verify that the number is both verified and registered, and confirm the sender and test recipient. For free-form text, check the 24-hour service window. Outside it, determine whether an approved template is required. If an error calls for a payment method or business verification, use the official deep link and complete the step directly.
The webhook saves, but events do not arrive
Configuring a callback and subscribing the WhatsApp account are separate actions. Check external HTTPS reachability, the verification token, subscribed fields, and the connection between the app and WhatsApp account. Then inspect the server logs for an actual incoming request.
Who should use it now?
The server is useful for a small development team or automation specialist who wants to assemble a test integration, expose missing prerequisites early, and reduce context switching among Meta tools. It is not a shortcut for unreviewed customer messaging, a large campaign sender, or a production environment without cost and permission controls.
The important value is not that an agent can click consoles on your behalf. It is that the agent can check dependencies among the business, app, number, templates, and webhook; route you to official settings; and keep a human in control of each state-changing step.
Official sources
- Meta for Developers: Announcing WhatsApp Business Tools MCP · September 15, 2026
- Meta setup and tool reference · page updated September 3, 2026; checked September 22, 2026
- Meta Social Technologies MCP documentation · checked September 22, 2026
- Official WhatsApp Business Platform pricing documentation · checked September 22, 2026
한국어판: 한국어로 읽기
Comments
Post a Comment