---
title: "WordPress MCP Adapter Errors: Fix 401, 404 and Application Password Problems"
url: "https://wpimportexport.com/wordpress-mcp-adapter-errors/"
description: "MCP Adapter returns 401, 404 or 400 to your AI agent? Exact error messages, causes and fixes for Application Passwords, sessions and missing abilities."
type: post
published: 2026-11-05T19:58:49+00:00
modified: 2026-11-14T10:41:00+00:00
categories: ["AI", "Tutorials"]
tags: ["Abilities API", "AI Agents", "Import Export by RockStarLab", "WordPress automation", "WordPress Import Export Plugin"]
docs_topics: ["Plugin comparisons"]
---

# WordPress MCP Adapter Errors: Fix 401, 404 and Application Password Problems

Connecting an AI agent such as Claude Code, Cursor, GitHub Copilot or Codex to WordPress through the [MCP Adapter](https://wordpress.org/plugins/mcp-adapter/) usually takes a few minutes. When it does not work, the agent shows a short error like “HTTP 401”, “Failed to connect” or “not found”, and it is not obvious which part of the chain broke: the address, the Application Password, the adapter, the session or the permissions.

We reproduced these errors on a test site. Below are the exact messages, what causes each one and the fix. The tests used WordPress 7.1, MCP Adapter 0.7.1 and [Import Export by RockStarLab](https://wordpress.org/plugins/import-export-by-rockstarlab/) 2.1.18, whose setup wizard checks most of these points for you.

## Quick Reference

| What you see | Most likely cause | Fix |
| --- | --- | --- |
| HTTP 401, `rest_forbidden`, “Sorry, you are not allowed to do that.” | Wrong or missing Application Password, or the header never reaches WordPress | HTTP 401 |
| No **Application Passwords** section in the profile | Site without HTTPS, or the feature is turned off | Application Passwords missing |
| HTTP 404, `rest_no_route` | MCP Adapter inactive or wrong address | HTTP 404 |
| “HTTP 404: Invalid OAuth error response” | No Authorization header in the client settings | OAuth error |
| HTTP 400, “Missing Mcp-Session-Id header” | The client or a proxy drops the session header | Session errors |
| HTTP 400, “MCP-Protocol-Version header is required” | VS Code / GitHub Copilot does not send the header | Protocol version |
| “Ability … not found on this WordPress site” | The plugin that provides the ability does not allow agent access | Abilities missing |
| “You do not have permission to use the plugin API.” | The Application Password belongs to a non-administrator | Permission errors |

## How the Connection Is Checked

Every request from the agent goes through the same steps, and each error belongs to one of them:

1. **Address.** The request goes to `/wp-json/mcp/mcp-adapter-default-server`. If WordPress has no such route, the answer is 404.
2. **Login.** WordPress checks the username and the Application Password in the `Authorization` header. If that fails, the answer is 401.
3. **Session.** The first request opens a session; later requests must send its ID and the agreed protocol version. If they do not, the answer is 400.
4. **Abilities.** The agent lists the actions that plugins make available and runs one of them. An action that is not available returns “not found”.
5. **Permissions.** The plugin checks the user’s rights before it runs the action.

The errors as Claude Code and VS Code show them:

![Claude Code showing Failed to connect with HTTP 401 rest_forbidden and HTTP 404 Invalid OAuth error response, and VS Code showing Error 400 MCP-Protocol-Version header is required](https://wpimportexport.com/wp-content/uploads/2026/11/01-mcp-errors-in-clients.webp)

_Three connection errors as Claude Code and VS Code report them._

## HTTP 401: “Sorry, you are not allowed to do that.”

WordPress answered, but did not accept the login. On our test site, all of these produced exactly the same 401 response with the code `rest_forbidden`:

- a wrong Application Password;
- the normal login password instead of an Application Password;
- no `Authorization` header at all;
- a valid Application Password on a site where Application Passwords are turned off.

These variants, on the other hand, worked: the account’s email address instead of the username, and the Application Password with the spaces WordPress shows (`abcd efgh ijkl ...`) or without them.

How to fix it:

1. Create a new Application Password in **Users > Profile**. The normal login password never works for API requests.
2. Generate the client settings again, for example with the wizard in **Import Export by RockStarLab > Plugin Options > AI Agent Connection**, and replace the old entry in the client. Most clients do not overwrite an existing server with the same name.
3. If a correct password still returns 401, the header may be removed on the way. Some Apache setups drop `Authorization` before PHP sees it. Add this line to `.htaccess` above the WordPress rules, or ask your host to pass the header through:

   ```
   SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
   ```
4. Check security plugins, a firewall or a CDN rule that blocks REST API requests or Basic authentication.

In Codex, a 401 in the log does not always come from the site you are working on: Codex starts every server in `config.toml`, so an old entry for another site can fail while yours works.

## Application Passwords Are Missing

If the profile has no **Application Passwords** section, WordPress has turned the feature off. By default it is only available on sites served over HTTPS, and on sites marked as a local development environment. Security plugins can also turn it off for all users or for some roles. The wizard of Import Export by RockStarLab shows this as a warning in step 3:

![Wizard step 3 warning that Application Passwords are unavailable for this account or site](https://wpimportexport.com/wp-content/uploads/2026/11/03-application-passwords-unavailable.webp)

_The wizard warns when WordPress has turned off Application Passwords._

Turn on HTTPS for a live site, or check the settings of security and login plugins. A local site from Local, DevKinsta or wp-env is usually marked as local and works over plain HTTP.

## HTTP 404: “No route was found matching the URL”

The site answered with `rest_no_route`. We got exactly this response in two cases:

- **MCP Adapter is not active.** The route only exists while the plugin runs. The wizard shows **Action needed** in step 2 with an **Activate MCP Adapter** button.
- **The address is wrong.** The default server is `/wp-json/mcp/mcp-adapter-default-server`. A shortened address such as `/wp-json/mcp/default-server` returns the same 404.

![Import Export by RockStarLab wizard step 2 Enable MCP Adapter with the status Action needed and an Activate MCP Adapter button](https://wpimportexport.com/wp-content/uploads/2026/11/02-mcp-adapter-not-active.webp)

_When MCP Adapter is inactive, the MCP route returns 404 and the wizard shows Action needed._

If your site uses plain permalinks (**Settings > Permalinks > Plain**), `/wp-json/` addresses do not work at all. Switch to any other permalink structure, or use `https://your-site.com/?rest_route=/mcp/mcp-adapter-default-server` as the address.

## “HTTP 404: Invalid OAuth error response”

Claude Code shows this when the server was added without an `Authorization` header. WordPress refuses the request, Claude Code then tries to start an OAuth sign-in, finds an HTML page instead of an OAuth server and reports the 404. Remove the server and add it again with the header, for example with the command from the wizard. MCP Adapter signs in with Application Passwords, not with OAuth.

## “Missing Mcp-Session-Id header”

The first request (`initialize`) opens a session, and the answer carries an `Mcp-Session-Id` header. Every later request must send it back. Without it, MCP Adapter answers with HTTP 400 and “Invalid Request: Missing Mcp-Session-Id header”. Ready-made clients handle this themselves. You will see this error with your own scripts, or with a proxy or gateway that removes unknown headers. Allow the `Mcp-Session-Id` and `MCP-Protocol-Version` headers through any proxy, and exclude `/wp-json/mcp/` from caching and firewall rules.

MCP Adapter also ends sessions after a period of inactivity. If a client shows a session error after a long break, restart the MCP server in the client or start a new chat.

## “MCP-Protocol-Version header is required”

This 400 error appears with GitHub Copilot in VS Code. The MCP protocol asks clients to send an `MCP-Protocol-Version` header with every request after the first one. VS Code 1.139 does not send it, and MCP Adapter 0.7.1 refuses those requests, so Copilot never receives its tools. In our tests Claude Code, Cursor and Codex sent the header and were not affected.

Import Export by RockStarLab 2.1.18 and newer fills in a missing header with the protocol version that was already agreed for the session; a header the client does send is never changed. With the plugin active, Copilot connects normally. The full setup is described in [How to Connect GitHub Copilot to WordPress via MCP](https://wpimportexport.com/connect-github-copilot-to-wordpress-mcp/).

## Connected, but the Abilities Are Missing

The agent connects and lists some abilities, but not the ones you expect, and running one returns:

```
Ability 'rsl-ie/get-capabilities' not found on this WordPress site, and no ability you can call has a similar name. Call the mcp-adapter-discover-abilities tool to see what this site offers, or tell the user this site cannot do it.
```

MCP Adapter only offers abilities that a plugin has registered and made available to agents. On our test site, the list shrank from 118 abilities to 13 when we turned off **Enable Abilities API** in Import Export by RockStarLab: only WordPress core and other plugins remained. The switch is off by default:

![Import Export by RockStarLab AI Agent Connection with the Enable Abilities API switch turned off](https://wpimportexport.com/wp-content/uploads/2026/11/04-abilities-api-disabled.webp)

_With Enable Abilities API off, the plugin's actions are not offered to agents._

Turn it on in **Import Export by RockStarLab > Plugin Options > AI Agent Connection**. For abilities of other plugins, check their settings in the same way. Some clients remember the list of tools, so start a new chat or restart the server in the client after the change.

## “You do not have permission to use the plugin API.”

We created an Application Password for a user with the **Editor** role. The connection worked and the agent saw all abilities, but every Import Export by RockStarLab action returned “You do not have permission to use the plugin API.” The plugin’s actions require an administrator (the `manage_options` capability), because exports, imports and syncs can read and change the whole site. Use an Application Password of an administrator account. Other plugins can have their own rules, and every ability checks the rights of the signed-in user.

## Test the Connection Without an Agent

A single `curl` request shows whether the address and the login work, independent of any client:

```
curl -i -u 'admin:abcd efgh ijkl mnop qrst uvwx' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' \
  https://your-site.com/wp-json/mcp/mcp-adapter-default-server
```

- **HTTP 200** with an `Mcp-Session-Id` header: the site, the adapter and the password are fine; look at the client settings.
- **401**: the login failed, see HTTP 401.
- **404**: the route does not exist, see HTTP 404.

Replace the username and password with your own, and remove the command from your shell history afterwards, because it contains the password.

The wizard in Import Export by RockStarLab runs similar checks in the browser: step 1 tests the authenticated REST API, step 2 the adapter and step 3 whether Application Passwords are available. If step 1 shows “Setup paused: the REST API is not ready”, fix that first, because nothing else can work until it is resolved.

## FAQ

### Is an Application Password safe to give to an AI agent?

It can only be used for API requests, not to log in to the dashboard, and it can be revoked at any time in the profile without changing your normal password. Create one per tool or computer, so you can revoke one without breaking the others.

### Do I need a separate administrator account for the agent?

Not necessarily, but a separate account makes it easy to see in the profile when the agent last connected and to revoke its access. It must have administrator rights for the Import Export by RockStarLab actions.

### Where are the setup guides for each agent?

Step-by-step guides with tested requests are available for [Claude Code](https://wpimportexport.com/connect-claude-code-to-wordpress-mcp/), [GitHub Copilot](https://wpimportexport.com/connect-github-copilot-to-wordpress-mcp/), [Cursor](https://wpimportexport.com/connect-cursor-to-wordpress-mcp/) and [OpenAI Codex](https://wpimportexport.com/connect-codex-to-wordpress-mcp/).

## Related Guides

- [Letting an AI Agent Edit WordPress Content Safely: Permissions, Staging, Rollback](https://wpimportexport.com/ai-agent-edit-wordpress-content-safely/)
- [How to connect Claude Code to WordPress via MCP](https://wpimportexport.com/connect-claude-code-to-wordpress-mcp/)
- [How to connect GitHub Copilot to WordPress via MCP](https://wpimportexport.com/connect-github-copilot-to-wordpress-mcp/)
- [How to connect Cursor to WordPress via MCP](https://wpimportexport.com/connect-cursor-to-wordpress-mcp/)
- [How to connect OpenAI Codex to WordPress via MCP](https://wpimportexport.com/connect-codex-to-wordpress-mcp/)
- [How to use the WordPress Abilities API with AI agents](https://wpimportexport.com/how-to-use-the-wordpress-abilities-api-with-ai-agents-exports-imports-content-sync-and-backups/)

Import Export by RockStarLab is free on [WordPress.org](https://wordpress.org/plugins/import-export-by-rockstarlab/).
