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.
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 Desktop, Claude CLI, Cursor and VS Code Copilot 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 authorise an assistant using a personal access token.
How It Works
The MCP server is a thin, stateless translation layer. It stores no credentials and touches no database. It calls CrmLeaf's own API as the authenticated user, forwarding that user's token on every request. CrmLeaf therefore 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.
Issue token → Configure assistant → Assistant calls a tool → CrmLeaf checks permission → Result returned and writes audited
- Approximately 50 tools and 19 reference resources are exposed across Leads, Deals, Invoices, Projects, 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.
- Write access is a coarse ability on the token and is re-checked against the user's own add or edit permission on the server. A read-write token does not bypass permissions.
- Every write is recorded to an append-only audit trail capturing who acted, which token was used, the action, the record, the outcome and the field names submitted - never the values.
Who Can Use This Feature?
Administrator
- Confirm the MCP capability is included in the account's plan and enabled.
- 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.
- Decide whether the account uses personal access tokens or, for hosted setups, the optional OAuth 2.1 flow.
User
- Issue your own personal access token, choosing read-only or read-write.
- Configure your AI assistant with that token.
- Revoke a 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 and enabled by an Administrator.
- Your own CrmLeaf user account with the permissions covering the data you want the assistant to reach.
- An AI assistant client that supports the Model Context Protocol.
- For write actions, the add or edit permission on the relevant module - a read-write token alone is not enough.
For Administrators
Step 1: Confirm the capability and its dependencies
What to do: Confirm MCP access is included in the plan and enabled, 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.
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: Decide the authorisation model
What to do: Use self-issued personal access tokens as the standard route. For hosted setups, evaluate the optional OAuth 2.1 flow instead.
What to verify: Users know which route your organisation uses.
Step 4: Review the write audit trail
What to do: Review the append-only audit trail of writes made through MCP. It records who acted, which token, 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: Issue a personal access token
What to do: Create a personal access token. It is pinned to your company and organisation, defaults to 30 days, and must be set as read-only or read-write. Choose read-only unless you genuinely want the assistant to create or update records. Copy the token when it is shown.
What to verify: The token is listed with the ability and expiry you intended.
Step 2: Configure your AI assistant
What to do: Add CrmLeaf as an MCP server in your assistant (for example Claude Desktop, Claude CLI, Cursor or VS Code Copilot) and supply 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 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 token, 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.
Step 5: Renew or revoke
What to do: Before a token expires, issue a new one and update the assistant. Revoke any token you no longer use, or one that may have been exposed.
What to verify: The revoked token no longer works and the assistant stops returning data.
Field and Option Reference
| Field / Option | Description | Required |
|---|---|---|
| Token ability | Read-only or read-write. Read-write is still re-checked against your own add or edit permission on the server. | Yes |
| Expiry | Validity period of the token. The default is 30 days. | Yes |
| Company and organisation | The token is pinned to the company and organisation you issued it in, so it cannot reach another workspace. | Yes |
| Token value | The secret the assistant sends with every request. Treat it as a password. | Yes |
Expected Result
Your AI assistant is connected to CrmLeaf with your own personal access token, it returns exactly the records your permissions allow, it cannot delete anything, and every write it makes is recorded in the append-only 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. 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.
- The token is your identity. Anyone holding it can act as you, within your permissions. Do not share it.
- MCP grants no new access. It cannot show an assistant data the user could not open in the web interface.
- The MCP server stores no credentials and no data of its own; CrmLeaf remains the only system of record.
- 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.
Common Scenarios
Example: a sales manager's weekly review. The manager issues a
read-only token 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 issues a read-write token and asks the assistant 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.
Troubleshooting
| Issue | Possible Cause | Resolution |
|---|---|---|
| The assistant returns no data | The token has expired or been revoked, or MCP access is not enabled for the account | Issue a new token and ask your Administrator to confirm the capability is enabled. |
| 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. |
| A create or update action is refused | The token is read-only, or you do not hold the add or edit permission on that module | Issue a read-write token and ask your Administrator for the required permission. |
| Vendor, purchase order, bill, payment or budget tools return nothing | 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 token is pinned to the company and organisation it was issued in | Issue a separate token in the other organisation. |
Frequently Asked Questions
Can an AI assistant delete my CrmLeaf data?
No. The MCP server exposes no delete tools by design.
Does connecting an assistant give it more access than I have?
No. It calls CrmLeaf's API as you, forwarding your token, so it is bound by the same multi-tenant scoping and per-user permissions.
Is the content of my records written into the audit log?
No. The audit trail records who acted, the token, 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 the Model Context Protocol, including Claude Desktop, Claude CLI, Cursor and VS Code Copilot.
Related Articles
Our support team answers on business days. Reference MCP-01 so we can jump straight in.