Short answers to what people ask before and after installing Block Theme MCP, with links to the page that covers each one in full.
What does the plugin do?
It is an MCP server inside your WordPress site, built for block themes. An AI agent connects to it and gets tools to read and edit the active theme’s files, the templates the Site Editor saves, global styles, patterns and saved content. Every kind of change has a way back. The server is the plugin itself: there is no cloud service and no account.
Which AI clients can connect?
- Claude Code, claude.ai and ChatGPT sign in through OAuth, with a consent screen on your site.
- Any MCP client that speaks Streamable HTTP and can send a header can connect with a WordPress Application Password.
- Browser agents use the tools through WebMCP, in a tab where you are signed in.
Start with Connect Claude Code, Connect claude.ai or ChatGPT, Connect with an Application Password or Use a browser agent through WebMCP.
Who can use the tools?
A signed-in user with the manage_options capability, which administrators have, and only while Enable Block Theme MCP is on. An agent acts as the account that connected it and can never do more than that account. A developer can change the capability with the btmcp_capability filter. See Change who can use the tools and other filters.
What can an agent do right after I activate the plugin?
Very little. No client outside your browser can connect until you switch a way in on. A browser agent on an admin screen can read basic site information, rename the site, and use Abilities your site exposes. The theme, template, content and file groups all start off. The full list is in Install Block Theme MCP.
Does it work with a classic theme?
Partly. The Theme files group edits .html, .css, .js and .scss files and theme.json in whichever theme is active, so it works on a classic theme’s styles and scripts. It does not edit PHP templates.
The Site Editor templates, Global styles and Patterns groups need a block theme.
Can an agent edit PHP files?
Not with the theme tools. They write .html, .css, .js and .scss files and theme.json, and nothing else. Writing other files, or running PHP, needs the Write files or Run PHP group, and each of those needs a constant in wp-config.php first. See Allow file writes or running PHP.
How do I undo something an agent changed?
- Theme files: every write is a change set that can be reverted, and every replaced or deleted file is backed up. See Edit theme files: change sets, backups and undo.
- Templates: WordPress revisions, and the trash for a reset or delete.
- Content replacements: a revision is saved before each post is written.
- Global styles and patterns: WordPress revisions, and the trash for a deleted pattern.
- You can revert a theme change set yourself on the Activity tab. See Activity: see what an agent did and revert it.
Will a theme update undo the agent’s work?
It depends where the work was saved. Templates, template parts, global styles and patterns that are saved in the database survive a theme update. Files inside a theme are replaced when that theme is updated by its author. Edit files in a theme you maintain, or in a child theme.
Will a destructive tool run without asking me?
Not by default. A tool marked destructive asks first. A browser agent gets the prompt from the plugin while Confirm destructive tools is on. Claude Code, claude.ai and ChatGPT ask in their own interface.
How do I see what an agent did?
Open the Activity tab. It lists calls to the tools that run on your server, with the time, the tool, the account, how the call came in, the result and what the call touched. The tools that run only in the browser (btm.request and the browse tools) are not listed. Theme changes are also listed as change sets, with the files each one touched.
Does the plugin send data anywhere?
No. There is no telemetry, no account and no outside service. An agent you connect receives what its tools return, and that is the only place your site’s data goes.
What happens to my data when I uninstall the plugin?
The settings and the OAuth tables are removed. Theme backups and change sets in wp-content/block-theme-mcp/ are kept, because they are recovery copies of your theme files. Delete that folder by hand when you no longer need them. Details are in How the plugin keeps a site safe.
Does it work on a multisite network?
The plugin runs on a network, with stricter rules. Only a Super Admin holds edit_themes, so only a Super Admin can use Theme files. Read files, Write files and Run PHP also need a Super Admin, because wp-content is shared by every site on the network.
Why does Claude Code show the tools under a different name?
Claude Code rewrites the dot. btm.theme-read-file appears as mcp__example-com__btm_theme-read-file, where example-com is the name you gave the server. It is the same tool.
Can I add my own tools?
Yes. Register an Ability with the WordPress Abilities API and expose it, and the plugin turns it into a tool. See the Abilities section of Tool groups and what each one allows.
Where do I get help?
Check Troubleshooting first. For anything else, write to [email protected].