Twenty CRM MCP for AI agents

Twenty CRM on crm.dardev.net exposes a Model Context Protocol (MCP) endpoint at https://crm.dardev.net/mcp so coding agents can query People, Companies, tasks, and workflows without embedding the CRM UI. MCP is for CRM orchestration—reading records, creating notes, activating workflow versions—not for sending mail. Outbound SMTP stays on the integration bus and Stalwart, matching the pattern in crm-orchestrates-bus-executes.

DarDev uses MCP in Cursor and other agent hosts to bulk-inspect outreach cohorts, seed workflow steps, and answer operational questions during 20.tn and Hesabi pipeline work. The endpoint is workspace-scoped: authenticate with a Bearer token configured in your local environment—never paste tokens into articles, logs, or chat transcripts.

What MCP provides

• CRUD on standard objects: people, companies, opportunities, notes, tasks
• Metadata tools for views, fields, and workflow versions when skills are loaded
• execute_tool pattern for actions like send_email and draft_email inside Twenty—not Stalwart bulk send
• group_by and find_many queries with filters for outreach analytics
• Navigation helpers for human operators; agents typically use API tools directly

MCP complements the REST and GraphQL APIs Twenty already documents. Agents benefit from structured tool schemas, rate-limited batch operations, and workspace skills (workflow-building, dashboard-building) that encode DarDev-specific conventions like targetSolution enums and consentEmail fields.

Connecting an agent host

Configure your MCP client with server URL https://crm.dardev.net/mcp and Authorization Bearer using the workspace API key stored in your password manager or local .env (variable name TWENTY_API_KEY in operator scripts—do not commit). Cursor users add a user-twenty MCP entry in project settings; the server instructions document available objects and execution rules.

Safe agent patterns

Read before write: use find_many with filters (targetSolution, consentEmail, leadSource) to count cohorts before update_many. Destructive bulk updates require explicit human confirmation in agent instructions—Twenty MCP enforces workspace policies, but operators should still preview counts.

Workflow creation: load the workflow-building skill, then create_complete_workflow or stepwise version APIs. Twenty CRM MCP generated the 20.tn outreach v2 payloads documented in 20TN-WORKFLOW-ORCHESTRATION—human review before activate is mandatory.

No SMTP in MCP examples: agents that need to trigger outreach call the platform bus POST /api/20tn/outreach/send or equivalent catalog routes with bus credentials—not Twenty send_email for cold bulk. Twenty send_email remains for 1:1 staff mail from Zoho-aligned workflows (contact@dardev.net booking links).

MCP vs Ops console

DarDev Ops at ops.dardev.net deep-links to Twenty views and shows MCP-friendly counts via crm-twenty connector capabilities (count-by-tag, open-view). Ops does not iframe CRM—policy matches deployed-realities-explained. MCP is the machine-facing mirror: same data, programmatic access for agents automating imports verification or dashboard repairs.

Ops Integration Inspector (M14) surfaces live tags and view IDs; agents can cross-check against MCP find_many results when debugging drift between manifest views_ref and actual CRM state.

20.tn outreach use case

After ecoles.com.tn import (~970 schools aggregate), sales uses CRM filters for private schools with email. Agents assist by: finding People with outreachStatus NOT_SENT, attaching timeline notes patterns, and validating workflow filters before enabling send-one automation. Mail execution still flows bus → Stalwart sales.dardev.net identity—not MCP.

Hesabi and Services parallels

OECT and Startup Tunisia imports set consentEmail UNKNOWN. Agents query Hesabi-tagged companies without adding product:hesabi:marketing tags via MCP unless explicit opt-in is documented. DarDev Services pipeline uses targetSolution DARDEV—MCP filters mirror CRM views DarDev Services Tunisia.

Rate limits and locks

Bulk import scripts use TWENTY_IMPORT_DELAY_MS and file lock at data/.twenty-crm-import.lock. MCP bulk writes should respect similar pacing—Twenty self-hosted rate limits live in Postgres keyValuePair on the VPS. Agents should not parallelize heavy update_many during active imports.

Security boundaries

• MCP credentials are staff-only; rotate if exposed
• No customer PII in agent transcripts uploaded to public channels
• http_request tool is for external APIs—not for bypassing bus auth on mail.dardev.net
• Destructive delete_many requires confirmation workflow in agent prompts

The unified mailer stack in inside-unified-mailer-stack remains authoritative for SPF, DKIM, and send domains. MCP sits entirely in the CRM lane of the architecture diagram.

Onboarding new agents

Add the Twenty MCP server to your agent host configuration with the public HTTPS endpoint only. Store the workspace API key in your local secret store—the same key scripts/twenty importers read from TWENTY_API_KEY in .env, never checked into git. Start sessions with learn_tools or load_skills for workflow-building when editing automation; use find_many with tight filters before any update_one call.

Document agent runbooks internally with redacted curl examples: show endpoint paths and JSON field names, omit Authorization headers. When sharing DarDev News articles externally, link to this guide and crm-orchestrates-bus-executes instead of pasting live MCP transcripts that may contain prospect emails from staging queries.

Testing without production risk

Use dry-run flags on bus outreach endpoints while MCP updates stay on test Person records in a dedicated CRM view. Twenty workflow activation should follow UI or MCP preview of filter counts—if find_many returns hundreds unexpectedly, stop and refine filters before send-one enables. deployed-realities-explained applies to agent-assisted sales: honesty about cohort size beats automated blast.