Site and WordPress account connections

A WordPress site reaches Power 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 the Power console, 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, search_kb
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 Power plugin and completes the registration flow
• A user registers the site from the Power console (future)

What it gives you

• The site appears in list_account_sites
• Site metadata: URL, display name, status
• Knowledge base search with search_kb, 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

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 in that site’s WordPress admin. That links three things:

• Your identity, from your personal API key or OAuth session
• 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 the Power console
• 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

1. Ask for your sites’ connection status, or call list_account_sites

2. For any site reporting wp_connection_status: "not_connected", open this URL while logged in to that site’s WordPress admin:

   {site_url}/wp-admin/admin.php?page=power-overview&action=trigger_wp_connection

   Opening this link is the only way to start the flow — there is no button for it anywhere in WordPress.

3. Review the permissions on the consent screen

4. Confirm with Connect WordPress User

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 key — a key shared across a team cannot silently act on every site in the account

The gateway checks the connection on every ability call, so a site you have not authorized stays untouchable even with a valid key.

Connection states

list_account_sites, called with a personal API key, reports wp_connection_status for each site:

Status	Meaning	What to do
connected	Both connections are in place	Nothing — you can run abilities
not_connected	Site is connected; your WordPress account is not	Complete the flow above, if you want to act on this site
needs_reconnect	Your connection went stale	Re-authorize in WordPress admin
(omitted)	You are using a project API key	Switch to a personal API key

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: open the link above while logged in to wp-admin.

What each credential can reach

Credential	Sees	Can act on
Personal API key	Every site in the key’s project	Sites where you connected your WordPress account
Project API key	Every site in the key’s project	Nothing — a project key has no acting user
OAuth token (future)	Every site in the selected account	Sites where you connected your WordPress account

A project API key can list sites and search knowledge bases, but it resolves no WordPress user, so it can never run an ability.

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 with wp_connection_status: "not_connected".

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.

Next steps

• Getting started tutorial — includes connecting your WordPress account
• API keys reference — personal vs project keys
• MCP server design — architecture and design decisions