How to Connect an AI Assistant to CrmLeaf
All editions. AI-assistant access uses CrmLeaf's MCP (Model Context Protocol) server, which is part of the platform's AI and automation capabilities and is plan-gated — confirm with your Administrator that it…
Availability: All editions. AI-assistant access uses CrmLeaf's MCP (Model Context Protocol) server, which is part of the platform's AI and automation capabilities and is plan-gated — confirm with your Administrator that it is included in your account's plan. Data types are additionally gated by their own add-on: vendors, purchase orders, bills and payments require the Purchase add-on module, and budgets require the Budget add-on module.
What's New NEW
R26.10 · Oct 2026MCP access now reaches the Work app. On top of the CRM and finance data it already covered, an AI assistant can read and, with a read-write token, create and update projects, tasks and time logs — for example creating or updating a task, setting its status, adding comments or subtasks, and logging or editing time. The tool set is now about 68 tools. There are still no delete tools, and there are no timer tools.
Overview
CrmLeaf supports the Model Context Protocol, a standards-based way to let an AI assistant read and act on your CrmLeaf data on your behalf. Assistants such as Claude (Claude.ai and Claude Desktop), Claude Code, Cursor and VS Code can connect, so you can ask them to summarise this week's deals, draft an invoice, or check a project's budget.
This article explains what the connection exposes, how the safety model works, and how to connect an assistant — either by signing in with your CrmLeaf account (recommended) or with a personal access token.
CrmLeaf's MCP server address is https://mcp.crmleaf.com/mcp. It is the same address for every
account and every assistant.
How It Works
The MCP server is a translation layer between your assistant and CrmLeaf. It holds none of your CrmLeaf records. Every request is made to CrmLeaf as the signed-in user, so CrmLeaf remains the sole authority for login, multi-tenant scoping and per-user permissions — the assistant sees exactly what you would see in the web interface.
Connect assistant → Sign in (or supply a token) → Assistant calls a tool → CrmLeaf checks permission → Result returned and writes audited
- Two ways to authorise. The recommended route is to add the server address to your assistant and sign in with your CrmLeaf account (OAuth 2.1 with PKCE; assistants register themselves automatically). The alternative is a personal access token that you create yourself and send with each request.
- 68 tools and 25 reference resources are exposed across Leads, Deals, Invoices, Projects, Tasks, Time Logs, Products, Customers, Vendors, Purchase Orders, Bills, Payments and Budgets.
- The tools cover reads and a set of create and update actions. There are no delete tools, by design — an assistant cannot permanently remove a CrmLeaf record.
- Every data type is still gated by its normal permission and by its add-on module. A user with no permission on Deals gets nothing on Deals through an assistant.
- Read-only or read-write. A connection made by signing in has read and write access. A personal access token is either read-only or read-write, and read-only is the default. In both cases each write is re-checked against your own add or edit permission, so a read-write connection does not bypass permissions.
- Every change an assistant makes (create, update, send, pay) is recorded to an audit trail capturing who acted, which token or connection was used, the action, the record, the outcome and the field names submitted — never the values. Looking records up is not audited.
What the Assistant Can Do
Wording is flexible; the assistant chooses the right action from your request. The table shows what is available in each area.
| Area | Read | Create and update (read-write) |
|---|---|---|
| Leads | List and view leads | Create a lead; update a lead |
| Deals | List and view deals, with pipeline, stage and value | Create a deal; update a deal or move its stage |
| Invoices | List and view invoices with line items; outstanding and overdue receivables | Create a basic invoice; update note, due date or status; send an invoice or mark it sent |
| Projects | List and view projects, with their members and milestones; budget versus actual for a project | Create a project with its members; update a project; change a project's status |
| Tasks | List and view tasks, with subtasks, comments and time logged, including overdue tasks | Create a task, in a project or on its own; update a task; move a task to another board column; comment on a task; add or update a subtask |
| Time logs | List time logs; totals for a date range by person, project, task or day | Log a finished time entry on a task; correct an existing time log |
| Products | List and view products | None |
| Customers | List and view customers, including the balance owed; a customer's invoices | None |
| Vendors (Purchase add-on) | List and view vendors, including the amount owed; a vendor's bill history | Create a vendor; update a vendor |
| Purchase orders (Purchase add-on) | List and view purchase orders with line items | Create a basic purchase order; update safe fields; approve; close |
| Bills (Purchase add-on) | List and view bills with payment history; filter by vendor or status | Create a bill from a purchase order; update a bill; record a full or partial payment |
| Payments (Purchase add-on) | List and view vendor payments and the bills they covered | None (to make a payment, pay a bill) |
| Budgets (Budget add-on) | List and view budgets and their lines; analytics such as variance and burn rate; a project's primary budget | Create a budget; update a budget; add or update a line; approve; close |
Examples for the work areas: "what is overdue on the website project", "add a task for Priya due Friday", "move that task to Review", "log an hour on this task", or "summarise last week's time by person". Task and time changes follow the same rules as the web forms: a status change respects task dependencies and approval rules, overlapping or future time entries are refused, and logging time for someone else needs the matching permission. Changing a project's status needs full edit-project access.
The assistant can also read reference lists such as lead sources, categories, statuses, agents, deal pipelines and stages, project and product categories, project and task statuses, task categories and labels, the people a task can be assigned to, and units of measure, so it can fill those fields correctly.
Some things are deliberately left to the web interface: deleting anything, timers (an assistant logs a finished time entry with a start and an end), task files and notes, tax rows, recurring invoices, converting time logs or expenses into an invoice, and linking estimates or proposals. Invoice and purchase order tools create simple documents from line items (item, quantity, unit price) and compute the totals for you.
Who Can Use This Feature?
Administrator
- Confirm the MCP capability is included in the account's plan.
- Confirm the add-on modules behind the data users want to reach — Purchase for vendors, purchase orders, bills and payments; Budget for budgets.
- Set the role permissions that decide what any assistant can read or write, because MCP inherits them.
- Review the audit trail of writes made through assistants.
- Tell users which route your organisation prefers: signing in (recommended) or a personal access token.
User
- Connect your own AI assistant by signing in with your CrmLeaf account, or by issuing your own personal access token.
- Choose read-only or read-write if you use a token.
- Revoke a connection or token you no longer use.
Access depends on the modules and role assigned by your Administrator.
Prerequisites
- MCP access included in your account's plan.
- Your own CrmLeaf user account with the permissions covering the data you want the assistant to reach.
- An AI assistant client that supports remote MCP servers over HTTP, such as Claude.ai, Claude Desktop, Claude Code, Cursor or VS Code.
- For write actions, the add or edit permission on the relevant module — a read-write connection alone is not enough.
For Administrators
Step 1: Confirm the add-on modules
What to do: Confirm MCP access is included in the plan, and enable the Purchase and Budget modules if users need procurement or budget data through an assistant.
What to verify: The modules behind the requested data types are enabled for the account. Without them, the assistant answers requests for those areas with a clear message that the module is not enabled.
Step 2: Set permissions deliberately
What to do: Review each role's ownership-scoped permissions. Because an assistant acts as the user, permissions are the real control surface. Grant add and edit only where the user should be able to create or change records.
What to verify: A user's assistant returns the same records as that user's own web session, and no more.
Step 3: Tell users how to connect
What to do: Point users to this article. Recommend signing in with their CrmLeaf account. Note that a connection made by signing in is read-write; anyone who should only ever read data through an assistant should use a read-only personal access token instead, and be given no add or edit permissions that they do not need.
What to verify: Users know which route your organisation uses and that write access is always limited by their own permissions.
Step 4: Review the write audit trail
What to do: Review the audit trail of changes made through MCP. It records who acted, which token or connection, the action, the record, the outcome and the field names submitted.
What to verify: Writes you expect are present, and the trail records field names only — values are never captured.
For Users
Step 1: Choose how to authorise
What to do: The recommended route is to sign in with your CrmLeaf account when your assistant asks. Use a personal access token if your assistant cannot do an interactive sign-in, or if you want a read-only connection. To create a token, go to Profile → Access Tokens — see How to Create Personal Access Tokens.
What to verify: You know whether you need read-only or read-write access. Choose read-only unless you genuinely want the assistant to create or update records.
Step 2: Connect your AI assistant
What to do: Add CrmLeaf to your assistant using the server address
https://mcp.crmleaf.com/mcp, then sign in with your CrmLeaf account when prompted. That is the
whole setup for most people.
Using a developer tool instead? Open the section for yours. Each one needs the same server address and nothing else; the personal access token variant is only for a read-only connection or a tool that cannot sign in interactively.
Claude Code
Run this command in your terminal, then sign in with your CrmLeaf account when prompted:
claude mcp add --transport http crmleaf https://mcp.crmleaf.com/mcpUsing a personal access token instead
Add the token as a header. Replace YOUR_TOKEN with your token.
claude mcp add --transport http crmleaf https://mcp.crmleaf.com/mcp --header "Authorization: Bearer YOUR_TOKEN"Cursor
Add this to ~/.cursor/mcp.json, then sign in with your CrmLeaf account when prompted:
{
"mcpServers": {
"crmleaf": {
"url": "https://mcp.crmleaf.com/mcp"
}
}
}Using a personal access token instead
Add a headers entry. Replace YOUR_TOKEN with your token.
{
"mcpServers": {
"crmleaf": {
"url": "https://mcp.crmleaf.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}VS Code
Add this to .vscode/mcp.json, then sign in with your CrmLeaf account when prompted:
{
"servers": {
"crmleaf": {
"type": "http",
"url": "https://mcp.crmleaf.com/mcp"
}
}
}Using a personal access token instead
Add a headers entry. Replace YOUR_TOKEN with your token.
{
"servers": {
"crmleaf": {
"type": "http",
"url": "https://mcp.crmleaf.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}What to verify: The assistant lists the CrmLeaf tools and resources.
Step 3: Test with a read
What to do: Ask the assistant for something you can already see, such as a list of your open deals, the tasks overdue on a project, or a project's budget position.
What to verify: The result matches what you see in the web interface. If it returns less, check your permission scope for that module.
Step 4: Test a write, if you need one
What to do: With a read-write connection, ask the assistant to create or update one low-risk record.
What to verify: The record appears in CrmLeaf and the write is present in the audit trail. If you are using a read-only token, the assistant tells you the token is read-only.
Step 5: Page through long lists
What to do: Lists return up to 100 records at a time, newest first. If there are more, ask the assistant for the next page.
What to verify: The assistant continues the list rather than starting again.
Step 6: Renew or revoke
What to do: You can revoke a connection at any time here. Before a personal access token expires, issue a new one and update the assistant. Revoke any connection or token you no longer use, or one that may have been exposed.
What to verify: The revoked connection no longer works and the assistant stops returning data.
Field and Option Reference
| Field / Option | Description | Required |
|---|---|---|
| Server address | https://mcp.crmleaf.com/mcp. The same for every account. | Yes |
| Authorisation | Sign in with your CrmLeaf account (recommended), or send a personal access token as a bearer token. | Yes |
| Access level | Read-only (read access only) or read-write (read plus write access). A token is read-only by default; a connection made by signing in is read-write. Read-write is still re-checked against your own add or edit permission on the server. | Yes (token) |
| Expiry (token) | Validity period of a personal access token. The default is 30 days. | Yes (token) |
| Company and organisation | The connection is pinned to your company and organisation, so it cannot reach another workspace. | Set automatically |
| Token value | The secret the assistant sends with every request. Treat it as a password. | Yes (token) |
Expected Result
Your AI assistant is connected to CrmLeaf with your own account or personal access token, it returns exactly the records your permissions allow, it cannot delete anything, and every change it makes is recorded in the audit trail.
Service Organisation Context
Delivery and finance questions in a service organisation are often asked once: which deals may close this quarter, which projects are running over budget, what has been invoiced against an engagement. Asking an assistant can be quicker than building a report for a single question. The scope matters, though — the assistant answers strictly as the signed-in user, inside that user's own permissions and add-on access, and it cannot delete anything, so a partner and a consultant asking the same question receive different data. The assistant can list, total and log time entries, but weekly timesheets and running timers stay in the web interface, and measures CrmLeaf does not hold, such as utilisation against a target, cannot be produced simply by asking for them.
Important Notes
- Menu names and their position can differ between product editions and can be customised for your account, so your sidebar may not match these paths exactly. Use Search or your Quick Access items if you cannot find a screen.
- A token is your identity. Anyone holding it can act as you, within your permissions. Do not share it or commit it to a file that others can read.
- MCP grants no new access. It cannot show an assistant data the user could not open in the web interface.
- Signing in gives the assistant read and write access (still limited by your permissions). If you want an assistant that can only read, use a read-only personal access token.
- CrmLeaf remains the only system of record. The MCP server does not keep copies of your records.
- Add-on modules are plan-gated. If vendors, purchase orders, bills, payments or budgets are missing from the assistant, confirm the Purchase and Budget modules are included in your plan.
- Because there are no delete tools, an assistant cannot be used to clean up records — do that in CrmLeaf.
- You can revoke an assistant's access at any time under Profile → Access Tokens.
Common Scenarios
Example: a sales manager's weekly review. The manager connects
Claude and asks the assistant to summarise deals by stage and average deal size. Because the manager's
permission scope on Deals is all, the summary covers the team. A representative with
owned scope asking the same question gets only their own deals.
Example: drafting an invoice. A finance user connects an assistant with read-write access and asks it to draft an invoice from an agreed quote. The write succeeds because the user holds the add permission on invoices, and the action, the record and the field names submitted are recorded in the audit trail.
Example: a read-only connection. A director wants answers but no
changes. They create a read-only personal access token and add it to Claude Code with the
--header option. If they ask the assistant to update a deal, it replies that the token is
read-only.
Troubleshooting
| Issue | Possible Cause | Resolution |
|---|---|---|
| "Not authenticated — check the token supplied to your MCP client." | The token has expired or been revoked, the connection was revoked, or your sign-in has lapsed | Sign in again, or issue a new token and update the assistant. Ask your Administrator to confirm MCP access is included in your plan. |
| The assistant sees fewer records than expected | Your ownership-scoped permission for that module is owned or added rather than all | This is correct behaviour. Ask your Administrator if a wider scope is appropriate. |
| "This token is read-only. A read-write MCP token is required to create or update records." | You connected with a read-only token | Create a read-write token, or connect by signing in, and update the assistant. |
| "You do not have access to leads in crmleaf-web." (or deals, invoices, budgets) | Your role has no view permission on that area | Ask your Administrator to review your permissions. |
| A create or update action is refused although the connection is read-write | You do not hold the add or edit permission on that module | Ask your Administrator for the required permission. |
| "Record not found or not visible to you." | The record does not exist, or it is outside what your permissions let you see | Check the record in the web interface with the same account. |
| "The submitted data was invalid." or "Invalid input — field: message" | A value was missing or not accepted, for example a date format or a stage that does not belong to the chosen pipeline | Correct the value and ask again. |
| Vendor, purchase order, bill, payment or budget requests return a "module not enabled" message | The Purchase or Budget add-on module is not enabled for the account | Ask your Administrator to enable the module, subject to your plan. |
| The assistant cannot delete a record | No delete tools are exposed, by design | Delete the record in CrmLeaf directly. |
| Data from the wrong workspace is expected but missing | The connection is pinned to the company and organisation it was made in | Connect again, or issue a separate token, in the other organisation. |
| "crmleaf-web is unavailable. Please try again later." | A temporary problem reaching CrmLeaf | Wait a moment and try again. |
Frequently Asked Questions
Can an AI assistant delete my CrmLeaf data?
No. The MCP server exposes no delete tools by design.
Can an AI assistant log my time or update my tasks?
Yes, with a read-write token and where you hold the add or edit permission. An assistant can create and update tasks and projects and log or edit time entries. It cannot start or stop a live timer.
Does connecting an assistant give it more access than I have?
No. It calls CrmLeaf as you, so it is bound by the same multi-tenant scoping and per-user permissions.
Should I sign in or use a personal access token?
Signing in is recommended and needs no token to copy or store. Use a token if your assistant cannot do an interactive sign-in, or if you want a read-only connection.
Is the content of my records written into the audit log?
No. The audit trail records who acted, the token or connection, the action, the record, the outcome and the field names submitted — never the values.
How long does a token last?
The default is 30 days. Issue a new token before it expires.
Which assistants can connect?
Any client that supports remote MCP servers over HTTP, including Claude.ai, Claude Desktop, Claude Code, Cursor and VS Code.
How do I disconnect an assistant?
Revoke it under Profile → Access Tokens. The assistant stops returning data.
Related Articles
Our support team answers on business days. Reference MCP-01 so we can jump straight in.