OAuth sign-in

OAuth sign-in lets an AI client connect to your site by approving a one-time browser prompt from your WordPress login, instead of generating and pasting an Application Password. It’s free, built in, and on by default on HTTPS sites.

Under the hood it’s a self-contained OAuth 2.1 authorization server (discovery metadata, Dynamic Client Registration, PKCE), you don’t configure any of it. The client discovers the endpoints, you click Approve, and it’s connected.

Requirements

Before approving a client, review WordPress MCP permissions and access. The guide explains the acting user, site-wide tool controls, and how to check your first task.

• HTTPS. OAuth is only offered on sites served over https:// (local development hosts such as localhost or *.test also qualify). On an HTTP site, use an Application Password instead.
• Administrator. Only administrators can approve a connection, the consent screen refuses non-admins.
• Enabled. It’s on by default when available. Confirm (or toggle) it with the OAuth sign-in switch under EMCP Tools → Connection → Advanced settings, then click Save. When it is off, step 2 of the Connection wizard (“Pick how it signs in”) greys out the OAuth card with “Turn on OAuth sign-in in Advanced settings.” and offers Application password (plus WP-CLI on this computer on local sites).

How it works

1. In your MCP client, add this site as an HTTP / Streamable-HTTP server using just the URL: no Authorization header:

   https://your-site.com/wp-json/mcp/emcp-tools-server

2. The client detects that the server wants authorization and opens your browser.

3. You confirm you’re signed in as the right WordPress user and click Approve.

4. The client receives a token and connects. That’s it, no password ever touches the client config.

The EMCP Tools → Connection wizard walks through this for each supported client: pick the client in step 1, OAuth in step 2, follow the client-specific instructions in step 3 (a terminal command, a config file, a connector form or a one-click install link), then step 4 waits for the client’s first MCP call and confirms it. If a client already signed in once and will not show the consent screen again, choose it under Reconnect an app that is already connected in step 3 so step 4 recognises it. The Connection screen page describes every part of the screen.

The token acts as the authorizing administrator, so every tool still runs through its own capability check, OAuth grants no extra privilege. Access tokens are short-lived (1 hour) and refresh automatically via a rotating 30-day refresh token.

Per-client steps are on each connection page: Claude Code, Claude Desktop, Cursor, VS Code, ChatGPT App, Antigravity, OpenClaw, Hermes.

Managing connected apps

Every app that registers appears under Connected apps, on the right of EMCP Tools → Connection, with its state (Connected, Signed out or Never signed in) and the WordPress user it acts as. Two actions:

• Sign out cuts its access immediately by revoking its tokens. The client can sign in again to reconnect.
• The trash icon (Remove) deletes the app and its tokens. The client must register again to connect.

Both ask for confirmation first. The EMCP Cloud gateway’s credential shows here as EMCP Gateway.

When to use an Application Password instead

OAuth is the recommended path, but an Application Password is the right choice when:

• your site is HTTP-only (OAuth is HTTPS-gated), or
• your host blocks /.well-known/ requests (see below), or
• you’re connecting through a stdio bridge such as the Node proxy, which signs in with a password. (The Connection wizard’s WP-CLI on this computer method, on local sites, needs neither: WP-CLI runs as a WordPress user on the same machine.)

Application Passwords keep working alongside OAuth, nothing you’ve already set up breaks. See Auth errors if a connection fails.

Host blocking /.well-known/

OAuth clients discover the server by requesting /.well-known/oauth-protected-resource (RFC 9728). Some managed hosts (and some nginx/openresty defaults) deny every /.well-known/ path except ACME challenges at the web-server layer, before the request ever reaches WordPress. When that happens the client can’t discover the OAuth endpoints and sign-in fails with a discovery/404 error, even though the plugin is configured correctly.

To check, open step 4 of the Connection wizard with OAuth chosen: when no call arrives it shows “No call yet” and a Run a server test button that tests OAuth discovery. If you hit this, either ask your host to allow /.well-known/ requests, or use an Application Password instead, it doesn’t rely on discovery. A CDN or WAF (Cloudflare’s bot-fight mode especially) can cause the same symptom by blocking the client’s own requests to those endpoints even though your browser reaches them fine. See Auth errors for the exact paths to allow-list.

Server URL

EMCP Tools → Connection → Advanced settings has a Server URL override field, normally left blank; its placeholder shows the auto-detected address (“Auto-detected: …”). Click Save after changing it. Every OAuth endpoint above, and the .mcpb bundle’s baked-in URL, is built from this value. Override it only if the site is served on a different address than WordPress’s configured Site Address, e.g. a staging site whose domain is pinned to a not-yet-live production URL.

Dedicated users and credential changes

A dedicated administrator can be the identity used for EMCP operations. For Gateway, connect or reissue the credential while signed in as the intended WordPress administrator. The token is bound to that user’s ID; there is no required administrator username.

This does not restrict other administrators from the EMCP menu or settings. Those use manage_options; there is currently no built-in EMCP administrator allowlist. Hiding a menu entry does not deny direct access. See fleet access and credentials.

OAuth clients must retain replacement refresh tokens returned during refresh. Gateway handles that rotation and writes the replacement credential back to Cloud. For direct Application Password connections, create a replacement, update each consuming client, verify the new connection, then revoke the old credential. Reissuing a Gateway credential is a connection repair operation; do not assume it revokes every older authorization. Use the explicit revocation controls when withdrawing access.