Security and permissions¶
Read this page before you install. It answers three questions: what an AI client can reach, under whose permissions, and how you narrow it.
The short version¶
- The AI acts as one signed-in CiviCRM user, never as an administrator or a service account.
- The built-in tools run every call with that user's CiviCRM permissions (APIv4 with
checkPermissionson). - The built-in tools are read-only, and the extension drops any tool that is not declared read-only. That is a declaration by each tool's author, so review third-party tools before enabling them.
- CiviCRM's own security is the ceiling. The one exception is CiviCRM's own: a SearchKit display set to bypass ACLs, used only when another extension publishes it. See The one deliberate exception.
- You choose who may connect, which tools each person gets, and from which AI client. Nobody can connect until you give them a permission profile. A profile only takes tools and entities away; it never adds to what the person's own CiviCRM permissions allow. Claude and ChatGPT are both on by default; turn off any you have not approved.
- You can revoke every connection at once with a single setting.
What an AI client can reach¶
An AI client can call only the tools the extension offers. It cannot run arbitrary code or arbitrary SQL. The built-in tools read through CiviCRM's own API, so:
- if the signed-in user cannot see a contact, case or field in CiviCRM, those tools cannot either
- ACLs, financial-type permissions and case permissions apply to them as normal
- fields whose names mark them as credentials (password, API key, hash, token, checksum and similar) cannot be selected, filtered or sorted on
- each call returns at most a fixed number of rows (the row cap)
What is not protected. Credentials that someone has pasted into free text, such as a login link inside an email activity's details, are not detected. The AI can read them if the user can. Remove them from your data.
The one deliberate exception¶
civicrm_mcp never shows anyone more than CiviCRM's own security does, with one exception that is CiviCRM's own.
Published SearchKit displays can show more than a user's own ACLs
An extension can publish a SearchKit display (built by an administrator) as a tool. If that display is set to bypass ACLs, the tool returns what the display returns to anyone offered the tool and permitted to open the form it is embedded in, whatever their own ACLs. It exists so a site can give a group such as volunteers a narrow, fixed view without widening their CiviCRM roles. It does nothing on its own: it is used only when another extension on your site publishes a display.
This shows the AI nothing a person could not already see: anyone allowed to open the form can run the same display in their browser. Only an administrator holding all CiviCRM permissions and ACLs can set a display to bypass ACLs, and you can see every such display in SearchKit. But who may run it, and which fields can be filtered, also depend on every form that embeds it and on who may build FormBuilder forms. Review any display that bypasses ACLs, every form that embeds it (its permission and its fields), and who holds the FormBuilder permissions, before you publish it, as you would an ACL-bypassing report.
The exact rule extension authors must follow is in Publishing a SearchKit display.
Other extensions can add tools too. Those tools must be read-only and must declare the CiviCRM permissions a user needs. civicrm_mcp cannot stop another extension's tool from turning CiviCRM's permission checks off, so that is the first thing to look for. Review any extension that adds MCP tools before you enable it, just as you would any extension that adds reports.
Under whose permissions¶
Signing in works like this:
- The AI client sends the person to your site's normal CMS login page.
- Once they are signed in, the extension checks that they may connect (see below) and shows a consent page.
- If they agree, the AI client receives two tokens tied to that person: an access token that lasts one hour, and a refresh token that lasts 30 days and is used to get new access tokens.
Every later request carries the access token, and runs as that person. Tokens are signed with your site's existing signing keys, and work only on the MCP endpoint, nowhere else on your site. The checks below are repeated on every request, so a change takes effect immediately.
How to narrow it¶
Starting with the most important:
- Grant the "connect an AI client" permission to as few roles as possible. Without it, a user cannot connect at all.
- Give a permission profile only to people who should connect. While Require a profile is on (the default), a person needs both the permission and an active profile. Removing their profile, or switching it off, cuts them off at their next request, even with an unexpired token. Turning Require a profile off makes the permission enough on its own, and administrators hold every permission, so every administrator account can then connect too. A profile belongs to the CMS login it was given to, not just the contact: a new account that CiviCRM links to the same contact does not get it, and merging contacts never moves it.
- Give each profile only the tools and entities that role needs. A tool outside the person's profile is not listed, and calling it gets the same unknown tool answer as a tool that does not exist, so a profile reveals nothing about what else the site offers. The entities limit what Read CiviCRM records and Describe CiviCRM data can reach. An empty list allows nothing; only All tools allows every tool, and All entities every entity, including ones added later. The entities limit where a query starts, not its joins, so a profile is not a substitute for CiviCRM's ACLs. See Setup § 3.
- Narrow what those users can see in CiviCRM itself. Because the built-in tools inherit the user's access, the most effective control is the one you already have: roles and ACLs.
- Lower the row cap if you want smaller answers per question.
- Revoke everything with Revoke all connections on the Setup checklist (it moves the token epoch forward). Every token issued before then stops working immediately, and people have to sign in again. Never lower the epoch: tokens issued before the old value would start working again. See Setup § Disconnecting everyone.
- Disable sign-in entirely by clearing the client ID. This also cuts off every existing connection at once, because tokens are tied to the client ID. If you change it instead (Generate a new client ID), update the ID in each AI client's connector.
The call log¶
Every tool call writes one row to the MCP call log: who called, which tool, the arguments they sent, how many rows came back, how long it took, whether it succeeded or was refused, and the MCP protocol version and session it used. Values in fields that look like credentials (passwords, keys, tokens) are replaced before the row is stored, but everything else a person typed into a question's arguments, such as a name they searched for, is kept. If the row cannot be written, the result is not returned, so a call is never answered without a record.
Staff read it on the MCP Call Log page, route civicrm/admin/mcp/call-log: administrators
under Administer → Users and Permissions → MCP (AI connector) → Call log, auditors under
Search → MCP call log (Setup § Reading the call log).
On WordPress, open it inside wp-admin, at
https://<your-site>/wp-admin/admin.php?page=CiviCRM&q=civicrm/admin/mcp/call-log: the CiviCRM
plugin refuses every civicrm/admin/... page on the public site, even for administrators, with
"You do not have permission to access this content". Reading it needs
the CiviCRM MCP: view the call log permission (or administer CiviCRM); nobody can edit or
delete rows through the API. The viewer's contact permissions apply to the rows: a row is shown
only when the viewer can see its caller as a contact, so an auditor needs contact access to the
people who connect (an ACL on a group of them, or view all contacts), and access deleted
contacts to see calls by a caller in the trash. Rows whose caller was deleted permanently are
shown to every reader. Only rows are filtered: a row's arguments can name contacts the viewer
cannot otherwise see. Details: Setup § Reading the call log.
Treat the log as personal data under your privacy policy.
Sessions¶
AI clients on the older MCP versions (2024-11-05 to 2025-11-25) open a session when they connect, and send its ID with every request. A session stores only who opened it (the contact and the AI client), the protocol version and the client's name and version, never a question, an answer or a token, in CiviCRM's database cache. It belongs to whoever opened it: anyone else using its ID is told it does not exist. It ends an hour after it was last used, or when CiviCRM's caches are cleared. A session grants nothing by itself: every request still needs a valid token for the same person and AI client. The current MCP version (2026-07-28) uses no session.
What the AI provider sees¶
Whatever a tool returns is sent to the AI client, and so to its provider: Anthropic for Claude, OpenAI for ChatGPT. Each supported AI client is a separate company processing your data, so check each provider's data-handling terms against your privacy obligations, and turn off in Setup any client your organisation has not approved. Turning a client off also cuts off its existing connections at once. Turning it back on revives any of those that have not expired, so after an incident also press Revoke all connections. The call log records which client made each call. If you would not paste the data into that AI tool yourself, do not give users access to it through this extension.
Reporting a vulnerability¶
Do not open a public issue. See SECURITY.md.