SitePilot beginner guide | Safe WordPress workflows

01

If you hand this guide to an agent

Give the agent an exact client and require one installation path with visible checkpoints.

The agent must first name the environment it is running in, the exact MCP client it will configure, and the path selected in the next chapter. It must not infer the target client from the chat product or from files it happens to find.

ChatGPT web and cloud tasks do not read local Codex, Cursor, Claude, Antigravity, Windsurf, or Claude Desktop configuration. If the agent cannot access the local target client and its configuration, it must stop and hand the steps to you instead of claiming setup is complete.

One attempt uses one transport. A remote attempt never falls back to a local profile inside the same session.
Environment repair is outside SitePilot setup. If a required executable is missing, report that boundary and stop.
No custom login scripts, global npm installs, copied tokens, or hand-written duplicate server entries.
The human completes browser sign-in and authorization. The agent never asks for a WordPress password or token in chat.
Setup is not complete when a file is written. It is complete only after the target client lists the server, authentication succeeds, and one bounded inspection returns site:read.

Set up SitePilot MCP for this project.
WordPress site: https://your-site.example
Target MCP client: <exact client name>

Follow only the matching path in this guide. First report whether you are running locally or in a hosted chat, the exact client you will configure, and the selected path. Do not repair Node or npm, switch between remote and local transport, create helper scripts, or edit a second configuration location. Stop for any WordPress or OAuth approval so I can complete it in the browser. After configuration, use the client's own MCP status command or panel. Do not call a SitePilot tool until the server is listed and authenticated. Then call sitepilot-inspect-site exactly once and report the versions, authentication strategy, and granted scopes.

02

What SitePilot is

A guarded bridge between an AI coding client and one WordPress site.

Your coding client can ask SitePilot to inspect the site, prepare a typed plan, execute an approved change, check its status, or roll back supported work. WordPress remains the authority for every request.

SitePilot is not remote desktop software and it does not give the model a shell. It exposes a fixed operation catalog instead of arbitrary PHP, JavaScript, SQL, WP-CLI, secrets, wp-config.php, or filesystem access.

The WordPress plugin exposes the tools and enforces policy.
The public npm adapter connects supported coding clients without putting credentials in project configuration.
Scopes limit what a credential may request.
WordPress capabilities, risk tiers, approvals, version checks, audit events, and rollback data add separate controls.

03

What you need

Prepare the WordPress side and your computer before connecting a client.

The WordPress plugin is distributed through the private SitePilot update channel. Ask the site owner for the approved ZIP or have an administrator install it. This public guide never exposes the private update URL.

After activation, open SitePilot in WordPress and check the Status and Connections tabs. The Dashboard entry should appear directly above Playbooks in the SitePilot menu.

An HTTPS WordPress site with SitePilot MCP 0.4.16 or later installed and active.
A WordPress account allowed to authorize an Application Password, or a supported client that can complete native OAuth.
Node.js 22 or later only when you choose the local sitepilot-mcp adapter or the Antigravity config generator.
A supported client: Claude Code, Codex, Cursor, Antigravity CLI, Antigravity IDE, Windsurf, or Claude Desktop.
A new empty project folder for your first connection.

04

Choose one client path

Use the client-native remote flow where it is verified, or the local adapter path. Never combine them.

Established MCP projects publish host-specific add, authenticate, and list steps because each client owns a different configuration scope and reload behavior. SitePilot follows that pattern here. Replace the example origin with the HTTPS origin of your WordPress site.

Codex, Claude Code, and Antigravity IDE have separate remote OAuth instructions below. Codex's corrected read-only procedure completed a real-site retest on 2026-09-04. Cursor, Windsurf, Antigravity CLI, and Claude Desktop continue with the live-verified local adapter chapters below.

Codex: corrected flow, live retest recorded

Codex native remote OAuth

Stay on native remote OAuth. Do not use codex mcp add for this read-only setup: it can immediately start a broad OAuth request before a scoped login runs. Save a disabled entry first, authenticate explicitly, then enable it. No npm adapter is needed.

Step 1, configuration file, not a terminal command: ask your local agent to back up and edit the active Codex home config.toml (normally ~/.codex/config.toml; if CODEX_HOME is set, use its config.toml). Add or update only the sitepilot table below, replacing the site URL and preserving unrelated settings. Keep enabled = false. Do not create a second project entry. If a project-level sitepilot entry or old OAuth credential exists, stop and resolve it before this fresh setup. Do not paste the whole config or credentials into chat.

[mcp_servers.sitepilot]
url = "https://your-site.example/wp-json/sitepilot-mcp/v2/mcp"
enabled = false

Step 2, local terminal: confirm this lists the exact /wp-json/sitepilot-mcp/v2/mcp URL and enabled: false before continuing. A disabled row is intentional at this stage.

codex mcp get sitepilot --json

Step 3, explicit login: use this command, not the app's generic Authenticate button. Only the human approves in the browser, and only if consent shows site:read alone. For broader scopes, deny, cancel the waiting login, and leave the entry disabled. Never edit the authorization URL. Wait for the terminal to confirm successful login.

codex mcp login sitepilot --scopes site:read

