W4DEV

Connect Claude Code

By the end of this page Claude Code is signed in to your site through OAuth, lists the site’s tools, and has run one. There is no password to create or paste.

Before you start

  • The site is on HTTPS. A local development site works too, when WordPress reports its environment type as local.
  • You can sign in to the site as a user with the manage_options capability.
  • Claude Code is installed on your computer.

1. Switch on sign-in through the browser

  1. Go to Settings → Block Theme MCP and open the Connect tab.
  2. The Connect an MCP client card says “No way in for MCP clients is switched on yet.” Under Sign in through your browser (OAuth), click Switch on.

The notice “Sign-in through the browser (OAuth) is switched on.” appears. The same switch is on the Settings tab, under Ways to connect, as MCP clients over OAuth (claude.ai, ChatGPT, Claude Code).

2. Choose what the agent may do

  1. Open the Settings tab and scroll to Tool groups.
  2. Under Block theme, tick the groups you want. For theme work that is Theme files and Site Editor templates.
  3. Click Save Changes.

A group that is off does not exist for any client. See Tool groups and what each one allows.

3. Add the site to Claude Code

  1. Open the Connect tab again. Under Sign in through your browser (OAuth), copy the command shown after Claude Code:. On the screen it is one line. It has this shape:
claude mcp add --transport http example-com \
  https://example.com/wp-json/btm/v1/mcp
  1. Run it in your terminal. example-com is the name Claude Code will list the site under. The plugin builds it from your host name, and you can change it.
  2. Start Claude Code, type /mcp, choose example-com and sign in.

4. Approve the connection

Your browser opens a page on your own site titled Connect an application. If you are not signed in to WordPress, you are sent to the login screen first and brought back.

Read four things before you approve:

  • It calls itself: the name the application gave when it registered. The page says “This name is unverified.” because any application can register under any name.
  • You will be sent to: where your browser goes next. For Claude Code this is localhost, because Claude Code waits for the answer on your own computer.
  • Signing in as: the WordPress account the application will act as.
  • The list of tool groups the application will be able to use.

Click Approve. Deny sends you back with nothing granted.

Check that it worked

  • In Claude Code, /mcp shows the server as connected.
  • Ask Claude Code to call btm.site-info. It returns the site address, the WordPress and PHP versions, and the tool groups that are on. Claude Code shows the tool as mcp__example-com__btm_site-info: it rewrites the dot in the name.
  • On the Connect tab, Connected apps lists the application, the account it acts as, and when it connected.

Tools marked destructive are approved in Claude Code, with its own permission prompt. The site does not show a dialog for a client that has no browser tab.

If something goes wrong

  • The OAuth row in Status says Blocked. The site is on plain HTTP. See Troubleshooting.
  • The browser shows “Connection unavailable”. The OAuth switch is off. Repeat step 1.
  • The browser shows “You cannot connect an application”. The account you are signed in with does not have the manage_options capability.
  • Claude Code lists only a few tools. The tool groups are off. Do step 2, then reconnect the server from /mcp so Claude Code reads the list again.

To cut the connection later, see Revoke a connected app.