MCP and AI agents
Connect an AI agent to your site over MCP, decide which tools it sees, and let it make precise edits with the same abilities the admin uses.
What it is
CanAI runs a Model Context Protocol server at /wp-json/mcp/wpcanai. Every action in the CanAI admin has a matching wpcanai/* ability, so an agent can write templates, pages and posts, manage menus, sideload images, change settings, translate, back up and restore. There is no "run any PHP" escape hatch: if an agent cannot do something, it is a missing ability, not a missing permission.
Manage all of it under CanAI → AI Client, which has four tabs: Skills, Connections, Guardrails and Tools.
Connecting
On Connections:
- OAuth (recommended). Hosted connectors such as Claude.ai and ChatGPT, and local clients using
@automattic/mcp-wordpress-remote, sign in without a secret in the URL. Turn on Enable OAuth in the guided setup. Claude and ChatGPT identify themselves automatically. Gemini Spark registers itself, but only after you paste its exact redirect URI on Allowed OAuth Redirects. An empty list rejects every automatic registration. Registered OAuth lists those clients so you can revoke them. - API key (fallback). Create one on API Keys. The key acts as the WordPress user you pick and inherits that user's capabilities. It is shown once, so copy it then. Send it as
Authorization: Bearer <key>, as anX-WPCanAI-API-Keyheader, or as a path token on/wp-json/mcp/wpcanai/<key>for clients that cannot set headers (the Claude app connector, for example). The path-token URL lands in server access logs, so treat the whole URL as a secret and Revoke it if it leaks.
Connections shows ready-to-paste client JSON for each option.
Skills
Skills teach an agent the right workflows. Install them with:
npx skills add usewp/canai
That opens a picker. Add --skill canai-mcp to take just one, or -g to install globally. The Skills tab also has copy-ready prompts you can paste into an AI client that can run shell commands.
| Skill | Use |
|---|---|
canai-mcp |
Essential. Drive any CanAI site: templates, pages, posts, settings, media, translations. |
canai-prepare |
Essential. Turn mockups or static sites into one self-contained HTML file per page. |
canai-blocks |
Opt-in. Deploy pages as native blocks instead of Twig. |
canai-replicate |
Opt-in. Clone or migrate a live site into CanAI. |
canai-eeat |
Opt-in. Audit content for helpfulness and E-E-A-T. |
canai-yolo |
Opt-in power tool. Publish FluentSnippets PHP. Skip it for routine work. |
Choosing which tools an agent sees
Every tool costs the agent context on each turn, so CanAI hides tools your site cannot use. On Tools:
- Each tool has a Touches column:
canai,core,woocommerce,fluent-snippets,cache,filesystemorhttp. It says what the tool may read or write, and you can filter by label. The label also prefixes the tool's description. - Follow recommendations hides tools that do not apply. Translation tools stay hidden until you turn the Languages group on, and
purge-cachehides when no page-cache plugin is found. - Each tool is Auto (follows the recommendation), On or Off. Your On/Off choice always wins.
- A hidden tool is removed from the server, not just discouraged. After changing the list, reconnect the client, because clients cache the tool list.
The same controls exist for agents as wpcanai/manage-tools: {"action":"list"} shows every tool including hidden ones, and {"action":"set","groups":{"Languages":"on"}} turns translation on.
Guardrails
The Guardrails tab limits what an agent can reach:
- Option allowlists.
get-optionreads only the names on the read allowlist.update-optionsapplies names on the auto-apply list immediately and queues names on the approval list until you approve them in wp-admin. If one name is in both lists, approval wins, and one approval-listed key queues the whole batch. A built-in denylist blocks dangerous options regardless. - Snippet groups. The FluentSnippets write tools can only change snippets in groups you list. An empty list disables snippet writes. Reads are always allowed.
- Page cache. CanAI purges your page cache once per request after any write (editor, MCP, import, preset), if a supported cache plugin is active.
Example: a precise edit in two calls
You asked for tighter line height on one heading. Rather than reading and rewriting a 145 KB page, the agent edits in place:
wpcanai/grep-content { "pattern": "conference", "post_id": 42 }
wpcanai/replace-in-meta {
"post_id": 42,
"field": "html",
"replacements": [ { "from": "leading-tight", "to": "leading-[1.15]" } ],
"scope": { "text": "conference" },
"require_all": true
}
grep-content returns each hit with line, column and a snippet around the match, plus optional context_lines. replace-in-meta is literal by default. ignore_whitespace tolerates indentation differences, regex allows PCRE with $1 templates, scope.text limits the edit to the element around a visible phrase, and dry_run previews counts without writing. For longer documents, read-meta accepts lines: [from, to] with a single field to read a slice.
Pages in a hierarchy
wpcanai/list-pages { "all_pages": true }
wpcanai/create-page { "title": "Auditorium", "parent": 118 }
wpcanai/update-page { "post_id": 245, "slug": "auditorium", "parent": 118 }
list-pages shows each page's slug, parent, path and url; all_pages includes drafts and plain pages, so the agent can find a parent instead of making a duplicate. update-page changes title, slug, status, parent or order without touching the body, and returns previous values you can re-send to undo. Moving a published page changes its URL and its subpages', so the response warns you to look for hard-coded links.
If something looks wrong
- Client cannot connect with OAuth. The Connections tab warns "OAuth discovery may be unreachable" when the site cannot serve
/.well-known/oauth-authorization-server. Fix that first. A warning also appears if another MCP plugin has its own OAuth or DCR endpoint switched on. - Gemini Spark says it needs a client ID. The redirect URI is not on the Allowed OAuth Redirects list yet.
- A tool is missing. Check Tools (it may be hidden by a recommendation or an Off override), then reconnect the client. Use
wpcanai/manage-toolswithlistto see the reason. replace_no_match. The error names the failing pair and the nearest match (whitespace_only,partial,outside_scopeornone) with line and snippet. Retry withignore_whitespace.option_not_readable. The option is denied or not on the read allowlist; add it on Guardrails if appropriate.invalid_parent/parent_loopfromcreate-pageorupdate-page. The parent does not exist or would sit under itself.- Content problems after a write. Run
wpcanai/scan(Scanning and auditing) and read the Diagnostics page.