How the EspoCRM MCP extension gives AI agents controlled CRM access
A team that wants an AI agent to look up or update CRM records should not hand that agent a shared administrator login. The EspoCRM MCP extension turns EspoCRM into a Model Context Protocol server that runs over the existing REST API, so the agent reaches records through the same permission layer that governs every other API client. The extension exposes tools for CRUD operations and for Stream access, and it works without a separate server process. Administrators decide which of those tools are exposed, which makes the tool list the first control to design. The extension is distributed free under AGPLv3, and according to the EspoCRM MCP extension page it currently supports only MCP protocol version 2026-07-28. Confirm that your agent framework or MCP client supports that exact version before you plan any rollout, because an older client will not connect.
Tool selection and identity work together. An enabled tool only matters for the records the connected user can see, so the agent should authenticate as a dedicated API user rather than an administrator. Create a role for that user that grants read access only to the entities the agent needs, add write permissions only where updates are a documented requirement, and keep the team scope narrow. Then enable the matching tools and nothing else. Keep the agent's account separate from staff accounts so its activity is traceable in the audit and stream history.
Plan the rollout as a short, reviewable sequence: confirm the protocol version, create the API user and role, enable the smallest tool set, and test each tool against a non-production instance with records that resemble yours. Record which tools you enabled and why, and review that list whenever the agent's job changes. Because the extension depends on the REST API, the authentication method you choose for the API user matters as much as the tool list. The EspoCRM API documentation describes HMAC as the most secure option, so confirm with your security team whether your deployment can use it for agent traffic.
What you need before enabling the EspoCRM MCP extension
Enabling the MCP extension is a small change on the EspoCRM side, but it depends on four things lining up: the EspoCRM version, the MCP client, a dedicated API user and the network path between them. Confirm each one before installing anything, because a mismatch in any of them will look like a broken agent rather than a configuration gap.
EspoCRM version and extension compatibility
The extension runs on top of EspoCRM's REST API, so it has to be installed on an instance version the extension supports. Confirm the required EspoCRM version on the extension page before you plan the install, and check it again if you are on an older release. If you plan a move to a newer major version, treat the extension as part of that upgrade test rather than a separate step, since an extension can lag a core release.
Server stack for the instance
The instance follows the standard EspoCRM server requirements: PHP 8.3 to 8.5, MySQL 8.0 or newer, MariaDB 10.6 or newer or PostgreSQL 15, served by Apache, Nginx or IIS. Background jobs need cron or a scheduled task, which matters here because agent-driven changes still flow through the same job and stream machinery as user changes. Confirm the stack against the current server configuration docs before you build.
MCP client with protocol 2026-07-28 support
The extension currently supports only MCP protocol version 2026-07-28, so the agent host or client must implement that exact version. A client that negotiates an older version will fail to connect, and the failure may appear on the agent side rather than in EspoCRM logs. Ask your agent platform vendor to confirm support for that version in writing before you select a client.
Dedicated API user and role
Create a separate EspoCRM API user for the agent, not a personal or administrator account. The EspoCRM docs describe API users with role-based permissions, and the MCP tools inherit whatever that role allows. Start with a narrow role that grants only the entities and actions the agent needs, and record which role and authentication method you chose, since both will be reviewed later.
Authentication method for the API user
The REST API supports API key, HMAC and basic authentication. HMAC is described in the EspoCRM docs as the most secure option, and basic authentication is not recommended. Choose the method before configuring the client, because the secret handling in your agent platform has to match it. Store the key or secret in your platform's secret store, not in prompts, configuration files committed to source control or chat transcripts.
HTTPS reachability from the agent host
The agent host must reach the EspoCRM instance over HTTPS on the public or internal hostname the extension is configured to use. Check the path through proxies, firewalls and any IP allowlist you have set on EspoCRM, since an allowlist that blocks the agent host will produce authentication-style errors. Confirm that the TLS certificate is trusted by the agent runtime, because a private certificate authority that the client does not trust is a common cause of failed connections.
Configuring the MCP extension step by step
This sequence takes the MCP extension from a test install to a verified agent connection, with each step closed by a check that confirms access is limited to what the agent needs. It is designed so that a mistake in permissions shows up on a non-production instance before any agent touches live customer records.
Install the extension on a non-production instance
Start on a non-production EspoCRM instance that matches your production version and extension set. The MCP extension is distributed free under AGPLv3, so the cost is the time your administrator spends on installation and testing, not a license fee. Install it from the official MCP extension page, then confirm it appears in the Administration extension list and that the instance still loads normally for an existing admin. Note the EspoCRM version you tested, because the upgrade path for production should be validated against the same version.
Create a dedicated API user for the agent
Create a separate user of the API type for the agent instead of reusing an administrator or a person's account. EspoCRM's security guidance recommends avoiding admin accounts for daily work, and an API user keeps the agent's actions visible in the audit trail as their own identity. Name the user so that its purpose is clear, such as the agent's function and environment. The check at the end of this step is that the user exists, is of the API type, and is not assigned the administrator role.
Define a role with the minimum record access
Create a role for the API user that grants read access only to the entities the agent genuinely needs, and write access only where a documented use case requires it. Set scope levels such as own, team or all deliberately, because the MCP tools operate through the same REST API permissions as any other API client. Confirm with your security team which entities and fields are in scope before saving. The check is a review of the role matrix against a written list of the agent's permitted entities.
Choose HMAC authentication for the API user
Set the API user's authentication method to HMAC rather than basic authentication. EspoCRM's API documentation describes HMAC as the most secure of the supported methods and does not recommend basic authentication. Generate the key pair, store the secret in your organization's secrets manager rather than in a prompt, configuration file or chat transcript, and record who holds it. The check is that a signed test request to a read-only endpoint succeeds and an unsigned request is rejected.
Enable only the required MCP tools
In the extension settings, turn on only the MCP tools the agent's task requires. The extension exposes tools for CRUD operations and Stream access, and administrators choose which of them are exposed. Start with read tools, then add write tools only after the read path has been verified and a specific business need is documented. Record the enabled list in your change log. The check is that the exposed tool list matches the approved list and nothing else.
Connect the MCP client with protocol version 2026-07-28
Configure the MCP client so that it negotiates protocol version 2026-07-28, which is the only version the extension currently supports. Confirm with the client vendor that their implementation supports this version before you start, since a client on another version will not connect. Point the client at the instance's MCP endpoint over HTTPS and supply the API user's credentials from the secrets store. The check is a successful handshake with the server and a tool listing that matches the list enabled in the previous step.
Run test calls and a denied-write check
Run a read on a known test record and confirm the returned fields match what the API user's role should show. Then attempt a write to an entity or field outside the role, and confirm EspoCRM refuses it with a permission error and that the attempt appears in the logs. Repeat the read with a record the role should not see to confirm record-level scoping. Only after these checks pass should you plan the production rollout, with the same role, tool list and protocol version recorded in your deployment notes.
How MCP tools map to EspoCRM REST API permissions
The MCP extension does not add a permission layer of its own. It runs through EspoCRM's REST API, so every tool call an agent makes is executed as the API user behind it. The agent's effective access is therefore the access of that API user, filtered by the role assigned to it. Before enabling anything, confirm which API user the MCP client will authenticate as, which role that user holds, and which teams it belongs to, because EspoCRM evaluates record visibility and edit rights against those settings on every request. A tool that exists in the extension cannot read a record the API user is not allowed to read.
CRUD and Stream tools inherit the same controls that govern the REST API. Role permissions are set per entity, with levels for reading, creating, editing and deleting that can be scoped to all records, the user's teams, or only records the user owns. Field-level restrictions and team-based access apply in the same way. Stream access follows record visibility, so an agent should not see activity on records its API user cannot open. Test this with a dedicated API user that has a narrow role, then confirm through the extension that the agent is refused records outside that scope. Use the EspoCRM security documentation for the authentication method and for the broader guidance on API users, including the recommendation to avoid admin accounts for automated access.
Tool enablement is a second, coarser control on top of role permissions. It decides which operations the MCP server offers at all, so a read-only enablement set means the agent cannot attempt writes even if its role would allow them. Use it to limit an agent to the tools its task needs, and keep role permissions as the authoritative boundary. Exact tool names, their parameters and the enablement settings are defined on the extension page, and you should confirm them against the version you install before writing approval rules or client configuration. Your team should also confirm that the MCP client supports protocol version 2026-07-28, since the extension supports only that version.
Which agent actions map to which EspoCRM permissions
This table maps common agent intents to the MCP tool category they use, the EspoCRM entity permission the agent's API user needs, and what to verify before enabling the tool. Treat it as a starting point and confirm each tool name on the extension page before you enable it. The main takeaway is to grant each intent separately and leave delete tools off unless a specific workflow requires them.
| Agent intent | Tool category | EspoCRM permission needed | Confirm before enabling |
|---|---|---|---|
| Read account record | Read tools for the Account entity, including list and view operations | Read access on Account, with a scope such as team or all that fits the agent's purpose | Exact tool name and whether list and view are separate tools |
| Create lead | Create tool for the Lead entity | Create access on Lead, plus field-level access on any required fields | Exact create tool name and required input fields |
| Update opportunity | Update tool for the Opportunity entity | Edit access on Opportunity, usually limited to own or team records | Exact update tool name and which fields it can change |
| Read stream notes | Stream access tools for records the agent can view | Read access on the parent record, since stream visibility follows it | Exact stream tool name and whether it returns notes and posts |
| Delete record | Delete tool for the entity | Delete access on the entity, which most agent roles should not hold | Exact delete tool name and whether it can be disabled per entity |
Designing permissions for agent users by risk level
Research agents answer questions about accounts, contacts, opportunities and activity history. They carry the lowest risk, but they still expose customer data, so they need a dedicated API user rather than a shared credential. Give that user a role with view access only, limited to the entities the research actually needs, and enable only the read-oriented tools that the EspoCRM MCP extension exposes. Stream access should be enabled only if the agent's questions depend on activity history.
- Role scope: Grant read permissions on named entities and leave create, edit and delete at none. Review each entity's field visibility so sensitive fields are not returned by default.
- Tool selection: Enable read tools only. Confirm in your version which tools map to reads before the agent connects.
- Team restriction: Assign the agent user to the teams whose records it may research, so record visibility follows team scope.
- Authentication: Use HMAC, which the API documentation describes as the most secure option, and avoid basic authentication, which the docs say is not recommended.
- Logging and review: Review access by the agent user on a regular schedule and confirm that only the intended MCP client uses its credential.
Before enabling the agent, check the role's entity permissions with a test user and confirm that the agent cannot reach records outside its teams.
Drafting agents create records that a person must review before they affect the business, such as tasks, notes or follow-up proposals. The risk is moderate: the agent can add data to the CRM, but it should not change records that customers or colleagues already rely on. The role should allow create on the specific entities the drafts require and deny edit and delete on existing records, so a draft cannot silently overwrite history.
- Role scope: Grant create and read on the draft entities, and keep edit and delete off for everything else. Confirm which entities support create-only use in your permission model.
- Tool selection: Enable the create tool for the draft entities and leave update and delete tools disabled, even though the extension can expose them.
- Team restriction: Scope the agent user to a single team, so drafts land in a queue owned by people who will review them.
- Review path: Route drafts to a named reviewer through assignment. If you plan workflow-based approvals, confirm that your Advanced Pack setup supports them for this entity.
- Logging and review: Sample records the agent created against their source material, and check whether records are attributed to the agent user in the stream and audit history for your version.
Before go-live, run a test in which the agent creates a draft, and confirm that the draft is visible only to the reviewer and that it cannot be edited through the agent's tools.
Operational agents update live records, such as changing stages, owners or contact details. They carry the highest risk because a single incorrect change reaches production data immediately. Design them last, after read-only and drafting patterns have run cleanly, and keep the scope of each agent narrow enough that one credential cannot touch every business area.
- Role scope: Grant edit only on named entities and specific fields where the agent's task requires it. Never grant administrator rights, and do not use an administrator account for agent work. The security documentation recommends avoiding admin accounts for daily work.
- Tool selection: Enable update tools only for the entities in scope, keep delete disabled, and document which tools each agent may call.
- Team restriction: Create one agent user per team or business unit instead of one agent for the whole organization, so a compromise affects a limited set of records.
- Session and network controls: Apply the same principles the security documentation recommends for people: limit token lifetime and restrict access by IP address where your network allows it.
- Logging and review: Set up the most frequent review of this group, and confirm with your team how changes made through the agent will be traced and reverted.
Before enabling any update tool, confirm that the MCP client supports protocol version 2026-07-28, since the extension currently supports only that version, and test every write path against a non-production copy of the data.
Hardening the agent API user
An AI agent connected through the MCP extension acts as an API user with its own role, credentials and audit trail. The controls below are the ones EspoCRM's security guidance points to, applied to that agent identity, so a compromised or misbehaving agent can reach only the records and tools it needs.
Give the agent its own API user
Create a dedicated API user for each agent instead of reusing an administrator or a person's login. Assign it a role that grants only the entity permissions the agent's job requires, such as read access to accounts and create access to cases. Because the agent inherits whatever its role allows, an admin account would give it reach across the whole instance. Confirm in your instance that the role's scope is set per entity and that no teams or portal roles widen access unexpectedly.
Prefer HMAC over basic authentication
The EspoCRM API documentation describes HMAC as the most secure of its authentication methods and does not recommend basic authentication. Choose HMAC for the agent's API user where your MCP client can sign requests, and confirm that the client supports it before you commit to a method. Basic authentication sends reusable credentials with every call, so treat it as a last resort if the client cannot do anything else.
Rotate and scope API keys
Issue one key per agent deployment so that a leaked key can be revoked without disrupting other agents. Set a rotation schedule that your security team agrees on, and record who owns each key and which tools it was issued for. Rotation is a recurring task, so ask your partner or internal team to document the steps, including how the MCP client's configuration is updated after a new key is issued.
Limit auth token lifetime
EspoCRM's security guidance recommends limiting how long authentication tokens remain valid. Shorter token lifetimes reduce the window in which a stolen token can be replayed against the agent's permissions. Check the setting in the administration area, then test that the MCP client recovers cleanly when a token expires, so that agents do not fail silently or retry in a loop.
Restrict access by IP address
Use the IP restriction options in EspoCRM to allow API calls only from the addresses where your MCP client runs, such as a fixed application server or an egress gateway. This turns a stolen key into a weaker risk, because requests from elsewhere are refused. Confirm the address the server sees behind any reverse proxy or load balancer, since an incorrect proxy setting can either block legitimate agents or let all traffic through.
Enforce policy for human admins
Human administrators keep the power to change roles, enable tools and read every record, so their accounts need the strongest controls. Enforce a password policy, require two-factor authentication, disable password recovery for admin accounts, and keep daily work on non-admin accounts. Note that EspoCRM's own 2FA is not compatible with OIDC sign-in, so confirm how admins authenticate before you set the policy.
Restrict tools and review the Stream
Enable only the MCP tools each agent needs, and remove any that are not part of its task. Then review what the agent actually does in the Stream, the activity feed that records changes to records, on a schedule your team sets. Look for unexpected deletions, updates outside the agent's scope and unusual volumes. Record the tool list and review findings so that changes in an agent's capability are traceable over time.
Common MCP connection and permission failures
This table maps the failures most often seen when an AI agent connects to EspoCRM through the MCP extension, with the likely cause and the check to run for each. Read it from the top when a connection fails, since protocol and enablement problems are the cheapest to rule out. Permission and ownership problems usually look like missing data rather than errors, so they need the record-level checks in the last rows.
| Symptom | Likely cause | Check to run |
|---|---|---|
| Client cannot connect or negotiates the wrong protocol | The MCP client does not support protocol version 2026-07-28, which is the only version the extension currently supports | Confirm the client's supported MCP version and upgrade it before changing EspoCRM settings |
| Expected tools are missing from the tool list | The administrator has not enabled those tools in the extension settings, so they are not exposed | Review the enabled tool selection in the extension configuration, then reconnect the client to refresh its tool list |
| Calls fail with a permission error | The API user's role does not grant the scope or action the tool needs for that entity | Compare the agent's role with the entity permissions (read, create, edit, delete) and the Stream access the tool uses |
| Authentication fails on every request | Basic authentication is misconfigured, or the HMAC key pair or API key does not match the API user | Confirm the authentication method chosen for the agent user, re-copy the credentials, and verify the request headers the client sends |
| Requests are refused from the agent host only | An IP restriction on the EspoCRM instance or the API user does not include the agent's outbound address | Check the IP allowlist for the instance and the API user, and confirm the address the server sees from the agent host |
| Agent sees fewer records than users expect | Team and ownership rules limit the API user to records owned by or shared with its teams | Check the API user's team membership and the entity's access level, then test with a record the agent should see |
| Agent sees records but not related activity | The role does not grant Stream access for that entity, so the stream tool returns nothing useful | Verify Stream permissions on the role and test the same request against the REST API directly |
Questions buyers ask about the EspoCRM MCP extension
Does the EspoCRM MCP extension cost money to use?
The extension itself is distributed free under AGPLv3, so there is no license fee for the extension. The cost sits in the EspoCRM edition and hosting you choose. The open-source edition can be downloaded and self-hosted for free, so your main costs are the servers, backups, maintenance time and any partner work. If you use EspoCRM Cloud instead, the pricing page lists 15 US dollars per user per month on the Basic plan (minimum 3 users), 25 dollars on Enterprise (minimum 5 users) and 69 dollars on Ultimate (minimum 10 users), with the Advanced Pack included in all cloud plans. Those subscription fees recur, while the extension cost is zero. Confirm the current figures on the pricing page before budgeting.
What drives the effort to configure EspoCRM MCP for AI agents?
Effort depends mostly on three things: the permission model, the number of agents, and the readiness of your MCP client. Each agent needs its own API user with a role that limits which entities it can read, create, update or delete, and the Stream access it gets. More agents with different duties means more roles to design, test and review. The extension lets administrators choose which tools are exposed, so each enabled tool needs a deliberate decision. Finally, the client must support MCP protocol version 2026-07-28, which is the only version the extension currently supports. If your client does not, the work includes upgrading or replacing it before any CRM configuration begins.
What does the work need from our team?
You need an owner for the CRM data model, someone who can decide which records an agent may touch, and an engineer who can run and secure the EspoCRM instance. The extension works through the existing REST API, so an administrator must create dedicated API users, set their roles and choose the API authentication method. The EspoCRM docs describe HMAC as the most secure method and basic authentication as not recommended. Your AI or platform team must also configure the MCP client and confirm it speaks the supported protocol version. Plan time for test records and a review of agent activity before any production access is granted.
Can our internal team set this up alone?
Yes, a team with EspoCRM administration skills and some experience with API authentication can enable the extension, create API users and connect an MCP client. The harder part is the permission design, because a role that looks narrow can still expose sensitive fields or related records through the API. Teams often do well when they write down each agent's job, list the entities and fields it needs, and test every role with a non-production account. A partner is most useful for complex role models, several agents, or integration with an existing identity provider. Whichever route you choose, agree the scope in writing first.
How long does it take to get an AI agent working on EspoCRM records?
No supplied figure gives a duration, and the answer depends on your environment. A single read-only agent against a test instance with a clean client setup is much faster to reach than several agents with separate write permissions on production data. Time usually goes into role design, field-level review, client compatibility checks and testing, not the extension install itself. Ask any implementation partner for a written timeline based on your agent count, entity model and the state of your MCP client, and confirm what counts as done, such as tested roles, documented tool choices and a rollback plan.
Which MCP protocol version does the extension support, and why does it matter?
The extension currently supports only MCP protocol version 2026-07-28, so the MCP client must support that exact version. A client that negotiates a different version will not work until it is updated or replaced. Check this before you choose a client or write agent workflows, because it affects your upgrade plan and vendor selection. Confirm the supported version on the extension page and with the client vendor, and test a connection on a non-production instance before any agent is given access to live records.
What should we confirm with the vendor or in our own environment before starting?
Confirm the extension's current release and compatibility with your EspoCRM version, the exact MCP protocol version your client uses, and which tools the extension exposes in your build. Check the license terms that apply to your deployment, and confirm your hosting costs, backup plan and who maintains the server. In your own environment, confirm which entities and fields hold personal or commercial data, whether agents need write access, how API keys will be stored and rotated, and how you will log and review agent actions. Put these answers in the scope document before any work starts.
How do we keep an AI agent from exposing data it should not see?
Start with the EspoCRM role model rather than the agent prompt. Give each agent a dedicated API user with the narrowest role that does the job, restrict entities and fields, and limit Stream access where it is not needed. Enable only the tools the agent requires, since the administrator chooses which tools are exposed. Use HMAC authentication where your setup allows it, restrict access by IP address where practical, and limit token lifetime as the EspoCRM security docs recommend. Test each role by attempting reads and writes it should not allow, and review those results before production use.
How DeployOpen scopes and supports an EspoCRM agent integration
DeployOpen agrees the scope in writing before any work starts. For an MCP integration, that scope names the EspoCRM instance, the API users the agents will authenticate as, the tools to be enabled and the record types each tool may touch. It also sets out the permission design, the MCP client and protocol version under test, the testing approach, the documentation and handover items, and whether ongoing support is included. Most engagements are fixed-scope, so the quote follows from this written list. Ask for the scope to state which EspoCRM roles and teams each agent user receives, and which tools were rejected and why, because those decisions are the ones that are hardest to reverse later.
The permission design is usually the largest share of the effort. It covers the dedicated API user for each agent, its role, which entities it can read, create, update or delete, which Stream access it receives, and how team membership limits what it sees. Client testing is equally specific: the agreed MCP client must support protocol version 2026-07-28, which is the only version the extension currently supports, so the test plan should confirm that version on the client side before anything else is built. Testing also covers denied actions, not only permitted ones, and checks that tools turned off in the extension cannot be reached through another path.
Security testing of the integration is available when requested and can be included in the written scope. DeployOpen runs that testing as a separate workstream with its own scope, covering the API user permissions, the exposed tools and the agent's behavior when given unexpected input. DeployOpen does not issue audit reports or attestations for this work. Handover includes configuration records, the tool inventory, the permission matrix and an operations note for rotating API credentials. Optional retainer support can cover permission reviews when new tools are enabled or when the EspoCRM or MCP client version changes, which should be confirmed with the vendor and the client's own environment before the retainer is priced.
