Managing a WordPress fleet

EMCP Cloud gives your AI client one Gateway connection to sites that have already connected to your workspace. Initial enrolment and Pro licence activation still happen separately on each independent WordPress installation.

Four separate setup steps

Step	Where it happens	What it enables
Install and activate EMCP Tools	Each WordPress installation	The site’s MCP tools
Activate a Pro licence, when needed	Each installation, through Freemius	Pro features on that installation
Connect to EMCP Cloud	Each site authorizes the Cloud connection	Cloud features within the workspace’s entitlement
Enable Gateway access	Each site issues a user-bound credential	Gateway calls to that site

A Cloud subscription does not activate the Pro plugin. The free plugin can connect to Gateway when the Cloud account is entitled; available tools still depend on each site’s licence, modules, integrations, and tool settings. Uploading a licence key or syncing settings does not complete activation or enrolment.

The operator-run onboarding command below is prepared for EMCP Tools 3.19.0 and requires the matching Cloud update. It is not available in older plugin releases. It handles Cloud connection and Gateway verification on independently installed sites; installation and licence activation remain separate. WordPress Multisite is not supported by this command.

Operator-run onboarding

Run WP-CLI with an existing WordPress administrator using --user. Keep the Cloud module enabled. Both the WordPress site and Cloud service must use HTTPS. Find your workspace ID under Account → Connected Sites → Onboard sites with WP-CLI.

# Local checks only, without HTTP requests or onboarding writes.
wp emcp cloud onboard --user=admin --dry-run

# Prepare a ten-minute, site-specific Cloud approval.
wp emcp cloud onboard --user=admin --phase=prepare --workspace=WORKSPACE_ID

# After approval, explicitly enable Gateway as this administrator and verify health.
wp emcp cloud onboard --user=admin --phase=resume --workspace=WORKSPACE_ID --gateway

Preparation prints JSON with an authorization_url. Open it, sign in to the requested Cloud workspace, and approve the site. The callback requires you to be signed in to WordPress as the same administrator passed to WP-CLI. The site keeps the PKCE verifier locally; authorization codes are single-use. Approval alone does not enable Gateway for this workflow: the resume command’s --gateway flag supplies that consent.

Repeating preparation before expiry returns the same pending approval. Another administrator’s pending approval is preserved. After expiry, prepare again. Connected sites are checked rather than reconnected automatically. A different workspace, copied identity, or mismatched registered site URL blocks onboarding before credential upload.

Running a batch

The plugin includes bin/cloud-onboard.mjs, an operator-side runner for Node.js 20 or newer and WP-CLI. It runs one site at a time, continues after individual failures, and emits one JSON result per site. Remote targets use your existing WP-CLI SSH access; no site passwords, licence keys, Cloud tokens or shell commands belong in the manifest.

{
  "version": 1,
  "workspace": "WORKSPACE_ID",
  "sites": [
    { "id": "client-one", "path": "/srv/www/client-one", "user": "admin", "ssh": "[email protected]" },
    { "id": "client-two", "path": "/srv/www/client-two", "user": "admin", "ssh": "[email protected]" }
  ]
}

node bin/cloud-onboard.mjs fleet.json preflight
node bin/cloud-onboard.mjs fleet.json prepare
node bin/cloud-onboard.mjs fleet.json resume --gateway

On Windows, set EMCP_PHP to the PHP executable and EMCP_WP_CLI_PHAR to wp-cli.phar; the runner starts them directly without a shell. A manifest accepts at most 1,000 distinct targets, but prepare small batches you can approve within ten minutes. This is not unattended bulk consent. Treat approval URLs as private and short-lived; do not paste preparation output into shared logs.

Results and recovery

Result	Meaning and next step
ready	Local preflight passed. No network health check has run.
awaiting_approval	Open the approval URL, or prepare again if it expired.
connected	Preparation found an existing Cloud binding. Run resume for Gateway verification.
complete	Cloud binding, uploaded Gateway credential and Gateway health were verified.
retry	A step could not be verified. Inspect the reason, wait before retrying, and rerun resume.
blocked	Resolve the reported permission, identity, workspace, plan or compatibility issue first.

The license field reports the installed Freemius SDK’s premium-access result independently of Cloud completion. It does not activate a licence or prove a particular licence purchase. A Free plugin can complete Cloud onboarding on a paid Cloud plan.

Resume reads current server state rather than replaying completed writes. It does not replace an already uploaded credential. If a restored site has a dead credential, use Re-issue gateway credential in WordPress, then resume verification. A timeout has an uncertain outcome: inspect or resume before preparing another connection. The runner does not automatically retry writes or bypass rate limits; wait for throttling to clear before retrying an affected batch.

Rollout checklist

