Get the plugin
WP MCP/Blog/Post

By · Published · Updated

MCP OAuth Explained: How Authorization Works on WordPress

securitymcp

MCP OAuth is how a remote MCP server lets a client act for a user without ever seeing the user’s password. The client discovers the server’s authorization server, sends the user to sign in and approve, and receives a short-lived access token that it sends as a Bearer header on every request. It is based on OAuth 2.1 with PKCE.

This post explains the flow in plain language, then shows how it works on a WordPress site with WP MCP, including the parts that are off by default.

Why remote MCP servers need authorization

An MCP server can be reached in two ways. A local server runs over stdio: the client starts it as a process on your machine and talks to it through standard input and output. There is no network request to authorize: the server has whatever access that local process has.

A remote server is reached over HTTP. Anyone on the internet can send it a request, so it must know who is calling and what they may do. The MCP specification makes authorization optional, but when an HTTP server protects access, the spec describes an OAuth-based way to do it. (If the difference between MCP and a plain HTTP API is unclear, see MCP vs API.)

The flow, step by step

The MCP authorization spec builds on OAuth 2.1 and a handful of related standards. In order:

  1. The first request is refused. The client calls the MCP endpoint with no token. The server answers 401 with a WWW-Authenticate header that points to its protected resource metadata.
  2. Protected resource metadata. This is a small JSON document (commonly under /.well-known/oauth-protected-resource) that says: this is the resource, and these are the authorization servers that issue tokens for it.
  3. Authorization server discovery. The client fetches the authorization server’s metadata, which lists its authorize, token and registration endpoints and what it supports.
  4. The client identifies itself. See the next section.
  5. The user signs in and approves. The client opens a browser to the authorize endpoint with a PKCE challenge. The user signs in on the server’s own site and approves the client.
  6. Code for token. The browser returns to the client with a one-time authorization code. The client exchanges it at the token endpoint, proving it holds the PKCE verifier that matches the earlier challenge.
  7. Bearer on every request. The client sends Authorization: Bearer <token> with each MCP request. When the access token expires, it uses a refresh token to get a new one.

PKCE (Proof Key for Code Exchange) is what protects step 6. The client makes a random secret, sends only a hash of it at the start, and reveals the secret at the end. An intercepted authorization code is useless without that secret. OAuth 2.1 requires PKCE for this flow.

The client also names the resource it wants a token for, so a token issued for one MCP server is not valid at another.

How the client introduces itself

An authorization server needs to know which client is asking, and where it is allowed to send the user back. MCP clients connect to servers they have never seen before, so manual registration does not scale. Two mechanisms cover this:

  • Dynamic client registration. The client posts its name and redirect addresses to a registration endpoint and receives a client ID.
  • Client ID metadata documents. The newer method, which the MCP authorization spec now prefers. The client ID is an https URL. At that URL the client hosts a JSON document with its name and redirect addresses, and the authorization server fetches it. Nothing is registered in advance.

OAuth vs a static credential

The alternative to all of this is a static credential in a header. On WordPress that is an application password sent as Basic auth: the Base64 encoding of username:application-password. The application passwords guide covers how to create one.

Application password (Basic) OAuth 2.1
Secret in a config file Yes, and it does not expire No
Lifetime Until revoked Short-lived access token, renewed by refresh token
Limit access Through the WordPress user’s role Role, plus full or read-only per connection
Revoke one client Revoke that password Block the client or lower its access
Where the credential works Wherever WordPress accepts application passwords Only at the MCP endpoint (in WP MCP)
Client support Claude Code, Cursor, Claude Desktop bundle Required by ChatGPT and the Claude custom connector
WP MCP default Works on a default install Off until a site administrator enables it

A static credential is easier and fits one developer with one tool. OAuth fits clients that cannot send a header, shared setups, and read-only access.

WordPress MCP OAuth in WP MCP

WP MCP ships a full OAuth 2.1 authorization server with PKCE, where the S256 method is mandatory. It is off by default, and there is no switch for it in wp-admin. A site administrator turns it on with one line in wp-config.php, above the “stop editing” comment:

define( 'WPMCP_OAUTH_ENABLED', true );

Or, from a plugin or mu-plugin:

add_filter( 'wpmcp_oauth_enabled', '__return_true' );

