By Fahad Murtaza · Published
Claude Desktop MCP servers: config file, bridge and fixes
Claude Desktop can use MCP servers, and a WordPress site can be one. The catch that costs people an evening is that the desktop app’s config file does not work the way the one in Claude Code does. This guide shows what the file accepts, three working routes to a WordPress site, and how to fix the usual failures.
The WordPress side is WP MCP. For the short version of connecting it to Claude, see WordPress MCP for Claude. This guide goes deeper on the config file itself, which is what most “Claude Desktop MCP” searches are about.
How do I add an MCP server to Claude Desktop? Open Settings, go to Developer and choose Edit Config. Add the server under mcpServers in claude_desktop_config.json, save, then fully quit and reopen the app. The file runs local programs, so a remote server needs a bridge, a bundle or a custom connector.
Where the config file lives
| System | Path |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json (per the MCP docs) |
The quickest way to open it is from the app: Settings, then Developer, then Edit Config. If the file does not exist yet, that button creates it.
The structure is one JSON object with an mcpServers map. Each key is a name you choose, and each value says how to start that server:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
}
}
}
That is a local stdio server: Claude Desktop starts npx as a child process and talks to it over standard input and output. Everything in this file follows that pattern, a command, optional args and optional env.
The rule that surprises people
Claude Desktop does not read url entries from this file. The file only runs local (stdio) servers. An entry with "type": "http", "url" or "headers", the shape that works in Claude Code and in Cursor, is skipped, and the app reports that it is not a valid MCP server configuration.
So a WordPress site, which is a remote HTTP server, cannot go straight into the file. There are three routes that work.
| Route | Sign-in | Needs | Pick it when |
|---|---|---|---|
Desktop bundle (.mcpb) |
Application password, typed once | Nothing else installed | You want the shortest path |
mcp-remote bridge in the config file |
Application password in an environment variable | Node.js | You want it in a file you can version and script |
| Custom connector | OAuth, approved in the browser | OAuth switched on, and a public site | You want OAuth instead of a password |
Route 1: the desktop bundle
An .mcpb file is a packaged local server that Claude Desktop installs by double-click. WP MCP generates one for your site.
- In wp-admin, open WP MCP and then Connection.
- Create an application password there. The screen shows it once.
- Download
wpmcp.mcpb. - Double-click the file. Claude Desktop asks you to confirm and then asks for the username and the application password.
- Enter them and finish.
The bundle contains no credentials, and it needs nothing else installed, so there is no Node.js step. Start a new chat, open the + menu in the message box and check Connectors to confirm the server is listed.
Use a dedicated WordPress user for this, not your administrator account, so you can revoke the password on its own. The application password guide shows how to create and revoke one.
Route 2: the mcp-remote bridge
mcp-remote is a small Node.js program that looks like a local stdio server to Claude Desktop and forwards everything to a remote HTTP server. It can add a header on the way, which is what an application password needs.
You need Node.js installed. Then add this entry, replacing the site address:
{
"mcpServers": {
"wpmcp": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://your-site.com/wp-json/mcp/wpmcp-server",
"--header",
"Authorization:${WPMCP_AUTH_HEADER}"
],
"env": {
"WPMCP_AUTH_HEADER": "Basic BASE64_OF_username:application-password"
}
}
}
}
Two details matter here. Keep Authorization:${WPMCP_AUTH_HEADER} with no space after the colon. The value, which contains a space after Basic, goes in env, because a space inside an argument is easy to break on some systems.
Create the base64 value in a terminal, keeping the spaces in the application password exactly as WordPress showed them:
echo -n "your-username:xxxx xxxx xxxx xxxx xxxx xxxx" | base64
Save the file, then fully quit Claude Desktop and open it again. The file is read at startup. On macOS use Quit from the app menu, and on Windows quit from the tray icon, because closing the window can leave the app running.
If you add more servers later, keep valid JSON: a trailing comma between entries is the single most common reason the whole file is ignored.
Route 3: the custom connector
Customize has a Connectors section (older versions: Settings) with an Add custom connector option. You enter the endpoint URL and the app signs in with OAuth. WP MCP’s connector route cannot send an application password. Custom connectors are tied to your Claude account and work in Claude Desktop, claude.ai and mobile, rather than being read from the config file.
WP MCP ships OAuth switched off, so the connector fails until the site owner turns it on. The steps are in the custom connectors guide. This route also needs the site to be reachable from the internet, because the request does not come from your computer.
Check that it works
Start a new chat and ask:
List the post types on my WordPress site, then list my five newest posts.
Claude should ask permission to use a tool and then call list-post-types and list-posts. If it answers without calling anything, check the tools menu in the chat to see whether the server is listed and switched on.
Then try something small that can be undone:
Create a draft post titled "Desktop test" and add one paragraph.
Then undo that change.
WP MCP snapshots each supported write before it happens, so Claude can call list-operations and rollback-operation, and you can press Restore on the WP MCP screen in wp-admin. A few changes cannot be snapshotted, such as package updates and raw database row writes. Those are off by default and say so in their response. See the revisions guide for how this compares with core revisions.
Troubleshooting
The server does not appear at all. Check the JSON first. Paste the file into a JSON validator and look for a trailing comma or a missing quote. Then confirm you fully quit and reopened the app.
A message says the entry is not a valid MCP server configuration.
You used url, type or headers in the file. Switch to the bundle, the bridge or the connector.
The server appears but shows an error.
Open the logs. On macOS they are in ~/Library/Logs/Claude/, with one mcp-server-<name>.log per server and an mcp.log for the app. The bridge prints connection errors there, including a 401 from the site.
A 401 or 403 from the site. The credential is wrong, or the user lacks a role that can edit posts. Re-create the base64 value, keep the spaces in the application password, and check that an Editor or Administrator role is assigned.
npx is not found.
Claude Desktop starts the command without your shell profile, so it may not find a Node.js installed by a version manager. Install Node.js system-wide, or put the full path to npx in command.
The chat reports 0 tools while Settings lists them. Update the plugin first. A past release sent a tool list that some clients rejected whole, because no-argument tools carried an empty array where an object was expected. If it persists on a current version, the cause is on the client side. Check the web server log for requests from Claude while the chat lists tools, and if none arrive the app is not asking your site. Note the Claude Desktop version when you report it. The bundle and the bridge are working routes in the meantime.
Too many tools.
A full install can register up to 407 tools: 274 free and 133 Pro. The count on your site depends on which plugins are active. A client pays token cost for every tool definition, so WP MCP has an optional compact mode that advertises five tools and reaches the rest through call-tool. It changes only what is listed, not what a call may do.
To see exactly what your server returns without Claude in the way, use MCP Inspector.
Desktop or Claude Code
Claude Desktop is the friendlier surface for non-developers and the weaker one for configuration, because of the stdio-only file. If you work in a terminal, Claude Code takes the remote URL and the header directly, in one command or one .mcp.json entry. Both are the most tested clients for WP MCP.
If you are comparing clients more broadly, MCP clients compared lays out how they differ. For what the server exposes, see the WordPress MCP server page, and pricing for the Pro tools.
Common questions
Where is the Claude Desktop MCP config file?
On macOS it is ~/Library/Application Support/Claude/claude_desktop_config.json, and on Windows it is %APPDATA%\Claude\claude_desktop_config.json. You can also open it from Settings, Developer, Edit Config. The servers go under a top-level mcpServers key.
Why does Claude Desktop say my MCP server is not valid?
The config file runs local stdio servers only. An entry with type http, a url or headers is skipped with a message that it is not a valid MCP server configuration. Use a bridge such as mcp-remote, a desktop bundle, or add the server as a custom connector instead.
Do I need to restart Claude Desktop after editing the config?
Yes. Claude Desktop reads the file at startup, so fully quit the app and open it again. Closing the window is not enough on every system, so quit from the app menu or the tray icon.
Can Claude Desktop connect to a remote MCP server?
Yes, in two ways. Add it as a custom connector under Customize, Connectors, which signs in with OAuth, or run a local bridge such as mcp-remote from the config file, which can send an Authorization header. A plain url entry in the config file does not work.
How do I connect Claude Desktop to WordPress?
Install WP MCP on the site, create an application password on its Connection screen, and download the wpmcp.mcpb bundle, or use the mcp-remote entry in the config file. Both send the credential as a Basic Authorization header to the site's MCP endpoint.
Why does Claude Desktop show zero tools for my server?
Update the plugin first, because a malformed no-argument tool schema in older releases could make a client drop the whole list. If it persists, check the web server log for requests while Claude lists tools, and note the Claude Desktop version when reporting it.
All WP MCP guides, or see every plugin integration. Topic: Connect an AI client.