1. Confirm the workspace’s effective connected-site limit using cloud-status or support. Enterprise includes 1,000 sites. If the reported allowance differs from your purchased plan, contact support to correct it before expanding the rollout.
2. Start with one representative site. Install EMCP, complete Pro activation if required, and configure the intended modules and tools.
3. Sign in as the intended WordPress administrator and connect the site with Gateway access.
4. Check emcp_list_sites, then use describe-site for the target’s available tools. Make a read-only call and verify its Gateway target.
5. Copy supported settings using the admin Settings Sync buttons if needed. Review the destination and test again before extending the rollout.
6. Repeat in paced batches. Record site identity, activation status, Cloud connection, Gateway health, and any failed step so you can resume deliberately.

Keep credentials out of inventories and support logs. Record status and identifiers, not tokens or licence secrets.

Background health checks

On deployments with Fleet health jobs enabled, open Account → Connected Sites → Fleet health jobs. Select the sites to check and review the selected count before starting. The job keeps that exact target list and continues if you close the page.

These checks inspect the Gateway connection and tool list without changing WordPress content or settings. Each site has its own result and attempt count. Temporary availability failures retry up to three total attempts; disconnected sites and rejected credentials require your attention. A completed job can contain failed sites.

Cancel stops pending checks. Checks already in progress can finish, and completed results remain visible. Work interrupted by a worker restart resumes automatically after its lease expires. Jobs have a 24-hour deadline; each workspace can have one active job and submit up to six new jobs per hour. This health-check workflow does not add bulk enrolment, arbitrary tool jobs, or configuration deployment.

Saved site groups

Use the Fleet health search to find sites by name or URL. Select visible adds the matching sites; selected sites hidden by the search remain selected and are included in the displayed total. Clear selection removes all selections.

Select sites, choose New group, name it, and choose Save selected sites. A workspace can save up to 50 groups, each containing up to 1,000 currently connected sites with active Gateway credentials. Choose a saved group to load its selection, then review the count before starting a check. Sites that are no longer available are skipped with a notice.

Edit group saves the current selection. Concurrent edits are rejected so an older tab cannot overwrite a newer version. Editing or deleting a group does not alter sites or previously submitted jobs. Groups are shortcuts for Fleet health checks; Gateway tool calls still use individual site targets or the existing all broadcast.

Scheduled checks and dashboard alerts

In deployments with scheduled Fleet checks enabled, open Account → Connected Sites → Fleet health and use Scheduled checks. Choose a saved group, select hourly, six-hourly or daily checks, and add the schedule. Up to five schedules are supported per workspace. Use Edit to change the interval or pause a schedule.

The first job starts within five minutes when capacity permits. Scheduled and manual jobs share the limit of one active job and six new jobs per hour per workspace. Busy schedules wait and retry later. Sites become eligible for checking two seconds apart within a scheduled job and remain subject to the worker’s concurrency limits. These intervals are a target cadence, not an exact-time guarantee. After a worker outage, each overdue schedule starts at most one new job; missed intervals are not replayed.

Fleet workers allow at most two active probes per workspace and ten across the service. Each worker process runs four probe loops, so actual concurrency can be lower. Eligible workspaces take turns when claiming checks; a large fleet does not receive priority solely because its job was submitted first. These limits are separate from your plan’s Cloud API request allowance.

For a 1,000-site scheduled group, the last site becomes eligible about 33 minutes and 18 seconds after the first. Queue contention, slow sites and retries can extend completion beyond that. This is scheduling behavior, not a promised completion time or a production capacity guarantee.

Each job snapshots the group’s current sites. Later group edits affect future jobs only. Removing a group pauses its schedule. Revoked membership, a banned owner, a plan without Gateway access, or invalid targets pause new submissions. Existing jobs continue to enforce live access before each probe. Pausing or deleting a schedule does not cancel a job already submitted; use that job’s Cancel pending checks control if needed.

A site that fails two consecutive completed scheduled checks produces one failure alert. Each check first uses the normal bounded retry policy. Further failures do not repeat that alert; the next successful check produces a recovery alert. Cancelled jobs reset the consecutive-check history and do not imply recovery. Manual jobs do not contribute to scheduled alert history.

Alerts appear in the Fleet dashboard only; this version does not send email, webhooks or browser notifications. Use Refresh schedules and alerts to retrieve current results. The dashboard retains the latest 100 alerts from the past 30 days. Recent reliability shows the percentage of successful observations across each site’s last 30 completed scheduled checks, not continuous uptime or an SLA.

Cloned and restored sites

A cloned WordPress database can include the original site’s Cloud UUID and credentials. Connecting that copy must not replace the original installation’s connection. Cloud rejects an existing UUID when it is presented from a different site URL, including a different subdirectory.

In plugin builds with clone protection, credentials are bound to the WordPress home URL when the Cloud connection is saved. A changed home URL blocks use of those copied credentials. On the clone, open EMCP Tools → Connection → Cloud → Connect as a separate site, confirm, then connect normally. This gives the clone a new UUID and clears its local Cloud and Gateway credentials without revoking the source site’s connection. The new site uses a separate slot in the workspace allowance.

Older saved connections may lack the local URL marker, and a clone retaining exactly the same URL cannot be distinguished by this check. Use Connect as a separate site explicitly before connecting such a copy. For a restore at the same URL, retain the original identity and repair credentials as needed. A deliberate move to a different URL also triggers the identity guard; contact support before moving if you need to preserve that site’s identity or history.

