How We Designed an MCP Interface So AI Agents Can Talk to a WhatsApp CRM

Most CRM APIs are CRUD endpoints bolted onto a database. You can create a contact, update a field, fetch a list. That works for dashboards and spreadsheet syncs. It does not work for AI agents that need to reason about conversations.

When we started seeing developer teams build custom AI workflows on top of Hallo Zetta, the REST API wasn't enough. They needed something that gave their agents structured context — not raw database rows, but meaningful conversation state.

So we built an MCP (Model Context Protocol) interface. This is the story of why, how, and what we learned.

The Problem: AI Agents Need Context, Not Just Data

Imagine you're building a custom sales agent. It needs to:

1. Read the last 10 messages in a conversation
2. Check what labels are attached to the contact
3. Look up relevant knowledge base entries
4. Decide whether to reply, escalate, or stay silent
5. If replying, send a message back through WhatsApp

With a traditional REST API, that's 4-5 separate HTTP calls, response parsing, error handling, and context assembly — all before your agent even starts thinking. Every integration team was writing the same glue code.

MCP changes this. Instead of your agent calling endpoints and assembling context manually, it connects to an MCP server that exposes tools and resources the agent can use naturally.

What Is MCP (Quick Primer)

Model Context Protocol is an open standard for connecting AI models to external systems. Think of it as a structured way for an LLM-based agent to:

• Discover what tools are available (send message, search contacts, read knowledge base)
• Call those tools with proper parameters
• Receive structured results back into its context window

The key difference from REST: MCP is designed for agent consumption, not human consumption. The tool descriptions, parameter schemas, and response formats are optimized for LLMs to understand and use correctly.

Our MCP Architecture for Hallo Zetta

Here's what the integration looks like:

┌─────────────────────────────────────────────────────┐
│           Developer's Custom AI Agent            │
│  (Claude, GPT, local model, custom pipeline)    │
└────────────────────────┬────────────────────────────┘
                         │ MCP Protocol
                         ▼
┌─────────────────────────────────────────────────────┐
│            Hallo Zetta MCP Server                │
│                                                 │
│  Tools:                                         │
│  ├── send_message(contact, text)                │
│  ├── search_contacts(query, labels)             │
│  ├── get_conversation(contact_id, limit)        │
│  ├── add_label(contact_id, label)               │
│  ├── search_knowledge_base(query)               │
│  ├── handoff_to_human(contact_id, reason)       │
│  └── get_inbox_summary()                        │
│                                                 │
│  Resources:                                     │
│  ├── conversation://active                      │
│  ├── contacts://recent                          │
│  └── knowledge://topics                         │
└────────────────────────┬────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────┐
│              Hallo Zetta Core                    │
│   WhatsApp Gateway + CRM + Knowledge Base       │
└─────────────────────────────────────────────────────┘

The MCP server is a thin layer that translates between agent intent and CRM operations. It handles authentication, rate limiting, and context formatting.

Tool Design: Making Actions Agent-Friendly

The hardest part wasn't building the MCP server. It was designing tool interfaces that LLMs use correctly without excessive prompting.

Here's what we learned:

1. Descriptive tool names beat generic ones

Bad: update_entity(type, id, fields)
Good: add_label_to_contact(contact_id, label_name)

Agents make fewer mistakes when tools are specific. A generic CRUD tool forces the agent to reason about parameters. A specific tool communicates intent through its name.

2. Return context, not just confirmation

When an agent sends a message, don't just return {"status": "sent"}. Return:

{
  "status": "sent",
  "message_id": "msg_abc123",
  "conversation_summary": "4 messages exchanged today, last human reply 2h ago",
  "contact_labels": ["hot-lead", "enterprise"],
  "suggested_next": "Customer asked about pricing in previous message — consider following up on enterprise plan details"
}

The extra context helps the agent make better decisions on the next turn without additional API calls.

3. Guard rails belong in the tool layer

We don't trust any agent to self-regulate. The MCP server enforces:

