Zoho CRM
The Zoho CRM connector lets AI agents browse and manage CRM records across any module, search contacts and leads, convert leads, and add notes — all via the Zoho CRM REST API using OAuth 2.0. Your credentials are stored encrypted in MCPGate's vault and are never exposed to the AI client.
Required scopes#
MCPGate requests the following OAuth scopes when you connect a Zoho CRM account.
| Scope | Purpose |
|---|---|
| ZohoCRM.modules.ALL | Read and write records across all CRM modules |
| ZohoCRM.settings.READ | Read module metadata and field definitions |
| ZohoCRM.coql.READ | Execute COQL queries for advanced searching |
Tool reference#
The Zoho CRM connector exposes 11 tools. Use the MCP Apps page to enable or disable individual tools per app, and the Guardrails page to add fine-grained rules on top.
| Tool | Category | Description |
|---|---|---|
| zoho_list_records | read | List records from a Zoho CRM module |
| zoho_get_record | read | Get a specific Zoho CRM record by module and ID |
| zoho_search_records | read | Search Zoho CRM records within a module using criteria |
| zoho_list_modules | read | List all available Zoho CRM modules |
| zoho_get_module_fields | read | Get field definitions for a Zoho CRM module |
| zoho_list_notes | read | List notes associated with a Zoho CRM record |
| zoho_create_record | write | Create a new record in a Zoho CRM module |
| zoho_update_record | write | Update an existing Zoho CRM record |
| zoho_create_note | write | Create a note and attach it to a Zoho CRM record |
| zoho_convert_lead | write | Convert a Zoho CRM Lead into a Contact, Account, and optionally a Deal |
| zoho_delete_record | delete | Delete a Zoho CRM record by module and ID |
Lead conversion is irreversible
zoho_convert_lead moves the Lead into Contact, Account, and optionally a Deal. The original Lead record is marked as converted and cannot be un-converted. Deny this tool unless the agent is specifically tasked with lead qualification.Common guardrail recipes#
Read-only access#
Enable only the six read tools and deny all write and delete tools. Useful for CRM reporting agents that need to retrieve pipeline data without modifying records.
Edit records preset#
Enable all tools except zoho_delete_record and zoho_convert_lead. This allows the AI to create records, update fields, and add notes while blocking the two most risky operations.
Restrict to specific modules#
Apply the allow_values template to zoho_create_record, zoho_update_record, and zoho_delete_record. Target the module field and provide a list of module names (e.g. Leads, Contacts, Deals) the agent is permitted to modify.
Troubleshooting#
- Data centre mismatch— Zoho CRM has regional data centres (US, EU, IN, AU, etc.). MCPGate detects the correct endpoint during the OAuth flow. If you see "invalid OAuth token" errors after reconnecting, ensure you are connecting via the same regional Zoho domain your account was created on.
- Module name case-sensitive — Zoho CRM module names are case-sensitive in API requests (e.g.
Leads, notleads). Usezoho_list_modulesto get the exact API names for modules in your org. - Field not writable — Some Zoho CRM fields are system-managed and cannot be updated via the API (e.g.
Created_Time,Ownerin certain contexts). Usezoho_get_module_fieldsto check theread_onlyflag on a field before attempting to write it.