--- title: Site and WordPress account connections description: The two connections a site needs, and which one you actually need. url: https://developers.wpengine.com/docs/ai/api/site-and-account-connections/ image: https://developers.wpengine.com/og/docs/ai/api/site-and-account-connections.png --- # Site and WordPress account connections A WordPress site reaches WP Engine AI through two separate connections, made by different people at different times. A **site connection** puts the site in your account. It is made once, by whoever administers the site, and it is what makes the site visible to everyone on the account. A **WordPress account connection** is yours alone. You only need one **if you want to run WordPress abilities or manage the site** — from Coworker in WP Engine AI, or from an MCP client like Claude Code. Everything else works without it: listing your sites, reading site metadata, and searching a site’s knowledge base all work as soon as the site is connected. If you never intend to have an agent act on a site, you can stop after the site connection. ## Overview | Connection | Who makes it | What it grants | Needed for | | -------------------------------- | ------------------------------ | ----------------------------------------------------------- | ------------------------------------------------------------------------------------ | | **Site connection** | The site’s administrator, once | The site is visible to the whole account | `list_account_sites`, the knowledge base tools | | **WordPress account connection** | Each person, per site | That person may run abilities *as their own WordPress user* | `list_site_abilities`, `run_site_ability`, `search_abilities`, Coworker site actions | The second connection is per person, not per account. Connecting a site grants nobody the ability to act on it — including the administrator who connected it. ## Site connection ### What it is The site is registered to your account. This happens when the site’s administrator installs the WP Engine AI plugin and completes the registration flow. ### What it gives you - The site appears in `list_account_sites` - Site metadata: URL, display name, status - Knowledge base access — `get_site_knowledge_base`, `search_knowledge_base`, and `fetch_knowledge_base_document` — where the knowledge base is enabled ### What it does not give you Running abilities needs the second connection. Until you make one: - `list_site_abilities` returns `not_personally_connected` - `run_site_ability` returns `not_personally_connected` An HTTP site returns `site_requires_https` instead, with no Connect link. `list_account_sites` sets `requires_https` on each site from its URL, so that is visible before either tool is called. A site connection is *account*-scoped. If ten people share the account, all ten see the site — and none of them can act on it until each has connected their own WordPress account. ## WordPress account connection ### What it is You have completed the **Connect WordPress Account** consent flow, started from that site’s WordPress admin. That links three things: - Your identity, from the user authenticated with OAuth - The site - Your WordPress user on that site From then on, abilities you trigger run **as your WordPress user**, with exactly the permissions that user has. ### When you need one Only for acting on a site: - Running WordPress abilities from Coworker in WP Engine AI - Running them from an MCP client — `list_site_abilities`, `run_site_ability`, `search_abilities` You do not need one to list sites, read site metadata, or search a knowledge base. ### How to make one The flow starts in WordPress admin and finishes in WP Engine AI, so expect to be signed in to both. 1. Ask for your sites’ connection status, or call `list_account_sites`. 2. For any site with no `wp_connection_status` at all, the answer carries a link. Open it while logged in to that site’s WordPress admin. If no link comes back, build it from the site URL: `{site_url}/wp-admin/admin.php?page=power-overview&action=trigger_wp_connection` Opening this link is the only way to start the connection — there is no option to start it manually anywhere in WordPress. 3. WordPress hands you to WP Engine AI, signing you in if you aren’t already. Review the permissions on the consent screen there. 4. Confirm with **Connect WordPress user**. You land back in wp-admin, now connected. ![Screenshot: Connect your WordPress account consent screen in WP Engine AI](https://developers.wpengine.com/_astro/wp-level2-consent.DvR_ySTC_Z10p1ty.webp) Once per site, per person. The connection lasts until you revoke it in WordPress admin, your WordPress user is deleted, or your account loses access to the site. ### Why it is separate WordPress abilities can publish posts, delete users, install plugins, change settings, and read private data. Keeping this connection separate and personal buys three things: - **Explicit consent** — nobody acts on a site on your behalf until you say so - **Real user identity** — abilities run as your WordPress user, so your role and capabilities still apply, and the site’s logs name you rather than a service account - **No blast radius from a shared credential** — no one can act on a site as another person The gateway checks the connection on every ability call, so a site you have not authorized stays untouchable. ## Connection states `list_account_sites`, called by a user authenticated with OAuth, reports `wp_connection_status` for each site: | Status | Meaning | What to do | | --------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `connected` | Both connections are in place | Nothing — you can run abilities | | `needs_reconnect` | Your connection went stale | [Re-authorize](https://developers.wpengine.com/docs/ai/api/mcp/troubleshooting/#it-worked-yesterday-and-now-says-the-connection-is-stale) | | `site_requires_https` | The site is not served over HTTPS, so no connection can be made | Enable SSL on the site first | | *(omitted)* | You never connected, or the connection was revoked | [Make the connection](https://developers.wpengine.com/docs/ai/api/site-and-account-connections/#how-to-make-one) | There is no `not_connected` value — when you have no usable connection the field is **absent from the response entirely**. Absence is therefore ambiguous on its own: it cannot distinguish “never connected” from “revoked”. `needs_reconnect` shows up when your WordPress credentials changed, the site invalidated its sessions, or the connection was flagged for reauthorization. The fix is the same as making it the first time — [How to make one](https://developers.wpengine.com/docs/ai/api/site-and-account-connections/#how-to-make-one), opening the link while logged in to wp-admin. ## What each credential can reach | Credential | Sees | Can act on | | --------------------------------- | -------------------------- | -------------------------------------------------- | | **User authenticated with OAuth** | Every site in your account | Sites where *you* connected your WordPress account | | **User API key** | Every site in your account | Sites where *you* connected your WordPress account | | **Account API key** | Every site in your account | Nothing — an account key has no acting user | An account API key can list sites and search knowledge bases, but it resolves no WordPress user, so it can never run an ability. API keys on MCP are deprecated. Where a server refuses API keys, every tool returns `forbidden`, so a key sees and acts on nothing. ## Worked example 1. **Alice’s team connects `example.com`** to their account. The site is now visible to everyone on the account. Alice calls `list_account_sites` and sees `example.com` listed with no `wp_connection_status` field on it. 2. **Alice connects her WordPress account** for `example.com`, because she wants Coworker to draft posts there. She opens the connect link while logged in to wp-admin and authorizes the gateway to act as her WordPress user. 3. **Alice runs an ability.** `run_site_ability` creates a post; the gateway checks her connection first, the ability executes as her WordPress user, and the site’s logs show the post was created by Alice. 4. **Bob, on the same team, tries the same thing.** He gets `not_personally_connected` — the site connection is shared, his WordPress account connection is not. Bob connects his own, or carries on using the site’s knowledge base without one. --- > #### Making the connection > > - [Connect Claude Code — a full setup path, including your WordPress account](https://developers.wpengine.com/docs/ai/api/mcp/how-to/configure-claude-code/) > - [Authentication — MCP clients authenticate with OAuth](https://developers.wpengine.com/docs/ai/api/authentication/#mcp-clients-authenticate-with-oauth) > - [Troubleshooting — fixes by symptom](https://developers.wpengine.com/docs/ai/api/mcp/troubleshooting/) ## Was this helpful? Thanks for the feedback! ```json {"@context":"https://schema.org","@graph":[{"@type":"WebSite","@id":"https://developers.wpengine.com/#website","name":"WP Engine Product Documentation","url":"https://developers.wpengine.com/","description":"Resources for developing, deploying, and scaling on WP Engine.","inLanguage":"en-US","keywords":["API documentation","product documentation","headless WordPress","managed WordPress hosting"],"publisher":{"@id":"https://wpengine.com/#organization"}}]} ```