• Rate limits: Max 5 outbound messages per contact per hour
• Quiet hours: No messages between 22:00-07:00 local time (configurable)
• Group silence: Tools that send messages reject group targets unless explicitly allowed
• Handoff locks: Once a human takes over, agent tools return "conversation locked" until released

These are not suggestions in a system prompt. They're hard blocks in the tool implementation. An agent literally cannot violate them.

4. Search over list

We initially exposed a list_all_contacts() tool. Agents would call it, get 500 contacts back, and then hallucinate about which one to message.

We replaced it with search_contacts(query, labels, last_active_within). Now the agent describes what it's looking for, and the tool returns a focused, relevant set. Much better results.

Real-World Use Cases We've Seen

Developer teams connecting to Hallo Zetta via MCP have built:

Custom sales qualification agents
An agent that reads incoming conversations, scores lead quality based on company-specific criteria, applies labels, and routes hot leads to the sales team — all without the team manually triaging every new conversation.

Multi-language support routing
A middleware agent that detects message language, searches the appropriate knowledge base section, and either auto-replies in the customer's language or routes to a team member who speaks it.

Proactive follow-up systems
Agents that monitor conversation state and send follow-ups when a prospect goes quiet for 48 hours — with context-aware messages that reference the previous conversation, not generic templates.

Internal dashboard bots
Team leads connecting their Slack bot to Hallo Zetta's MCP to get inbox summaries, SLA alerts, and workload distribution without switching apps.

The DX Decisions That Mattered

Building a good MCP interface is as much about developer experience as it is about protocol compliance.

Local testing without WhatsApp
Developers can connect to the MCP server in sandbox mode. Messages go to a simulated inbox instead of real WhatsApp. This means you can build and test your agent without risking real customer conversations.

Typed schemas with examples
Every tool includes parameter descriptions AND example values. This helps both human developers reading docs and AI agents understanding expected input format.

Event streaming
Besides request-response tools, we expose a resource stream for real-time events. New message arrives, label changes, handoff triggers — the agent can subscribe and react without polling.

Composable with Zetta CRM core
The MCP layer works with the full Zetta CRM stack. Contact data, labels, analytics, team assignments — everything accessible. If you're already using Zetta CRM for your team inbox, adding an AI agent layer is connecting one more MCP client.

Lessons From Production

After running MCP in production with developer teams for several months:

Agents are only as good as their guardrails. Without rate limits and handoff locks, even well-prompted agents occasionally spam customers. Build safety into the tool layer, not the prompt.

Context windows fill fast. A single WhatsApp conversation can be hundreds of messages. We added server-side summarization — the MCP server returns a compressed conversation summary for older messages and full text only for the recent window.

Tool descriptions are documentation. The text you put in MCP tool descriptions is the most-read documentation you'll ever write. Make it precise. Every ambiguous word costs you failed agent actions.

Observability is non-negotiable. We log every MCP tool call with the calling agent's identity, parameters, and result. When something goes wrong (wrong message sent, wrong contact labeled), you need an audit trail.

Getting Started

If you're building AI agents that need to interact with WhatsApp conversations:

1. Set up Hallo Zetta — connect your WhatsApp number and publish your knowledge base
2. Enable MCP access — generate credentials in the developer settings
3. Connect your agent — point your MCP client at the server endpoint
4. Test in sandbox — validate tool calls against simulated conversations
5. Go live — switch to production mode with guardrails active

The MCP interface is available on all Hallo Zetta plans. No separate API pricing, no per-call charges.

What's Next

We're working on:

• Multi-agent coordination — multiple MCP clients sharing one inbox with conflict resolution
• Agent performance analytics — measuring resolution rate, response quality, and customer satisfaction per agent
• Template marketplace — pre-built agent configurations for common workflows (sales qualification, support triage, appointment booking)

All built on the same MCP foundation, all accessible from Zetta CRM's unified platform.

Build With Us

If you're a developer building AI-powered customer communication tools — or a team that wants custom agent workflows on WhatsApp — the MCP interface gives you full programmatic access without reinventing the messaging infrastructure.

Explore the docs, connect a test number, and see what your agent can do with real conversation context.

---

Built by Cipta Dusa — software development for teams that move fast.