--- title: Site and WordPress account connections description: The two connections a site needs, and which one you 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. Different people make them at different times. A **site connection** puts the site in your account. The site’s administrator makes it once. It makes the site visible to everyone on the account. A **WordPress account connection** is yours alone. You need one only **if you want to run WordPress abilities or manage the site**, from Coworker in WP Engine AI or from a Model Context Protocol (MCP) client such as Claude Code. Everything else works without a WordPress account connection. You can list your sites, read site metadata, and search a site’s knowledge base as soon as the administrator connects the site. If you never intend to have an agent act on a site, you can stop after the site connection. ## Compare the two connections | 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 WordPress account connection is per person, not per account. A site connection doesn’t let anyone act on the site, including the administrator who connected it. ## Site connection ### What it is A site connection registers the site to your account. The site’s administrator makes it by installing the WP Engine AI plugin and completing 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 To run abilities, you need a WordPress account connection. Until you make one: - `list_site_abilities` returns `not_personally_connected` - `run_site_ability` returns `not_personally_connected` For an HTTP site, these tools return `site_requires_https` instead, with no Connect link. `list_account_sites` sets `requires_https` on each site from its URL, so you can see it before you call either tool. A site connection is *account*-scoped. If ten people share the account, all ten see the site. None of them can act on it until each one connects their own WordPress account. ## WordPress account connection ### What it is You make a WordPress account connection by completing the **Connect WordPress Account** consent flow, which starts from that site’s WordPress admin. The flow 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 You need one only to act 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 don’t need one to list sites, read site metadata, or search a knowledge base. ### Connect your WordPress account The flow starts in WordPress admin and finishes in WP Engine AI, so you’ll 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` field, call `list_site_abilities` for that site. The `not_personally_connected` error returns the link as `connect_url`. Open the link while you’re 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. WordPress has no option anywhere to start it manually. 3. WordPress hands you off to WP Engine AI and signs you in if you aren’t signed in already. Review the permissions on the consent screen. 4. Click **Connect WordPress user** to confirm. You return to wp-admin with the connection in place. ![Screenshot: Connect your WordPress account consent screen in WP Engine AI](https://developers.wpengine.com/_astro/wp-level2-consent.DvR_ySTC_Z10p1ty.webp) You make this connection once per site, per person. It lasts until one of the following happens: - The site is disconnected in WordPress admin. This ends every person’s connection to the site. - Your WordPress user is deleted. - 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 gives you three protections: - **Explicit consent** — nobody acts on a site on your behalf until you authorize it - **Real user identity** — abilities run as your WordPress user, so your role and capabilities still apply. The site’s logs name you, not 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 you can’t act on a site you haven’t authorized. ## Check your connection status When you call `list_account_sites` as a user authenticated with OAuth, it 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/#fix-needs_reconnect-on-a-stale-connection) | | `site_requires_https` | The site is not served over HTTPS, so no connection can be made | Serve the site over HTTPS first | | *(omitted)* | You never connected, or the connection was revoked | [Make the connection](https://developers.wpengine.com/docs/ai/api/site-and-account-connections/#connect-your-wordpress-account) | There is no `not_connected` value. When you have no usable connection, the field is **absent from the response entirely**. On its own, a missing field can’t distinguish “never connected” from “revoked”. The status is `needs_reconnect` when your WordPress credentials changed, the site invalidated its sessions, or the connection was flagged for reauthorization. To fix it, repeat the steps in [Connect your WordPress account](https://developers.wpengine.com/docs/ai/api/site-and-account-connections/#connect-your-wordpress-account) and open the link while you’re logged in to wp-admin. ## What each credential can reach MCP clients sign in with OAuth. Once signed in, you see every site in each WP Engine account you belong to that has AI turned on. You can act on the sites where *you* connected your WordPress account. The MCP server doesn’t accept API keys. For an API key, every tool returns `forbidden`, so the key can’t see or act on anything over MCP. See [Authentication](https://developers.wpengine.com/docs/ai/api/authentication/#authenticate-mcp-clients-with-oauth). ## Worked example In this example, a team shares one WP Engine account, and two users on that account work with the same site. 1. **The team connects `example.com`** to its account. The site is now visible to everyone on the account. The first user calls `list_account_sites`. The response lists `example.com` with no `wp_connection_status` field. 2. **The first user connects their WordPress account** for `example.com`, so that Coworker can draft posts there. They open the connect link while logged in to wp-admin and authorize the gateway to act as their WordPress user. 3. **The first user runs an ability.** `run_site_ability` creates a post. The gateway checks the user’s connection first. The ability then runs as their WordPress user, and the site’s logs show that the first user created the post. 4. **A second user on the same account tries the same thing.** The call returns `not_personally_connected`. The site connection is shared, but the WordPress account connection is not. The second user can connect their own WordPress account, or keep 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/#authenticate-mcp-clients-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"}}]} ```