Copying settings

On the source site, choose EMCP Tools → Connection → Cloud → Push settings to cloud. On each destination, choose Pull settings from cloud. These actions collect and apply a curated set of preferences.

The workspace holds one shared settings blob, so designate a source rather than pushing competing configurations from every site. Applying it updates included allowlisted options, leaving absent options unchanged. There is no built-in configuration history or fleet rollback for this flow; retain the previous intended configuration before a rollout.

The MCP cloud-config-sync tool only stores or retrieves a supplied blob. Its pull does not apply options, even with site: "all". Brand-kit and lower-level tool-toggle blobs remain site-specific. See the schema, examples, and settings allowlist.

Choosing target sites

Use the exact site UUID or URL returned by emcp_list_sites on each Gateway call when several sites are connected. A site array or named group is not currently supported. For a pilot group, make individual calls with explicit targets.

site: "all" targets every Gateway-connected site in the workspace. Write broadcasts require the workspace opt-in and confirm: true. cloud-config-sync is classified as a write even for direction: "pull".

Broadcast results are per site. A partial failure does not undo successful changes on other sites. Check both transport errors and tool-level errors. Before retrying a write with an uncertain outcome, inspect the destination to avoid creating duplicate changes. Current broadcasts are not durable background jobs with a resume token.

Rate limits and recovery

The connected-site allowance controls capacity, not request throughput. Cloud config and credential operations also depend on OAuth authentication endpoints. Limits may be shared by requests from the same IP, including sites behind shared hosting or server-side validation requests.

There is currently no published, verified production throughput guarantee for a fleet rollout. Deployment settings, authentication limits, WordPress hosts, and edge protections can all affect the effective rate. Confirm pacing with support before automating a large initial enrolment.

• Use a queue with bounded concurrency. Gateway broadcasts default to five concurrent site calls, but this is deployment-configurable and does not guarantee a per-minute throughput.
• On 429 responses, honor Retry-After when available. Otherwise use bounded exponential backoff with jitter instead of immediate repeated requests.
• Do not retry every site when only a subset failed. Inspect unknown write outcomes before resubmitting.
• Cloud API request budgets are shared by all clients and sites in a workspace. Freelancer includes 180 requests/minute, Agency 360, and Enterprise 1,200 by default. See Cloud API request limits for burst allowances and examples. Workspace burst limits and a shared service ceiling still apply; the site allowance is not a concurrent-request allowance. A budget rejection returns 429 cloud_rate_limited with Retry-After.
• The Cloud API reports authentication throttling as 429 auth_rate_limited and temporary validation-service failures as 503 auth_service_unavailable, with Retry-After. Older deployments may surface these as 401s. Pause a burst and diagnose a low-volume request before replacing credentials.
• If failures persist, provide support with the operation, time, affected site identifiers, response status, and redacted error details.

Refresh recovery in plugin 3.19.0

Plugin 3.19.0 preserves the Cloud connection when refresh receives a network error, HTTP 408/429, or a server error. It waits until the next eligible request to retry, using Retry-After when supplied, bounded to one second through one hour, or 30 seconds when missing or invalid. It does not run a background retry loop. A successful refresh clears the cooldown; an actual credential rejection still requires reconnection.

The matching Cloud update serializes refresh rotation across website instances. A concurrent or overloaded refresh returns 503 temporarily_unavailable with Retry-After: 5; keep the saved credential and retry later. Gateway also treats HTTP 408/429/5xx from a site’s token endpoint as temporary unavailability. These controls protect refresh attempts; they do not increase plan request allowances or qualify 1,000 simultaneous site operations.

Administrator access and credentials

The EMCP menu and settings require WordPress’s manage_options capability. Other administrators normally have that capability. There is currently no built-in EMCP user-ID allowlist, dedicated management capability, or constant that limits all settings access to one administrator. Menu hiding alone does not enforce access control.

A dedicated administrator is supported as an execution identity. Gateway uses the user who connects or reissues its credential; direct OAuth uses the approving user; Application Passwords use their owner. Tool-level capability checks still apply. This does not bind ownership of the entire plugin to that account.

Change	Required action
Normal OAuth refresh	The client must save replacement refresh tokens; Gateway handles this automatically.
Replace an Application Password	Update consuming clients, verify access, then revoke the old password.
Revoke Gateway access	Use the site’s Gateway-off/connected-app controls or disconnect in Cloud. Reauthorize to restore access.
Change the Gateway user	Reissue/connect while signed in as the intended administrator. For a deliberate access handover, revoke the previous Gateway authorization first.
Delete the acting user or remove capabilities	Expect affected operations to fail; establish and verify the intended replacement identity.
Restore or migrate a site	Verify its URL, Cloud connection, and Gateway access; use Re-issue credential when Cloud holds a credential the restored site no longer accepts.

For revocation details and offline recovery, see Gateway security and revocation. See also OAuth sign-in and WordPress MCP permissions.