Add WPGuard to Windsurf’s MCP configuration, secure your bearer token in your environment, and give Cascade a reviewable path from site inspection to verified WordPress updates.
Self-hosted · Streamable HTTP · Global or workspace MCP configuration
Declare WPGuard in Windsurf’s configuration file using the native Streamable HTTP format and authenticate with a scoped bearer token.
{
"mcpServers": {
"wpguard": {
"serverUrl": "http://127.0.0.1:8642/mcp",
"headers": {
"Authorization": "Bearer <YOUR_WPGUARD_TOKEN>"
}
}
}
}Windsurf stores global MCP configuration at ~/.codeium/windsurf/mcp_config.json on macOS and Linux, or %USERPROFILE%\.codeium\windsurf\mcp_config.json on Windows. Windsurf reads this file on initialization to register active server tools into Cascade’s workspace context.
Unlike stdio servers that execute local binary processes for every conversation, WPGuard runs as a dedicated daemon over Streamable HTTP. Windsurf requires the serverUrl attribute and a nested headers object containing the required Authorization string.
WPGuard enforces token authentication on every tool call. If the Authorization: Bearer header is missing or invalid, the server responds immediately with HTTP 401 Unauthorized. Keep your token in private workstation files rather than committing configuration into shared repositories.
When Windsurf and WPGuard run on the same physical machine, binding to 127.0.0.1:8642 provides zero-latency, private communication. If WPGuard is hosted on a remote server, connect through an SSH tunnel or Tailscale network rather than exposing unencrypted HTTP over the public internet.
WPGuard enforces three distinct permission tiers. Match the token scope to the specific task you want Windsurf to perform.
Ideal for read-only audits, SEO reviews, and discovery. Cascade can query registered sites with site_list, inspect active themes and plugins with wp_site_context, read stored post content, and inspect metadata. It cannot write changes or approve modification packets.
The standard operational tier for daily content and settings updates. Cascade can generate preview packets, run automated correction checks, and apply approved mutations to posts, pages, and options. It cannot execute arbitrary PHP code or run raw WP-CLI shell commands.
Reserved for administrative site setup, registering new WordPress connections, creating persistent correction rules, and running privileged diagnostics. Use admin tokens only when setting up infrastructure or defining client policies.
Tokens apply instance-wide across all sites registered on a given WPGuard server. To keep client staging sites separate from live customer environments, run independent WPGuard instances with distinct ports and separated state directories.
Never let an AI editor write directly to WordPress without a dry run. WPGuard structures Cascade’s actions into reviewable phases.
Begin by asking Cascade to run wp_site_context on your target site. Cascade retrieves the current WordPress version, active plugins, theme details, and available fields. This grounds Cascade in real site structure rather than assumed schemas.
When requesting an edit, instruct Cascade to pass apply=False. WPGuard reads the current stored database record, executes the proposed replacement in memory, and returns a structured packet showing the exact old value, new value, and active rule check results.
Review the proposed diff directly in Windsurf’s chat panel. Confirm that Cascade accurately modified the targeted sentence or option without deleting adjacent block markup, truncating shortcodes, or corrupting HTML entity formatting.
When you approve the edit, Cascade calls the mutation tool with apply=True and the preview’s state tag. If another user modified the post in WordPress during the preview phase, the state hash fails and WPGuard rejects the write to prevent silent overwrites.
Prompt instructions disappear when context compacts. WPGuard’s correction engine deterministically protects mandatory requirements.
If a landing page requires an explicit refund notice, medical disclaimer, or license registration, save that requirement as a correction rule. WPGuard checks the requirement before every mutation and blocks writes that omit required phrases.
Correction checks are strictly scoped. A rule protecting specific booking policies on your checkout page will not restrict blog posts, documentation, or header menus across other pages on your site.
Every rule preserves the prompt, date, and user reason that created it. When policies change, operators can inspect why a rule was instituted, update the criteria, or retire the rule cleanly.
Because correction rules execute in WPGuard’s Python core rather than inside Cascade’s token prediction loop, they cannot be bypassed by clever phrasing, hallucinations, or long conversation histories.
A successful database write is not proof that the page looks right. WPGuard provides automated browser verification.
An agent confirming that MySQL accepted a new string does not verify that CSS styling remains intact. Broken HTML tags, unrendered shortcodes, or layout shifts only appear when the page renders in a real browser engine.
WPGuard can trigger headless Playwright to capture full-page desktop (1280px) and mobile (390px) screenshots following a mutation, preserving visual receipts in your local artifact directory for quick operator review.
The render check inspects the rendered DOM for missing image assets (HTTP 404 responses), horizontal viewport overflow, broken link paths, heading hierarchy anomalies, and unhandled JavaScript console errors.
Always connect Windsurf to a staging clone first. Test Cascade’s suggested changes, verify the preview packet, and review the screenshot receipts before running mutations against live customer-facing sites. Learn more in our staging to production safety guide.
Run WPGuard locally, configure your bearer token, and preview your first guarded WordPress edit.