By the end of this page you know which checks stand between an agent and your site, which of them you control, and what the plugin stores.
One rule first
A connected agent acts as a WordPress account. It can never do something that account could not do, and it can only do it through the tool groups you switched on.
The checks, in order
Every tool call is checked on the server, on every request. The list of tools a client sees is a convenience. It is never the permission.
- The main switch. With Enable Block Theme MCP off, no page and no client gets any tool.
- A signed-in account with the capability. By default that is
manage_options, which administrators have. - The way in. A request that arrives a way that is off is refused. Each way has its own switch under Ways to connect:
- OAuth, for Claude Code, claude.ai and ChatGPT
- Application Passwords, for clients that send a header
- Admin screens and Front end, for browser agents
- The tool group. A group that is off does not exist for any client.
- The group’s own requirement. Some groups need more than the general capability. See the table below.
- The item itself. A file, template, global styles or pattern update needs the hash of the version the agent read. A content replacement or a pattern change checks each post for the right to edit it.
What each group needs
| Group | Needs, on top of the general capability |
|---|---|
| Theme files | edit_theme_options and edit_themes |
| Site Editor templates | edit_theme_options and an active block theme |
| Global styles | edit_theme_options and an active block theme |
| Patterns | edit_theme_options and an active block theme |
| Search and replace in content | edit_others_posts and edit_theme_options |
| Site administration | manage_options |
| Read files | manage_options, and Super Admin on a multisite network |
| Write files | A wp-config.php constant, manage_options and unfiltered_html |
| Run PHP | A wp-config.php constant, manage_options and unfiltered_html |
edit_themes is the capability the theme file editor in wp-admin needs. WordPress takes it away when DISALLOW_FILE_EDIT or DISALLOW_FILE_MODS is set, so a site that has locked file editing has locked the Theme files group too.
If you give tool access to a lesser role with the btmcp_capability filter, Site administration, Read files, Write files and Run PHP still need manage_options.
The two wp-config constants
Write files and Run PHP each need a line in wp-config.php as well as their switch:
define( 'BTMCP_ALLOW_FILE_WRITE', true );
define( 'BTMCP_ALLOW_PHP', true );A setting can be changed from wp-admin. wp-config.php cannot. Switching these groups on is therefore always two deliberate steps, by someone with access to the server. See Allow file writes or running PHP.
The Theme files group needs no constant. It is confined to the active theme’s folder and to .html, .css, .js and .scss files and theme.json, and it never writes PHP.
Confirmations
A tool marked destructive asks before it runs.
- For a browser agent, the plugin shows the prompt, with the tool’s name and its arguments, while Confirm destructive tools is on. It is on by default.
- For a remote client such as Claude Code, claude.ai or ChatGPT, the client asks you. There is no page for the site to show a dialog on.
The prompt is there so you notice a destructive call. What a tool is able to do is decided by the switches, capabilities and constants above.
The consent screen
An application that connects over OAuth gets nothing until a signed-in user approves it on a page of your own site. That page shows the name the application gave itself, the host your browser will be sent to, the account it will act as, and the tool groups it will reach.
- The name is not verified. Approve only a connection you started yourself.
- The application must send you back to exactly the address it registered.
- Access tokens last one hour and the application renews them. A connection that is not used for 30 days has to be approved again.
- The site stores tokens as hashes, never the tokens themselves.
- You can cut a connection at any time. See Revoke a connected app.
A way back from changes
- Theme file writes are recorded as change sets, and every replaced or deleted file is backed up.
- Template changes and content replacements keep WordPress revisions.
- Resetting or deleting a template moves it to the trash.
Deletes made with the Write files group are permanent. That group has no backups.
What is stored and where
- Settings: the option
btmcp_settings. Removed on uninstall. - Connected applications and their tokens: the tables
btmcp_oauth_clientsandbtmcp_oauth_tokens, with your table prefix. Tokens are kept as hashes. Removed on uninstall. - Tokens from a content replace dry run: transients that last 15 minutes. Removed on uninstall.
- Activity log: the table
btmcp_activity, with your table prefix. Removed on uninstall. - A dismissed Get started card: the user meta
btmcp_setup_dismissed, one value for each user who clicked Dismiss. Removed on uninstall. - The result of a Revert on the Activity tab: a transient that lasts 5 minutes, until the notice is shown. Removed on uninstall.
- Theme backups and change sets: the folder
wp-content/block-theme-mcp/. Kept on uninstall.
Backups and change sets are recovery copies of your own theme files. They are kept on purpose when the plugin is removed. Delete the folder by hand when you no longer want them.
Nothing leaves your site. There is no telemetry, no account and no outside service. The activity log stays in your own database. See Activity: see what an agent did and revert it.