By Fahad Murtaza · Published · Updated
Claude Code MCP servers: how to add one, with WordPress
Claude Code MCP servers are how you give the agent tools beyond your local files and shell. This guide covers the commands and config files, then works through a real example: connecting Claude Code to a WordPress site.
What an MCP server gives Claude Code
Out of the box, Claude Code reads and edits files and runs commands in your project. An MCP server adds a set of named tools that reach something else: a database, an issue tracker, a browser, or a WordPress site. Claude Code lists the server’s tools, picks the ones a task needs and calls them with structured arguments. If the concept is new, read what is an MCP server first, and MCP vs API for how it differs from calling a REST API.
Servers come in two common forms. A remote server is a URL that Claude Code talks to over HTTP. A local (stdio) server is a command that Claude Code starts on your machine and talks to over standard input and output.
The three scopes
Every server is saved at one of three scopes, chosen with --scope:
- local (the default): private to you, available only in the current project.
- project: written to a
.mcp.jsonfile at the repository root, so everyone who clones the project gets the same server. - user: private to you, available in every project on your machine.
Local and user servers live in ~/.claude.json. Project servers live in .mcp.json, which is designed to be committed.
The commands
Add a remote server over HTTP, with a header for authentication:
claude mcp add --transport http my-server https://example.com/mcp \
--header "Authorization: Bearer YOUR_TOKEN"
Add a local stdio server. Everything after -- is the command Claude Code runs, so options for claude mcp add itself (such as --scope or --env) go before the server name:
claude mcp add --scope user --env API_KEY=YOUR_KEY my-server -- npx -y some-mcp-package
Add a server from a JSON definition, which is handy when a vendor gives you a config block:
claude mcp add-json my-server '{"type":"http","url":"https://example.com/mcp"}'
Inspect and manage what is configured:
claude mcp list
claude mcp get my-server
claude mcp remove my-server
Inside a session, type /mcp to see each server’s connection status and to sign in to servers that use OAuth.
The .mcp.json file and secrets
A project scoped server is an entry under mcpServers in .mcp.json:
{
"mcpServers": {
"my-server": {
"type": "http",
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer ${MY_SERVER_TOKEN}"
}
}
}
}
Claude Code expands environment variables in this file. ${VAR} is replaced with the variable’s value, and ${VAR:-default} falls back to a default when it is not set. Expansion works in command, args, env, url and headers.
That is how you keep secrets out of git: commit the file with ${MY_SERVER_TOKEN} in it, and have each developer set the variable in their own shell. If you would rather not use a variable, do not put the credential in .mcp.json at all. Add the server at local or user scope, where the configuration stays in your home directory.
Worked example: Claude Code for WordPress
Claude Code and WordPress connect through an MCP server on the site. WP MCP is a free plugin that provides one, with a snapshot before every write. You need WordPress 6.9 or newer on PHP 8.1 or newer.
1. Install the plugin and create a credential
Install and activate the plugin:
wp plugin install https://github.com/wpmcp/wordpress-mcp/releases/latest/download/wpmcp.zip --activate
Or download the zip from that address and upload it under Plugins > Add New > Upload Plugin. Then open WP MCP > Connection in wp-admin and create an application password for a user with at least the edit_posts capability (Editor or Administrator). WordPress application passwords covers how they work and how to revoke one.
2. The one-line command
The Connection screen shows this command with your site and credential already filled in:
claude mcp add --transport http wpmcp https://your-site.com/wp-json/mcp/wpmcp-server \
--header "Authorization: Basic BASE64_OF_username:application-password"
The header value is the Base64 encoding of username:application-password. To build it yourself, keep the spaces WordPress generated:
echo -n "your-username:xxxx xxxx xxxx xxxx xxxx xxxx" | base64
3. Or the .mcp.json form
{
"mcpServers": {
"wpmcp": {
"type": "http",
"url": "https://your-site.com/wp-json/mcp/wpmcp-server",
"headers": {
"Authorization": "Basic BASE64_OF_username:application-password"
}
}
}
}
A real Base64 credential in this file is a password in plain sight, since Base64 is an encoding, not encryption. Keep the file out of version control, or replace the value with a variable such as "Basic ${WPMCP_BASIC_AUTH}".
4. A local site: the WP-CLI stdio bridge
On a machine that has WP-CLI and the site’s files, Claude Code can run WP MCP as a local process with no HTTP credentials at all. The command the client runs is wp mcp-stdio serve, and it needs a WordPress user to act as:
claude mcp add wpmcp-local -- wp mcp-stdio serve --user=admin --path=/path/to/wordpress
--user is required because WP-CLI runs as no user by default, and the server refuses to start without one. --path is WP-CLI’s own flag for the WordPress directory. Leave it out if you start Claude Code from that directory.
5. Check it, then try a first prompt
Start Claude Code, run /mcp and confirm wpmcp is connected. Then:
› List the post types on this site.
› Show me the five most recent draft posts.
› Tighten the intro of the About page, and tell me the operation id.
The first two call list-post-types and list-posts. The third reads the page and writes with update-post or a block edit, and the reply carries an operation_id.
6. Undo
› Roll back that last operation.
› Roll back everything from this session.
These call rollback-operation and rollback-session. A person can do the same from the wpmcp screen in wp-admin, where each recent operation has a Restore button. The free plugin keeps the last 20 operations. The full client guide is at Claude Code and WordPress, and the safety design is described in MCP security for WordPress.
Troubleshooting
The server shows as failed. Run claude mcp get wpmcp and check the URL. For WP MCP it must end in /wp-json/mcp/wpmcp-server, and the site has to be reachable from your machine.
401 on every call. The credential was rejected. Rebuild the Base64 string from username:application-password with the spaces kept, or create a new application password and copy the command again. If the credential is right and the 401 persists, the host may be stripping the Authorization header before it reaches WordPress, which some Apache and CGI setups do. That is fixed in the server configuration, so ask your host. A 403 usually means the WordPress user lacks edit_posts.
Too many tools in context. A large server spends context on tool definitions. WP MCP has a compact mode that advertises five tools (list-tools, get-tool-schema, call-tool and two connection basics) while every other tool stays reachable through call-tool. Set the site’s wpmcp_tool_exposure_mode option to compact to turn it on.
A project scoped server does nothing. Servers from .mcp.json need your approval before Claude Code uses them, because the file arrives with the repository. Approve the prompt when it appears. To be asked again, run claude mcp reset-project-choices.
Some tools refuse to run. On WP MCP, risky tools such as permanent deletes, database writes and file writes ship off and reply with the exact filter that enables them. That is by design.
Next step
Install WP MCP on a staging site, copy the command from WP MCP > Connection, run it, and ask Claude Code to list your post types. The tools reference lists every tool you can call after that.
Using the desktop app or Cursor instead? See the Claude Desktop MCP guide and the Cursor MCP guide. To check a server without a client, use MCP Inspector.
New to MCP? Start with the MCP tutorial.
Common questions
How do I add an MCP server to Claude Code?
Run claude mcp add with a name and either a URL (with --transport http) or a local command after a double dash. You can also add an entry to a .mcp.json file in the project root. Then run /mcp inside Claude Code to check that the server is connected.
Where does Claude Code store MCP servers?
Local and user scoped servers are saved in the .claude.json file in your home directory. Project scoped servers are saved in a .mcp.json file at the root of the project, which is meant to be shared with the team.
What is the difference between local, project and user scope?
Local is the default: the server is private to you and available only in the current project. Project scope writes it to .mcp.json so everyone on the repository gets it. User scope makes it available to you in every project.
Can Claude Code work on a WordPress site?
Yes, through an MCP server on the site. WP MCP is a free WordPress plugin that provides one, so Claude Code can read and edit posts, pages, blocks, menus and settings over HTTPS, with a snapshot saved before every write.
How do I remove an MCP server from Claude Code?
Run claude mcp remove followed by the server name. Use claude mcp list first to see the names that are configured.
Why does my MCP server show as failed in Claude Code?
The usual causes are a wrong URL, a server that is not reachable from your machine, or rejected credentials. Run claude mcp get with the server name to see the stored configuration, fix it, and check again with /mcp.
All WP MCP guides, or see every plugin integration. Topic: Connect an AI client.