Step 4, only after successful read-only login: change enabled = false to enabled = true in the same config table, then run this command. Restart or reload the target client, open a new local task, use /mcp, and require authenticated tool discovery before the single inspection in chapter 07.

codex mcp list

If --scopes is unavailable, stop; do not drop the flag or switch transport.
For later reauthentication, disable the entry and repeat login with --scopes site:read; the CLI flag applies to that login, not to every future OAuth attempt. Do not use an unscoped login or generic Authenticate action for this read-only procedure.
The previous add-then-login procedure failed a real user test by requesting nine scopes. On 2026-09-04 the corrected flow completed real-site read-only consent and inspection on plugin 0.4.10; the registered ceiling and granted scope were both site:read.

Recommended for Claude Code

Claude Code native remote OAuth

Let Claude Code own the remote server entry and its OAuth credential.

claude mcp add --transport http sitepilot https://your-site.example/wp-json/sitepilot-mcp/v2/mcp

claude mcp list

Inside Claude Code, use /mcp and start authentication for sitepilot.
The WordPress consent page must list only site:read.
Use claude mcp get sitepilot if the server is absent or the saved URL is uncertain.

Antigravity IDE remote OAuth

Antigravity IDE

Generate the documented serverUrl entry, then authenticate through the IDE settings.

npx -y sitepilot-mcp@0.1.6 init --client antigravity-ide --remote --url https://your-site.example

Refresh MCP servers, start a new Agent session, then choose Authenticate in Settings and Customizations.
The WordPress consent page must list only site:read. Do not add an oauth object by hand.
Antigravity CLI remote OAuth remains outside this beginner path until its end-to-end run is recorded. Use the local adapter path with client value agy instead.

Local adapter

Cursor, Windsurf, Antigravity CLI, or Claude Desktop

Continue with the next two chapters to create one read-only local profile and generate one exact client configuration.

npx --yes sitepilot-mcp@0.1.6 --version

The version probe must print 0.1.6. If it does not, stop and report the exact output instead of repairing the environment inside this setup.
The local path uses a WordPress Application Password flow and stores the profile outside the project configuration.
Do not also create a remote entry for the same client during this attempt.

05

Local adapter only: create a read-only profile

Skip this chapter if you completed a remote OAuth path.

Open a terminal in the empty project folder. Replace the example URL with your WordPress site and run this exact one-line command. Do not use this command after adding the same server through native remote OAuth.

The browser opens the WordPress Application Password authorization page. Sign in there if required.
Approve the Application Password request. If you instead see an OAuth consent page with a scope list, stop because you are on the remote path.
Return to the terminal and confirm that the saved profile reports site:read only.
Stop if the result shows broader scopes than you requested.

npx -y sitepilot-mcp@0.1.6 login --url https://your-site.example --scopes site:read --profile my-site --label my-site

06

Local adapter only: configure one client

Generate one client configuration from the saved profile, then pause for the required reload.

Cursor is the first local example. Run the command below in the same project folder, then use Developer: Reload Window from the Command Palette. If you use another local client, replace cursor with exactly one value from the list.

Claude Code: replace cursor with claude-code.
Codex: replace cursor with codex, then trust the project so Codex can load project-scoped configuration.
Antigravity CLI: use agy. Antigravity IDE: use antigravity-ide.
Windsurf: use windsurf. Claude Desktop: use claude-desktop.
Do not use major or all during a first setup. Writing several client configurations makes failures ambiguous.

npx -y sitepilot-mcp@0.1.6 init --client cursor --profile my-site

07

Run one bounded inspection

Prove the connection before asking the agent to do anything else.

First use the target client's MCP list, status command, or settings panel. Continue only when sitepilot is present, enabled, and authenticated. Then open a new agent chat and use this exact prompt.

The tool call completes successfully.
The client listed sitepilot before the tool call. A generated file alone is not evidence of a working setup.
The SitePilot plugin version is 0.4.16 or later.
The authentication strategy is app_password or oauth, depending on the connection path.
Granted scopes contain only site:read.

Use the SitePilot MCP tool sitepilot-inspect-site exactly once. Do not call any other tool. Report the WordPress version, SitePilot plugin version, authentication strategy, and granted scopes from that single result.

08

Understand scopes and risk tiers

A scope grants a category of authority. A risk tier decides whether a human approval is required.

Tier 0 is read-only. Tier 1 stages safe work such as a draft. Tier 2 changes sensitive site state and requires approval. Tier 3 is high risk and requires a fresh administrator approval.

A broad scope does not bypass WordPress capabilities or approvals. It only makes that operation category eligible for further checks.

site:read: inspection and capability discovery only.
content:write: drafts, content updates, publishing, trash, and deletion, each still governed by its risk tier.
media:write: staged Media Library uploads and bounded imports.
design:write: supported builder, menu, template, and site-design operations.
commerce:write: supported WooCommerce price, stock, order, and refund operations.
extensions:manage, core:update, users:write, and security:manage: high-risk administrative operations.

09

Local adapter only: Prepare your first safe draft

Widen authority deliberately, inspect again, and stop after planning before execution.

