Skip to content
WP EngineDocumentation

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

Section titled “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

Section titled “Site connection”

What it is

Section titled “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

Section titled “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

Section titled “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

Section titled “WordPress account connection”

What it is

Section titled “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

Section titled “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

Section titled “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

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

Section titled “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

Section titled “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
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

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 and open the link while you’re logged in to wp-admin.

What each credential can reach

Section titled “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.

Worked example

Section titled “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.

Last updated: