Connect your AI client¶
Claude and ChatGPT are supported today. Both are on by default, and a site administrator can turn either off (see Setup). Support for other AI clients, such as desktop and command-line tools, is on the Roadmap.
The quick way: let your AI walk you through it¶
Copy the box below and paste it into a chat with Claude or ChatGPT. Replace the two values in angle brackets first: your site address, and the OAuth client ID your administrator gave you (see Setup).
Paste the instructions; don't send a link
Claude and ChatGPT cannot open this page on lab.civicrm.org (the site blocks automated readers), so sending them the address does not work. Pasting the text does.
Help me add a custom MCP connector to this AI assistant, one step at a time.
Wait for me to confirm each step before giving the next one.
Connector details:
- Name: CiviCRM
- Server URL: https://<your-site>/civicrm/mcp/ (keep the trailing slash)
- Authentication: OAuth, with a pre-registered (user-defined) client
- OAuth client ID: <client ID from your administrator>
- Client secret: leave empty
- Token endpoint authentication method: none
- Leave every other setting at its default
Where to add it:
- Claude: Customize > Connectors > + Add > Add custom connector. The client ID goes under
"Advanced settings". On a Team or Enterprise plan, an owner adds it first under
Organization settings > Connectors.
- ChatGPT: Plugins (in the sidebar) > Add > Create custom MCP server. The client ID goes under
"Advanced OAuth settings", with "User-Defined OAuth Client" as the registration method.
After I connect, I will be sent to my organisation's website to sign in, then to a consent page.
That page must name this AI assistant and show my own account; I should approve only if both are
right.
The steps are also written out below, if you would rather follow them yourself.
Which plans work¶
| AI client | Plans that can add this connector |
|---|---|
| Claude | Free (one custom connector only), Pro, Max, Team and Enterprise |
| ChatGPT | Plus, Pro, Business, Enterprise and Education. Not Free. On Business, Enterprise and Education, a workspace administrator may have to allow custom connectors first |
Nonprofit discounts. Both companies discount their organisation plans for eligible nonprofits, and those plans also keep your conversations out of model training:
- ChatGPT Business: see OpenAI for Nonprofits (discounted Business seats, and up to 75% off Enterprise).
- Claude Team or Enterprise: see Claude for Nonprofits (up to 75% off).
Prices and terms are the providers', and change; check the pages above. Whichever you use, it receives what its users can read in CiviCRM, so check its data terms against your privacy obligations (What the AI provider sees).
Claude (claude.ai)¶
- In Claude, open Customize → Connectors, choose + Add, then Add custom connector. On a Team or Enterprise plan, an owner first adds it under Organization settings → Connectors, and members then connect to it.
- Enter a name and the URL
https://<your-site>/civicrm/mcp/. Include the trailing slash, and use exactly the same host form as your site (with or withoutwww). - Under Advanced settings, paste the OAuth client ID from Setup. Leave the client secret empty.
- Choose Add, then Connect. You will be sent to your site's login page, then to a consent page that names Claude and shows your account. Approve it.
The connector works in Claude on the web, in Claude Desktop and in the mobile apps.
ChatGPT (chatgpt.com)¶
- In the ChatGPT sidebar, open Plugins, then choose Add → Create custom MCP server.
- Enter a name (such as "CiviCRM") and, under Connection, the Server URL
https://<your-site>/civicrm/mcp/, with the trailing slash and exactly your site's host form. Leave Authentication on OAuth. - Open Advanced OAuth settings. ChatGPT reads your site's sign-in settings and fills in the rest: keep User-Defined OAuth Client as the registration method, paste the OAuth client ID from Setup, leave the client secret empty, and keep the token endpoint authentication method none. Leave every other setting at its default.
- Tick OpenAI's risk acknowledgement, choose Create as a plugin, and sign in. The consent page names ChatGPT and shows your account. Approve it.
- In a new chat, add the connector from the tools menu next to the message box, and ask a question. To see the tools it offers, open Plugins, choose the connector, then its row under Apps.
On a personal Plus or Pro account, consider turning off Settings → Data controls → Improve the model for everyone before connecting, so CiviCRM data is not used for training.
ChatGPT's company knowledge mode needs search and fetch tools, which this extension does not
offer; use the connector in a normal chat.
If sign-in fails, check the FAQs first. Once you are connected, see Asking questions.
Other AI clients¶
Only Claude and ChatGPT can sign in today: the address each one returns to after sign-in is built into the extension. Letting an administrator approve any other MCP client without a code change (through Client ID Metadata Documents, the MCP standard's own way for a client to identify itself) is planned in #8. Comment there if your organisation needs a particular client.