Testing your tools¶
How to check a tool your own extension adds (Adding your own tools). Keep these tests in your extension, with the tool. Testing changes to civicrm_mcp itself is covered in CONTRIBUTING.md.
Use a development site with made-up or copied test data, never production. Every call writes a row to the call log, and whatever a tool returns goes to the AI provider.
1. Test the callback on its own¶
A tool's callback is a plain PHP callable: fn(array $args, ToolContext $context). Call it from
your own PHPUnit tests with the arguments an AI client would send, and a context built by hand:
use Civi\Mcp\Tools\ToolContext;
$context = new ToolContext(contactId: 2, rowCap: 50);
// $ability is the Ability your listener registers.
$result = ($ability->callback)(['status' => 'open'], $context);
Check that it respects $context->limit() (the site's row cap), and that every API call inside it
runs with permission checks on. To check the second, run it as a user who may not see the records
and expect nothing back.
2. Check that it registers¶
On the development site, with your extension enabled and caches flushed (cv flush), list the
registered tools:
cv api4 -U <administrator login> McpTool.get
Your tool should be in the list. If it is missing, either its listener did not run, or it is not
marked readOnly: TRUE and was dropped. A profile's tool list on Who can connect shows the same
tools, each with the extension that adds it.
3. Call it as a real user¶
Give a test login a permission profile that allows your tool (Who can connect), connect an AI client as that login (Connect your AI client), and ask a question that needs the tool. Then check the call log (MCP (AI connector) → Call log): one row per call, with the arguments sent and the rows returned.
Also try a login whose role lacks the permission your tool declares: the tool should not be offered to them at all.
A throwaway test site¶
No development site? civicrm_mcp's repository has a CiviCRM Standalone site in Docker, seeded with
made-up data
(tests/Site).
It mounts civicrm_mcp only. To add your extension, mount it beside civicrm_mcp with a compose
override file, enable it with cv ext:enable, and run cv flush. A real AI client needs a public
HTTPS address to reach it; the README explains how to set one up safely.