Either one is enough. While OAuth is off, the discovery addresses return 404 and an OAuth-only client cannot register or sign in. That is the default state, not a fault. Once it is on, the Connection screen in wp-admin lists the discovery addresses clients use for the site.

What the documented behaviour gives you after that:

  • You choose the access level at approval. Full access (the mcp scope, limited to what your WordPress user can do), read-only (the mcp:read scope, refused anything that changes the site), or, for site owners, a scoped identity.
  • Access can be lowered later. Changing a connection on the Connection screen takes effect on its next request, with no reconnecting. A token never gains scope when it is refreshed.
  • Tokens are bound to the MCP endpoint. An access token does not authenticate the rest of the WordPress REST API or admin-ajax.
  • Both registration methods work: dynamic registration and client metadata documents.
  • New clients can require approval. Site owners can turn on approval for new OAuth clients, then approve or block each one on the Connection screen. Blocking a client revokes its tokens.
  • Metadata fetches are restricted. The site fetches a client metadata document only while a signed-in user is authorizing that client, over https only, and it refuses private and loopback addresses and does not follow redirects.

OAuth does not replace the rest of the safety model. A token still acts as a WordPress user, every ability is still capability-checked, and every write still takes a snapshot first. MCP security for WordPress covers that side.

Which clients need OAuth

  • ChatGPT can only sign in with OAuth. It cannot send an application password, so OAuth must be on. It works through OAuth once enabled, but it is not fully tested with WP MCP yet. The ChatGPT and WordPress page has the setup steps.
  • Claude Code uses an application password and works on a default install. See Claude Code and WordPress.
  • Claude Desktop uses an application password through the desktop bundle or a config file. The custom connector route signs in with OAuth. See Claude and WordPress.
  • Cursor uses an application password. See Cursor and WordPress.

The Claude clients are the most tested path.

Which should I use

Your situation Use
One developer, Claude Code or Cursor Application password on a dedicated user
ChatGPT, or the Claude custom connector OAuth, since there is no other option
You want an agent that can only read OAuth with read-only access
Several people or clients on one site OAuth, with approval for new clients turned on
You cannot edit wp-config.php or add a plugin Application password

Honest limits

  • Enabling OAuth needs access to wp-config.php or the ability to add a small plugin. A switch on the Connection screen is planned, with no date promised.
  • The ChatGPT round trip is not fully tested. Expect to verify it yourself with a read-only connection first.
  • OAuth controls who may connect and at what level. It does not make an agent’s decisions correct.

Next step

Decide which client you are connecting. If it is ChatGPT, follow the ChatGPT and WordPress setup and approve it as read-only first. For anything else, start with an application password.

OAuth matters most for remote servers: remote MCP servers compares stdio with Streamable HTTP and covers both sign-in styles, and the Claude custom connectors guide uses OAuth end to end.

If you are choosing between sign-in options, see MCP authentication methods compared.

Common questions

Does MCP require OAuth?

No. Authorization is optional in the Model Context Protocol. Servers reached over HTTP are expected to follow the OAuth-based authorization spec when they protect access, while local stdio servers take credentials from their environment instead. Many HTTP servers also accept a static credential in a header.

Does ChatGPT need OAuth to connect to WordPress?

Yes. ChatGPT signs in to a custom MCP server with OAuth and cannot send a WordPress application password. With WP MCP, a site administrator has to switch OAuth on in wp-config.php first, and this route is not fully tested yet.

How do I enable OAuth in WP MCP?

Add define( 'WPMCP_OAUTH_ENABLED', true ); to wp-config.php, or return true from the wpmcp_oauth_enabled filter in a plugin or mu-plugin. There is no switch for it in wp-admin today.

Is OAuth more secure than an application password?

It has real advantages: no long-lived secret sits in a config file, access tokens expire, access can be read-only, and one client can be revoked on its own. An application password on a dedicated low-privilege user is still a sound choice for a single developer tool, and it is the more tested route with WP MCP.

What is a client ID metadata document?

It is a small JSON file a client hosts at an https URL, and that URL is used as the client ID. The authorization server fetches it to learn the client's name and allowed redirect addresses, so the client does not have to register in advance.

Do local MCP servers need OAuth?

No. A stdio server runs as a local process started by the client, so there is no network request to authenticate. It uses whatever access the local process already has.