Agent Bridge — WordPress MCP for Claude Code and any MCP agent

Agent Bridge is the safety and SEO layer for AI-edited WordPress: it proves every write, snapshots everything it touches, and refuses the writes you didn't authorize. It pairs with EMCP, which does the Elementor editing.

What it is

Agent Bridge is a WordPress MCP for Claude Code and every other MCP client, built for self-hosted WordPress (WordPress.org installs, not WordPress.com) where an AI agent manages a site's SEO, schema, and safety net alongside, or instead of, a human editor in wp-admin. Claude Code is the primary documented client, but nothing here is Claude-specific: Cursor, Windsurf, Codex CLI, Gemini CLI, or any MCP client connects through the same official WordPress MCP Adapter endpoint, and the REST surface needs nothing beyond an Application Password. It's designed to pair with EMCP, the Elementor MCP for Claude Code most agents already reach for on layout work. EMCP edits the page. Agent Bridge never writes _elementor_data at all; what it covers is the layer builder tools consistently skip: Rank Math SEO fields, JSON-LD schema, content snapshots, and a restore that proves it converged.

Every write Agent Bridge makes is read back from the database before it's reported saved. Every page and post gets a stable content hash, so an agent can tell in one request whether anything has changed since it last looked, and a write aimed at content that predates the plugin's own activation is refused unless the caller proves it just captured a fresh snapshot of that exact post. Two kill switches, set in wp-config.php, let an operator take the whole thing offline or lock it to read-only without touching the plugin itself.

Related MCP server: Respira for WordPress

Why this exists

Most WordPress MCP servers report a write successful the moment their API returns HTTP 200. Of the safety-focused ones surveyed for this project's own competitive research, none publish a write that reads its own result back from the database before saying so, and none document a hash-verified restore, a proof that a rollback actually converged to what it claims, rather than just a note that a snapshot exists somewhere. See How Agent Bridge compares below for the specific tools, what each documents, and the sources.

A live example of what a capability gap actually costs: in 2026, the AI Engine plugin's MCP module shipped a privilege-escalation flaw that let subscriber-level WordPress accounts hijack MCP-authenticated actions, on more than 100,000 sites (gbhackers.com/over-100000-wordpress-sites-exposed). The root cause was a capability check gap on MCP-authenticated calls: a request carrying a valid credential wasn't also checked against the specific WordPress capability the action required.

Agent Bridge closes that exact class of bug in its route design, not in a promise. Every route scoped to one post checks edit_post for that exact post ID (Agent_Bridge_Auth::can_edit_post()), never the blanket edit_posts grant a lower-privilege account might also hold. Routes that affect the whole site (restore, cache purge, health, the snapshot hash backfill) require manage_options. The Abilities API layer runs the identical checks per ability, not a looser mirror of them (Agent_Bridge_Abilities::permission_*).

Verified Writes

Every SEO field write and every schema write is followed immediately by a fresh get_post_meta() read from the database. A value is only reported saved once that read-back matches what was written, accounting for WordPress's own type coercion (array order, numeric-string image IDs). A caller never has to trust an HTTP 200: if the write-back doesn't match, the route returns a 500 with the field name, the value it tried to write, and what the database actually holds (Agent_Bridge_Seo::write(), Agent_Bridge_Schema::write()).

Stable Content Hash

Every page and post gets one SHA-256 hash, recomputed automatically whenever the post itself, its Elementor data, its bridge-scope SEO fields, or its Rank Math schema meta changes (hooked on save_post and the added_post_meta / updated_post_meta / deleted_post_meta actions in Agent_Bridge_Snapshot::init_hooks()). The hash covers post_content, the verbatim Elementor blob, and the sorted SEO plus schema meta, so one call to /snapshot/manifest tells a caller, for every page and post on the site, whether anything has touched it since the last time the caller looked.

Verified Restore

