MCP clients

Connect an AI client to find customers, review conversations and prepare replies. You choose its access. Sending requires a preview and explicit confirmation.

MCP uses OAuth sign-in. For code running on your own server, use the Node.js SDK or Developer API with an API key. See the MCP tools reference for supported tasks and tool names.

Open Settings > Developer > MCP and copy the server URL shown for your workspace. If the setting is unavailable, contact Waaru Care.

Connect with read access firstCopy Anchor Link

1. Open the intended workspace and Settings > Developer > MCP. Copy its discovered HTTPS server URL.
2. In a client that supports remote HTTP MCP and OAuth, add that URL and choose OAuth authentication. Complete the client's application setup if requested. Registering an application does not grant workspace access.
3. Sign in to Waaru, choose the intended workspace and review the permissions. Initial bootstrap access requests only mcp:workspace:read and mcp:instances:read.
4. Approve only the workspace and permissions you intended. Cancel a mismatched review. Never paste WAARU_API_KEY, an OAuth token or a model key into a chat prompt.
5. Refresh the client's tools and test get_workspace and list_instances. Confirm the workspace and permitted numbers before requesting additional access.

If a client asks you to supply a client ID or secret, use its reviewed setup instructions and exact callback. Public clients need no secret. Do not substitute another application's client identity or copy an operator's credentials.

A stored approval is not proof that this host authenticated successfully or is using the newest token. Verify the actual client after sign-in. The connected-app guide records the version-specific CLI bootstrap alternative where automatic URL-only setup requests too many scopes; it does not certify a desktop or hosted client's login.

Choose and review capabilitiesCopy Anchor Link

In Settings > Developer > MCP, choose the read, support and campaign tasks your app needs. Optional choices start empty. Select a whole group only if you need every action. Review the access before copying the setup request; copying grants nothing and performs no action.

Your client can show tools eligible for your role and application before permission approval. Seeing a tool does not authorize it. Additional access requires a permission review; your token stays limited until approval.

The request_permissions tool can initiate a bounded permission review. Your workspace role, allowed numbers and the application's approved scope ceiling remain limits. Review the actual permissions on the OAuth page, not only the text the AI client displays. Cancel if the review does not include the intended selection.

For an existing application, open Allowed actions for its exact client identity in the selected workspace. Saving a broader selection prepares a time-limited review; it does not widen an existing token. Start a fresh OAuth reconnect for that app and verify the displayed permissions before approving. Refresh tools afterward. Reconnecting without a pending selection does not add permissions automatically.

Read-only observation can coexist with Logic Flow and does not take over replies. Message sends, contact changes, template edits and scheduling need their own permissions and current server authority. The SDK's API-key scopes are not interchangeable with MCP's mcp:* scopes.

Claim a conversation before replyingCopy Anchor Link

A reply needs a conversation assigned to you. For unassigned work, select Claim conversations as yourself and Reply to customers during setup. For an existing app, open Allowed actions and allow Claim conversations as yourself and Find conversations and send replies, then complete the permission review.

1. Find the conversation with list_conversations. Pass its conversation ID to get_conversation_assignment to check the active session, assignment revision and your eligible teams.
2. Review the conversation and selected team. Only after you ask to take it, call claim_conversation with that session ID, the returned assignmentRevision as expectedRevision, the eligible teamId, confirm: true and an idempotency key saved for this claim.
3. A successful claim assigns the conversation to you and pauses automated handling. It sends no message and does not change the number's handling mode.
4. Use the returned session ID to prepare a reply with preview_message or preview_rich_message. Review the recipient, sender and complete content, then give separate approval before confirm_message.

MCP cannot take another teammate's conversation or transfer it between teams. If ownership or eligibility changes, read the assignment again. After an uncertain claim result, reconcile the assignment and keep the same idempotency key; do not create a second logical claim blindly. Claiming also requires mcp:conversations:read, mcp:conversations:write and your current Inbox role permissions. Reply permission remains separate.

Review actions before confirmationCopy Anchor Link

For the single-contact campaign workflow, preview_scheduled_template also uses confirm_broadcast. This differs from the preview_template_message / confirm_template_message pair. Follow the tool names and inputs returned for the workflow you chose.

Previews do not send messages. Confirm only what you actually reviewed, using its unchanged preview ID before expiry. A tool invocation by an AI client is not, by itself, proof of a human confirmation. Verify how your chosen host presents and records that approval before using write actions.

Sending still checks current consent, recipient restrictions, sender state, quality and any required customer-service window. Template editing and campaign scheduling retain their own role and scope checks. Queued acceptance is not provider delivery or template approval. An uncertain provider result requires reconciliation, not a new preview to repeat the action blindly.

Scheduling additionally requires explicit offline_access. Review the timezone, returned UTC instant, sender, audience and rendered content. Token expiry alone does not cancel a confirmed schedule. Revocation or disconnection removes authority; reapproval does not revive cancelled commands.

Diagnose and disconnect safelyCopy Anchor Link

• If a tool is missing, refresh the client's catalog and check your role, allowed numbers and application limits. If a visible tool cannot run, inspect the token's approved scopes and the app's Allowed actions. Repeated login is not a scope upgrade.
• For invalid_scope or invalid_target, correct the requested permissions or exact resource URL. Do not request the issuer's entire permission catalog or switch to a broader credential.
• For stale or cancelled permission reviews, reload the settings and deliberately prepare a new review. Cancelling leaves existing access unchanged.
• To reduce access, save a narrower Allowed actions selection or use Manage connected apps to disconnect the exact application. Reducing authority invalidates broader tokens and cancels existing approval-bound previews and schedules.
• Share only redacted method names, stable error codes, scope names and callback host/path with authenticated support. Never share tokens, secrets, cookies, authorization codes or complete sign-in URLs.

Your external AI client supplies its own model. MCP access does not enable native AI replies in Waaru. See optional AI availability, and test sign-in, permitted reads, cancelled permission reviews and host confirmation before using write actions.

Next: Find an MCP tool, manage connected apps, use the Node.js SDK, or browse the REST contract.