# Frequently asked questions

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](https://w4dev.com/docs/block-theme-mcp/connect-claude-code/), [Connect claude.ai or ChatGPT](https://w4dev.com/docs/block-theme-mcp/connect-claude-ai-or-chatgpt/), [Connect with an Application Password](https://w4dev.com/docs/block-theme-mcp/connect-with-an-application-password/) or [Use a browser agent through WebMCP](https://w4dev.com/docs/block-theme-mcp/browser-agents-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](https://w4dev.com/docs/block-theme-mcp/filters-and-actions/).

## 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](https://w4dev.com/docs/block-theme-mcp/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.

## Which files can an agent write?

The active theme’s `.html`, `.css`, `.js` and `.scss` files and `theme.json`, and nothing else. See [Tool groups](https://w4dev.com/docs/block-theme-mcp/tool-groups/).

## 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](https://w4dev.com/docs/block-theme-mcp/theme-files-change-sets-backups-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](https://w4dev.com/docs/block-theme-mcp/activity-log-and-revert/).

## 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](https://w4dev.com/docs/block-theme-mcp/how-block-theme-mcp-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** also needs 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](https://w4dev.com/docs/block-theme-mcp/tool-groups/).

## Where do I get help?

Check [Troubleshooting](https://w4dev.com/docs/block-theme-mcp/block-theme-mcp-troubleshooting/) first. For anything else, write to supports@w4dev.com.

Source: https://w4dev.com/docs/block-theme-mcp/block-theme-mcp-faq/