Restoring a snapshot doc is not "trust this backup." The request has to clear two separate proofs before anything is written. First, the document itself has to be self-consistent: the confirm token sent with the request has to equal the doc's own stated hash, and recomputing that hash from the doc's own content, Elementor data, SEO, and schema fields has to produce the same value (proof the doc is untampered, not just plausible-looking). Second, the caller has to prove it just read the post's real live state, via the same additive-only header the Additive-Only Gate below requires. Only once both gates pass does restore converge the post (content, Elementor data, SEO, and schema) to exactly what the doc says, deleting fields the doc doesn't mention rather than merely patching over them, and it hands back the resulting document so the convergence can be checked directly instead of assumed.

Additive-Only Gate

A write aimed at a post that already existed before Agent Bridge was activated is refused by default, unless the request proves it just captured a fresh snapshot of that exact post by sending the post's current content hash back in an X-Agent-Bridge-Confirm header. Content created after activation is exempt, since there is nothing pre-existing to protect. In practice this means an agent cannot silently overwrite content it never looked at: it has to read a post's real current state first, on every post that predates the plugin. A site can turn this off with the agent_bridge_additive_only filter.

Kill Switches

Two PHP constants, set in wp-config.php and checked before anything else runs. AGENT_BRIDGE_DISABLED makes every route return 503, reads included. AGENT_BRIDGE_READ_ONLY refuses every write, including the snapshot manifest's ?rebuild=1 hash backfill (a write issued over GET, which a naive HTTP-method check would miss), while every read keeps working. Both are config-time switches an operator with server access controls directly; neither is exposed over the API itself.

Write, Purge, Verify

Cache purge is its own route, POST /cache/purge, deliberately not folded into the write routes, because the sequence that matters is write, then purge LiteSpeed's cache, then read back to verify, in that order. Keeping the purge as an explicit step means a verification read right after a write is never served the stale page a cache is still holding.

Abilities API and MCP

When the WordPress Abilities API is present (built into WordPress 6.9+, or added by the standalone mcp-adapter plugin on an older core), Agent Bridge registers eight abilities under an agent-bridge category. WordPress abilities are private by default; every one of these sets meta.public = true, which is what lets the official mcp-adapter surface it as an MCP tool with no separate integration on Agent Bridge's part. Each ability's permission_callback runs the same capability, read-only, and additive-only checks its REST counterpart does, never a looser copy.

Restore is deliberately not registered as an ability. It stays REST-only, behind its own double confirm-token gate, because its request body (a full snapshot document) doesn't fit the Abilities API's typed input-schema model the way the other seven do.

Agent Bridge composes with Rank Math's own first-party MCP tools (rank-math/get-post-schema and its meta read/write tools, documented at rankmath.com/kb/mcp-tools) rather than replacing them: both surfaces read and write the same stored Rank Math postmeta, so an agent can use whichever one it already has connected. Disable the whole ability surface independently of the REST API with define( 'AGENT_BRIDGE_ABILITIES', false ) in wp-config.php.

Supported SEO fields

GET/POST /posts/{id}/seo cover 15 Rank Math fields. Sending an empty string, empty array, or null for any of them clears that field back to its default, mirroring how Rank Math's own update_metadata() treats an empty value as a delete.

The *_image_id fields exist alongside the plain *_image URL fields on purpose: Rank Math's front end resolves a custom Open Graph or Twitter image exclusively through the _id field, so writing only the URL is silently ignored by the renderer even though the write itself succeeds and reads back cleanly. Both fields have to be set together for the image to actually show up.

Requirements

• WordPress 6.9 or later.

• PHP 8.1 or later.