The Codex, Claude Code, and Antigravity IDE remote paths end at read-only inspection in this guide. Skip this chapter if you followed any remote path, and do not mix these local-adapter commands into that setup.

When you are ready to test a write workflow, create a separate profile with only site:read and content:write. Do this on a disposable or staging site first.

Confirm the plan creates a draft, not a published page.
Confirm the target, title, content, scope, and risk tier.
Do not execute if the plan contains an unexpected second action.
Ask the agent to execute only after the dry-run diff matches your intent.

npx -y sitepilot-mcp@0.1.6 login --url https://your-site.example --scopes site:read,content:write --profile my-site-drafts --label my-site-drafts

npx -y sitepilot-mcp@0.1.6 init --client cursor --profile my-site-drafts

Inspect the site once. Then describe the content.create_draft operation and prepare a plan for a draft page titled SitePilot Test Draft. Do not execute the plan. Show me the risk tier, required scope, target, expected version, and complete diff.

10

Approve sensitive work and understand rollback

Tier 2 and Tier 3 plans pause until a WordPress user approves the exact change hash.

When a plan reports awaiting approval, open WordPress, choose SitePilot, then Approvals. Review the target, actions, diff, risk tier, and expiry before approving.

The approval is bound to the exact planned actions. If the plan changes, the approval no longer matches. Execution also fails if the site version changed after planning.

Never approve a change you cannot explain.
Reject plans with unexpected operations, targets, or scopes.
After execution, ask for sitepilot-get-change-status and inspect the result in WordPress Change History.
Rollback is available only where SitePilot retained the required snapshot and compensation data.
A partial rollback is reported as failed, never as success.

11

Know the supported surfaces

Inspectable does not always mean constructible or writable.

Use sitepilot-search-capabilities and sitepilot-describe-operations before planning unfamiliar work. For builder changes, inspect the target structure first and review the staged preview before approval.

Gutenberg: inspection, staged changes, publishing approval, and supported rollback.
Elementor 3: classic document inspection, construction, bounded edits, approval, and rollback.
Elementor 4 mixed documents: per-region inspection and known typed-setting updates on existing atomic elements only. Atomic construction and structural edits remain unsupported.
Enfold ALB: bounded work on calibrated documents and inspected scalar colour or typography settings. Uncalibrated nested Enfold 7.x structures remain administrator work.
WooCommerce: guarded product, stock, price, order, and refund operations under the appropriate scope and approval tier.
Media: bounded JPEG, PNG, WebP, and PDF staging. SitePilot does not currently provide an image-optimization pipeline.

12

Troubleshoot without weakening security

Most failures identify the missing precondition. Fix that condition instead of widening access blindly.

Server not listed: stop before authentication. Use codex mcp list, claude mcp list, /mcp, or the target client's MCP settings to confirm the entry exists in that exact client.
Local server missing after init: confirm you ran init in the project folder, reload the client, and check project trust where required.
Unauthorized or Auth Needed: Codex remote users disable the entry and repeat the scoped login procedure in chapter 04, not the generic Authenticate action. Other remote clients follow their own chapter 04 steps. Local-adapter users repeat login for the intended profile. Do not change transport as a repair.
Wrong authorization page or duplicate sitepilot entries: deny or cancel, remove the stale entry in the target client, revoke the stale WordPress connection, and restart one documented path from the beginning.
Browser did not open: keep the exact command and terminal output and stop. Do not create a custom login script or copy a credential into configuration.
Insufficient scope: check the operation's required scope. Create a purpose-specific profile instead of granting every scope.
Approval required: review the pending item in SitePilot → Approvals. Do not ask the agent to bypass it.
Version mismatch: inspect the site again and create a new plan against the current site version.
Operation blocked or unsupported: ask sitepilot-describe-operations for the current contract and choose a supported workflow.
Provider or hosting outage: verify the WordPress URL in a browser and wait for the provider to recover. Do not rewrite the MCP configuration around a temporary outage.

13

Disconnect and clean up

Remove local profiles and revoke server-side credentials when a test or project ends.

In WordPress, open the relevant user profile and revoke the matching SitePilot MCP Application Password.
For OAuth, open SitePilot → Connections and revoke the client connection.
Delete disposable project folders only after saving non-secret evidence you still need.
Confirm the client no longer lists the removed SitePilot server after reloading.

npx -y sitepilot-mcp@0.1.6 logout --profile my-site

npx -y sitepilot-mcp@0.1.6 logout --profile my-site-drafts

14

Plain-language glossary

The few terms you will see throughout SitePilot.

MCP: the protocol a coding client uses to discover and call SitePilot tools.
Profile: a local named SitePilot connection whose credential stays outside project configuration.
Scope: a category of authority granted to one credential.
Operation: one typed WordPress action with a fixed input contract.
Plan or change set: an immutable dry run describing intended actions and their diff.
Risk tier: the policy level that determines how much review and approval an action needs.
Expected version: the site-state digest used to stop stale plans from executing.
Approval: an expiring WordPress-side decision bound to the exact change hash.
Rollback: a supported reverse operation based on retained snapshot and compensation data.

Go from a first connection to a controlled WordPress workflow