By Fahad Murtaza · Published
Cursor MCP servers: set up, test and fix, with WordPress
Cursor’s agent can call MCP servers, which means it can do more than edit the files in your project. Point it at a WordPress site that runs an MCP server and it can read and change pages, posts, menus and settings from the same chat where you write code. This guide covers how Cursor’s MCP config works, how to wire it to WordPress with WP MCP, and the problems that come up.
The short WordPress setup is on the WordPress MCP for Cursor page. This guide is the longer version, and most of it applies to any MCP server.
How do I add an MCP server in Cursor? Create .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project. Add the server under mcpServers with a url and optional headers for a remote server, or a command and args for a local one. Open Cursor’s MCP settings and confirm the server is enabled and lists its tools.
How Cursor finds MCP servers
Cursor reads MCP servers from two places:
| File | Scope | Use it for |
|---|---|---|
.cursor/mcp.json in the project root |
This project only | Servers a project needs; the file can be committed if it holds no secret |
~/.cursor/mcp.json in your home directory |
Every project | Servers you want everywhere, such as a site you manage |
Cursor’s settings also list each server with a toggle, its status and the tools it provides. The section has been renamed across versions (Tools and MCP, and more recently under Customize), so look for the MCP servers list. A server that is configured but toggled off does nothing, so look there first when nothing happens.
Cursor supports two kinds of server entry:
- Local (stdio): a
command, optionalargsand optionalenv. Cursor starts the process. - Remote (HTTP): a
urland optionalheaders. Cursor connects to the address. Cursor’s documentation lists Streamable HTTP and SSE for remote servers, with OAuth available for servers that support it.
Unlike Claude Desktop’s config file, which only runs local servers, Cursor accepts remote entries directly. That is why a WordPress site can be added with no bridge. See the Claude Desktop guide for that difference.
Connect Cursor to WordPress
You need a WordPress site with WP MCP active. The free plugin has 274 tools and the safety engine; Pro adds 133 more, including deep Elementor and other page builder editing. See pricing.
Step 1: create an application password
In wp-admin, open WP MCP and then Connection. It creates an application password and shows ready-made snippets for Cursor, Claude Code and Claude Desktop with your address filled in. You can also create one yourself under Users, Profile, Application Passwords; the application password guide covers that.
Use a dedicated user for the agent, with the lowest role that does the job. You can then revoke the password on its own, and the audit log shows its actions under a separate name.
Step 2: encode the credential
The endpoint expects a Basic header, which is the base64 of username:application-password:
echo -n "cursor-agent:xxxx xxxx xxxx xxxx xxxx xxxx" | base64
Keep the spaces in the application password exactly as WordPress generated them.
Step 3: add the entry
In .cursor/mcp.json:
{
"mcpServers": {
"wpmcp": {
"url": "https://your-site.com/wp-json/mcp/wpmcp-server",
"headers": {
"Authorization": "Basic BASE64_OF_username:application-password"
}
}
}
}
Open Cursor’s MCP settings. The server should show as connected, with a tool count. If it shows an error, the message usually names the cause: a 401 means the credential, a 404 means the path.
If the file lives in a repository, do not commit it with the real credential in it. Either keep the entry in ~/.cursor/mcp.json, add .cursor/mcp.json to .gitignore, or have the config read the secret from an environment variable. Cursor expands ${env:NAME} in url, headers, command, args and env, so the header can be "Authorization": "Basic ${env:WPMCP_BASIC}" with the value set in your shell. Check Cursor’s MCP documentation for the current syntax.
Step 4: ask for something
Switch the chat to agent mode and try a read first:
Use the wpmcp server to list the post types, then list my five most recent posts.
Cursor should show tool calls such as list-post-types and list-posts and ask you to approve each one. A result confirms the whole path works: Cursor, the endpoint, the credential and the user’s permissions. If you get a 401 or 403, check that the user has at least the edit_posts capability.
Prompts that work well
Be explicit about the site tool and the scope. These work because each names an object and an outcome:
Find every page that mentions "free shipping" and show me where, with the page ids.
Update the meta description of the page with slug "pricing" to this text, then show me the result.
Create a draft page called "Spring sale" with a heading and three short paragraphs. Do not publish it.
Show me what you changed in this session, then undo the last change.
A developer’s workflow benefits from mixing the two worlds. Cursor can read your theme code in the editor and use the site tools to inspect what the page actually renders, using get-rendered-html, which returns what a logged-out visitor receives. That closes the loop on a front-end fix without leaving the editor.
Undo, and what Cursor’s approval does
Two layers protect a live site, and they do different jobs.
Cursor’s approval prompt stops a tool from running until you accept it. It is useful, but it asks about a call, not about its effect, and people click through after the tenth prompt. Cursor also has an auto-run option, and for a connection that can write to a live site, leave it off for write tools.
WP MCP’s snapshot records the before-image of the target before each supported write, then verifies the result. If the check fails, for example block markup that no longer parses, the change rolls back on its own. If you simply dislike the change, ask Cursor:
List the last five operations, then roll back the one that changed the pricing page.
That uses list-operations and rollback-operation. To unwind a whole conversation, rollback-session returns the site to its state before the session. The WP MCP screen in wp-admin lists every operation with a Restore button as well. Not everything can be snapshotted: package updates, raw database row writes and a few other one-way actions are off by default and report that they cannot be undone. The revisions and undo guide compares what each option covers.
Troubleshooting
The server is listed but the agent ignores it. Confirm agent mode, confirm the server’s toggle is on and that its tools show. Then name the server or a tool in your prompt. Models pick a tool more reliably when the request clearly matches its description.
The tool list is very long, and results get worse.
Every tool definition costs tokens on each request, and Cursor has limited how many tools it sends to the model at various times, so check its current limit. A full WP MCP install can register up to 407 tools, depending on active plugins. The plugin has an optional compact mode that advertises five tools, list-tools, get-tool-schema, call-tool, get-connection-info and get-site-context, and reaches the rest through call-tool. It changes what is listed, not what a call may do. The list-tool-catalog tool shows exactly what your site has.
401 or 403.
Rebuild the base64 value, keep the spaces in the password, check the word Basic and one space before the value, and check the user’s role.
It worked and then stopped. The application password may have been revoked or the user changed. Create a new one on the Connection screen and replace the header.
You are not sure whether the problem is Cursor or the site. Run the same URL and header through MCP Inspector. If it works there, the site is fine and the issue is in the client config.
Cursor reports it cannot parse the config. Validate the JSON. A trailing comma or a stray quote makes Cursor ignore the file.
Cursor compared to other clients
Cursor takes a standard MCP configuration, and WP MCP works with it through the same endpoint and header as any HTTP client. We test mostly with the Claude clients, which are the most exercised path, so if you hit something odd in Cursor, a report with the Cursor version helps. The MCP clients comparison shows how Cursor, the Claude clients and ChatGPT differ on sign-in and setup.
For more on what the server exposes, see the WordPress MCP server page, and the security checklist before you connect a client site.
Common questions
How do I add an MCP server to Cursor?
Create a .cursor/mcp.json file in your project, or ~/.cursor/mcp.json for every project, and add the server under mcpServers. A remote server takes a url and optional headers; a local one takes a command and args. Then open Cursor's MCP settings and check that the server is enabled.
Where is the Cursor MCP config file?
Project servers live in .cursor/mcp.json at the project root, and servers available everywhere live in mcp.json inside the .cursor folder in your home directory. Cursor's settings also have an MCP section that shows each server and its tools.
Does Cursor support remote MCP servers over HTTP?
Yes. A remote server is declared with a url, and you can add headers such as Authorization. That is how a WordPress site with WP MCP connects, using a Basic header built from an application password.
How do I keep a password out of mcp.json?
Cursor expands ${env:NAME} in the config, including in url and headers, so the file can refer to a variable and the secret stays in your shell. Check Cursor's current documentation for the exact syntax, and add the file to .gitignore if it holds a credential.
Why does Cursor not use my MCP tools?
Check that the server is enabled in settings and shows its tools, that you are in agent mode and not plain chat, and that the tool count is not over what Cursor sends to the model. Naming the tool or the task in your prompt helps.
Can Cursor edit a WordPress site safely?
With WP MCP it can. Each supported write is snapshotted first and can be undone one operation at a time or for the whole session. Cursor also asks before running a tool unless you turn on auto-run, so keep approval on for write tools.
All WP MCP guides, or see every plugin integration. Topic: Connect an AI client.