• HTTPS. Enforced on every route, proxy-aware (a trusted reverse proxy's X-Forwarded-Proto header counts), refusable only via the agent_bridge_allow_http filter for local development.

• Rank Math, for the SEO and schema routes specifically. The plugin activates fine without it; those two routes simply have nothing to read or write until it's installed.

• LiteSpeed Cache, for the /cache/purge route specifically. Every other route works regardless of which cache layer, if any, sits in front of the site.

• The WordPress Abilities API and the official mcp-adapter plugin, only if you want the eight abilities exposed as MCP tools rather than calling the REST API directly. Neither is required for the REST API itself.

Quickstart

Install

1. Download the plugin zip and upload it via Plugins → Add New → Upload Plugin, or extract it into wp-content/plugins/agent-bridge/.

2. Activate Agent Bridge for WordPress from the Plugins screen.

3. Create a WordPress Application Password for the account your agent will use: Users → Profile → Application Passwords. Give it a role no wider than the job needs: the SEO and schema routes only need edit_post on the posts the agent touches, so an Editor account is enough for routine content work. The site-wide routes (/health, /restore/{id}, /cache/purge, and the snapshot manifest's ?rebuild=1 backfill) need manage_options, so they only work with an Administrator-capable account.

4. Confirm the plugin is reachable (this call needs the Administrator-capable credential from the previous step, since /health requires manage_options):

curl -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx" \
  https://example.com/wp-json/agent-bridge/v1/health

{
  "bridge_version": "0.11.0",
  "wp": "6.9",
  "php": "8.2.10",
  "elementor": "3.28.0",
  "rank_math": "1.0.277",
  "emcp": "1.4.0",
  "litespeed": true,
  "active_plugins": ["agent-bridge/agent-bridge.php", "elementor-mcp/elementor-mcp.php"],
  "is_ssl": true,
  "forwarded_proto": "",
  "forwarded_ssl": "",
  "https_effective": true
}

elementor, rank_math, and emcp come back null instead of a version string whenever that plugin isn't installed; nothing else in /health depends on any of the three being present.

Read and write SEO fields

# Read every Rank Math SEO field set on post 42
curl -u "agent:xxxx xxxx xxxx xxxx xxxx xxxx" \
  https://example.com/wp-json/agent-bridge/v1/posts/42/seo

# Write a title and description on a post created after Agent Bridge was activated
curl -u "agent:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -X POST https://example.com/wp-json/agent-bridge/v1/posts/42/seo \
  -H "Content-Type: application/json" \
  -d '{"rank_math_title": "New title", "rank_math_description": "New description."}'

A successful write reports the read-back value for every field, not just an acknowledgement:

{"saved": {"rank_math_title": "New title", "rank_math_description": "New description."}}

If the database doesn't hold what was just written, the route fails loudly instead of reporting success:

{
  "code": "agent_bridge_writeback_mismatch",
  "message": "Write-back verification failed for rank_math_title.",
  "data": {
    "field": "rank_math_title",
    "expected": "New title",
    "actual": "Old title",
    "status": 500
  }
}

Writing to a post that predates Agent Bridge's activation needs one extra step, since the additive-only gate refuses it otherwise:

# 1. Read the post's current content hash
curl -u "agent:xxxx xxxx xxxx xxxx xxxx xxxx" \
  "https://example.com/wp-json/agent-bridge/v1/snapshot/items?ids=42"
# -> {"items":[{ ... "hash":"a1b2c3..." }], "missing":[]}

# 2. Write, proving you just read the real current state
curl -u "agent:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -X POST https://example.com/wp-json/agent-bridge/v1/posts/42/seo \
  -H "Content-Type: application/json" \
  -H "X-Agent-Bridge-Confirm: a1b2c3..." \
  -d '{"rank_math_title": "New title"}'

Skip the header, or send the wrong hash, and the gate refuses the write before anything is touched:

{
  "code": "agent_bridge_existing_content",
  "message": "This content existed before Agent Bridge was activated. Snapshot it first, then send its current hash in the X-Agent-Bridge-Confirm header to confirm the write.",
  "data": {"status": 403}
}

Write JSON-LD schema

curl -u "agent:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -X POST https://example.com/wp-json/agent-bridge/v1/posts/42/schema \
  -H "Content-Type: application/json" \
  -d '{"type": "Article", "schema": {"@type": "Article", "headline": "How Agent Bridge Works"}}'

# Delete a schema entry by sending schema: null
curl -u "agent:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -X POST https://example.com/wp-json/agent-bridge/v1/posts/42/schema \
  -H "Content-Type: application/json" \
  -d '{"type": "Article", "schema": null}'

The stored value is an envelope, not a bare JSON-LD object: Rank Math attaches its own metadata block (display name, template or custom, and whether the schema is primary for the page) alongside the JSON-LD properties, and reads @type back out unconditionally at render time with no fallback for a missing one. Agent Bridge fills @type in from the route's own type param when a submitted schema omits it, rather than accepting the gap, and rejects a schema whose own @type disagrees with the route's type, since that would store correctly but render under the wrong key:

{
  "type": "Article",
  "schema": {
    "@type": "Article",
    "headline": "How Agent Bridge Works",
    "metadata": {"title": "Article", "type": "custom", "isPrimary": true}
  }
}

Snapshot and purge

# Paginated manifest of every page/post id and its content hash
curl -u "agent:xxxx xxxx xxxx xxxx xxxx xxxx" \
  "https://example.com/wp-json/agent-bridge/v1/snapshot/manifest?per_page=50"

# Flush the whole LiteSpeed cache after a batch of writes (needs manage_options)
curl -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -X POST https://example.com/wp-json/agent-bridge/v1/cache/purge

Restore takes a full snapshot document (everything /snapshot/items returned for that post, including its hash) plus a confirm field equal to that hash, and the same X-Agent-Bridge-Confirm header proving you just read the post's current live state. See the route reference below for the full shape: it's deliberately not a small enough payload to demo in one line.

Claude Code, plus EMCP, plus Agent Bridge

The canonical setup for agent-managed Elementor sites runs both plugins on the same install:

1. Install and activate Agent Bridge and EMCP (Elementor MCP for Claude Code) on the same self-hosted WordPress site.

2. Create one Application Password for the account both tools will authenticate as.

3. Connect Claude Code to each tool per its own docs: EMCP as an MCP server for layout, and Agent Bridge's REST API (or, once the Abilities API and the official mcp-adapter are installed, its eight abilities as MCP tools alongside EMCP's) for SEO, schema, snapshots, and restore.

4. Tell the agent the division of labor in one line of project instructions: EMCP edits layout; Agent Bridge is the source of truth for SEO, schema, and safety, and is the tool to call before and after any layout edit.

A worked example: "update the hero section, then fix the page title and meta description." Claude drives EMCP for the hero edit, then calls POST /posts/{id}/seo on Agent Bridge to update rank_math_title and rank_math_description, reading back the confirmed values before it reports the task done.

The full walkthrough, with prerequisites spelled out and the two-plugin architecture in more depth, lives in docs/CLAUDE-CODE-SETUP.md.

Route reference

All routes are under the agent-bridge/v1 namespace: https://example.com/wp-json/agent-bridge/v1/....

Every route requires HTTPS and an authenticated WordPress user (Application Passwords are the intended credential). Every write is appended to a rolling 50-entry audit log (timestamp, user, route, post id only, readable as the agent_bridge_audit option); no route ever runs raw SQL, writes to the filesystem, or makes an outbound HTTP request.

Security model

• An Application Password is not itself the security boundary. It grants the same access as the WordPress account it belongs to. Agent Bridge's per-route capability checks are defense in depth against a misconfigured or overly broad account, not a substitute for issuing a role no wider than the job needs.

• Per-post checks, never blanket ones. Routes scoped to a single post check edit_post for that exact id. Routes that touch the whole site (restore, cache purge, health, the hash backfill) require manage_options.

• HTTPS is enforced, proxy-aware. An X-Forwarded-Proto: https header is honored only from a reverse proxy the site has explicitly trusted via the agent_bridge_trusted_proxies filter; an unconfigured site never trusts a client-supplied forwarded header, and plain HTTP is refused unless a site opts in for local development.

• Two kill switches, AGENT_BRIDGE_DISABLED and AGENT_BRIDGE_READ_ONLY, set as wp-config.php constants (see Kill Switches above).

• The additive-only gate on every write to pre-existing content (see Additive-Only Gate above).

• Request bodies are size-capped per route, 64KB for SEO and schema writes, 2MB for restore documents, and rejected before WordPress's own JSON decode runs, not after.

• Zero phone-home. No telemetry, no analytics, no outbound request of any kind beyond WordPress's own standard plugin-update check.

Every write is appended to a rolling, 50-entry audit log: ids and route names only, never content or credentials.

{"time": "2026-08-31T12:00:00+00:00", "user_id": 3, "route": "/posts/{id}/seo", "post_id": 42}

The log is readable directly in the database as the agent_bridge_audit option; there's no separate admin screen for it yet.

A full threat model, mapping specific failure modes (a shared credential, a looping destructive tool call, a naive content write flattening Elementor's serialized JSON) to the specific mechanism that closes each one, lives in docs/THREAT-MODEL.md; the precise definition of every named mechanism above lives in docs/SAFETY.md.

How Agent Bridge compares

Checked on 2026-08-31 against each project's GitHub API data and its own public docs (sources linked below). This space moves fast: re-verify before citing any of this months later. A longer version of this table, including the archived and stale projects worth knowing not to cite as current, lives in docs/COMPARISON.md.

Where Agent Bridge falls short today

• Rank Math only. The field map and schema adapter are isolated in their own classes, so adding another SEO plugin is a contained addition, not a rewrite, but as shipped there's nothing for Yoast, AIOSEO, or SEOPress users to read or write yet.

• LiteSpeed-only cache purge. /cache/purge calls LiteSpeed's own purge actions. On a site running a different cache layer, the route reports purged: false with an explicit warning rather than silently doing nothing, but it does not purge anything else.

• Field-validated MCP surface (2026-08-31). All eight abilities were exercised end to end on a live production site through the official MCP Adapter: discovery, execution, write with read-back, schema write and delete, cache purge, and the additive-only gate refusing an unconfirmed write to pre-existing content over MCP.

FAQ

Does Agent Bridge only work with Claude Code?

No. The eight abilities surface through the official WordPress MCP Adapter, which speaks standard MCP; any MCP client (Cursor, Windsurf, Codex CLI, Gemini CLI, a custom agent) can call them the same way Claude Code does. The REST surface is plainer still: any HTTP client holding a WordPress Application Password can use it. Claude Code simply gets the most documentation, since agent-driven site work is where the safety gates earn their keep.

What is an AI agent for WordPress?

A program, often an LLM like Claude working from natural-language instructions, that reads and writes a site's content, structure, or settings the way a human editor would, typically over the REST API or MCP tools rather than logging into wp-admin. WordPress's own Abilities API is the sanctioned mechanism for exposing what an agent is allowed to touch: a plugin registers a typed, named ability, that ability is checked against a real WordPress capability, and only then does an MCP client get to call it. Agent Bridge is one such agent-facing plugin: it adds no chat interface or model of its own, only the SEO, schema, and safety operations an agent needs to manage a site responsibly.

What is a WordPress MCP server, and how do I use one with Claude Code?

MCP (Model Context Protocol) lets an AI agent discover and call a set of typed tools instead of guessing at raw API calls. On WordPress, the Abilities API is the official path: a plugin registers abilities, and the official mcp-adapter exposes every public one as an MCP tool. Agent Bridge registers eight abilities this way (see Abilities API and MCP above); install mcp-adapter, connect Claude Code to it, and Agent Bridge's SEO, schema, snapshot, and cache-purge tools show up alongside any other plugin's abilities.

Can Claude Code edit Elementor pages?

Yes, through EMCP (Elementor MCP for Claude Code), not through Agent Bridge. Agent Bridge deliberately never writes _elementor_data; it reads that field verbatim for snapshots and writes it back byte-for-byte during a restore, but all actual layout composition stays with EMCP or a similar Elementor-editing tool.

Does Rank Math have a REST API?

Rank Math ships its own first-party MCP tools as of 2026 (rank-math/get-post-schema and meta read/write, documented at rankmath.com/kb/mcp-tools). Agent Bridge reads and writes the same underlying postmeta over plain REST and the Abilities API, with a write-then-read-back verification step Rank Math's own tools don't document. Use whichever surface your agent already has connected; both point at the same stored fields.

How do AI agents safely edit WordPress without breaking the site?

The concrete pattern, not just the principle: check a real WordPress capability on every write, scoped to the specific post rather than a blanket grant; read a write back from the database before calling it successful; snapshot content with a hash the agent can compare against before editing anything that predates its own involvement; and keep an operator-facing kill switch that doesn't depend on the agent behaving correctly. Agent Bridge implements all four as its Verified Writes, Additive-Only Gate, Stable Content Hash, and Kill Switches (each documented above); WordPress core's own guidance points the same direction (permission_callback, dedicated MCP users, least-privilege roles).

How do I install an MCP server on a self-hosted WordPress.org site?

Upload the plugin zip, activate it, and create a WordPress Application Password for the account your agent will authenticate as (Users → Profile → Application Passwords). That's the whole REST-API path. For MCP-tool exposure specifically, rather than plain REST, also install the WordPress Abilities API (built into WordPress 6.9+) and the official mcp-adapter plugin; the eight abilities Agent Bridge already registers become available with no further configuration.

What is the best MCP server for WordPress?

It depends on the job. A generalist server with the most tools is the right pick for broad content and admin work; EMCP or a similar builder-aware tool is the right pick for Elementor layout; Agent Bridge is built for the layer both of those tend to leave out, SEO fields and JSON-LD schema with a verified write, and content snapshots with a verified restore. See the comparison table above for what each named tool actually documents, not just what it advertises.

How do I fill or update Rank Math SEO fields through the REST API?

POST a field: value map to /wp-json/agent-bridge/v1/posts/{id}/seo, using any of the 15 supported fields (title, description, canonical URL, robots directives, focus keyword, and the Open Graph and Twitter card fields). The response only reports a field saved after reading it back from the database; an empty string, empty array, or null clears that field back to its default. See Read and write SEO fields above for a worked example, including the extra confirmation step required on content that predates the plugin's activation.

Architecture

agent-bridge.php only bootstraps: it defines constants, requires each class below, and hooks rest_api_init, the Abilities API actions, and the hash-maintenance hooks. Every actual feature lives in one file under includes/, each owning exactly one concern:

Uninstalling

Deactivating and deleting the plugin removes only the agent_bridge_audit option, per uninstall.php. SEO fields, schema meta, and post content are never touched on uninstall: they belong to Rank Math and to the site's own content, not to this plugin. The per-post _agent_bridge_hash meta this plugin adds is left behind (a harmless, inert key, not sensitive data); cleaning it up automatically is deferred to a later release.

Contributing

Issues and pull requests are welcome. This is a small, single-purpose plugin: each feature class in includes/ owns exactly one concern (auth, health, snapshot, SEO, schema, restore, cache, abilities), and every route is wired in one place, includes/class-routes.php. Read the class you're touching, and its docblock, before proposing a new route or field; several of the existing validators exist because a field looked simple and silently wasn't (see the CONTRACT DEVIATIONS note at the top of includes/class-seo.php for a worked example).

Try it in Docker

docker/ has a self-contained Dockerfile that boots a complete WordPress site with Agent Bridge and the official MCP Adapter already installed and activated, running on SQLite so there's no second container to stand up:

docker build -f docker/Dockerfile -t agent-bridge-mcp-demo:latest .
docker run -d --name agent-bridge-demo -p 8080:80 agent-bridge-mcp-demo:latest

Once it's up, POST an MCP initialize to http://localhost:8080/wp-json/mcp/mcp-adapter-default-server with no credentials and you'll get back a session id and serverInfo; tools/list on that session, then tools/call on mcp-adapter-discover-abilities, surfaces all eight agent-bridge/* abilities anonymously. See docker/README.md for the full walkthrough, exactly what the included demo-only mu-plugin does and doesn't relax, and how to authenticate with the bootstrap Application Password for anything beyond read-only discovery.

Author

Built and maintained by Nipun Arora. Bug reports and questions: GitHub issues.

License

GPL-2.0-or-later. See LICENSE.