7 bugs I caught in my MCP server before publishing (and why I almost shipped a data-corruption disaster)

Hardening MCP Integrations: Resilience Patterns for WordPress Automation

Current Situation Analysis

Building Model Context Protocol (MCP) servers for opinionated SaaS platforms like WordPress introduces a class of failures that unit tests and static analysis cannot detect. Developers often assume that a 200 OK response from a REST API guarantees persistence, or that remote command execution behaves identically across interactive and non-interactive shells. In production environments managing dozens of client sites, these assumptions lead to silent data corruption, false error reporting, and brittle automation pipelines.

The core pain point is the gap between "API compliance" and "operational reality." WordPress REST endpoints have specific registration requirements for metadata that are not enforced by standard HTTP status codes. Similarly, managed hosting environments strip environment variables and alter binary paths in non-interactive SSH sessions. When an MCP server acts as an autonomous agent, it lacks the human intuition to recognize when a write operation has been silently discarded or when a stderr stream contains benign system banners rather than fatal errors.

Evidence from production deployments indicates that standard validation suites miss critical edge cases. In a fleet of 50 WordPress installations, end-to-end testing against live targets revealed seven distinct failure modes. Three of these resulted in silent data loss where the API returned success but the payload was never persisted. The remaining issues caused false error propagation and timeout failures. Relying solely on local mocks or type-checking creates a false sense of security; resilience must be engineered at the transport and boundary layers.

WOW Moment: Key Findings

The following comparison illustrates the operational difference between a naive implementation that trusts standard API behaviors and a hardened implementation that enforces verification and boundary normalization.

Approach	Data Integrity Risk	False Error Rate	Cold Start Latency	Setup Complexity
Naive REST/CLI	High (Silent drops)	High (Stderr pollution)	Unpredictable (>30s)	Low
Hardened/Boundary-Normalized	Near Zero (Verified writes)	Low (Filtered banners)	Configurable (Graceful)	Medium

Why this matters: The hardened approach shifts failure detection from "silent corruption" to "explicit error." By implementing verification loops and transport normalization, the system ensures that an MCP tool call either succeeds with confirmed persistence or fails with a descriptive error. This eliminates the customer-support nightmare of "the tool said it worked, but the site didn't change."

Core Solution

Resilience in MCP servers for WordPress requires a strategy centered on Boundary Normalization, Explicit Verification, and Environment Probing. The implementation must treat the WordPress REST API and WP-CLI as distinct transports with different serialization rules and reliability characteristics.

1. Boundary Normalization for Metadata

WordPress REST and WP-CLI handle metadata serialization differently. The REST API may parse JSON strings into objects for registered meta keys, while WP-CLI returns raw serialized strings. An MCP server must normalize these representations at the transport boundary to prevent type mismatches during read-modify-write cycles.

// transport-normalizer.ts

export interface MetaPayload {
  key: string;
  value: unknown;
  transport: 'rest' | 'cli';
}

export class MetaNormalizer {
  /**
   * Normalizes meta values to a consistent internal representation.
   * Handles the discrepancy where REST returns parsed objects
   * and WP-CLI returns JSON strings for the same field.
   */
  static normalize(payload: MetaPayload): string | object {
    const { value, transport } = payload;

    if (transport === 'rest') {
      // REST may return an object for registered meta keys.
      // We stringify for internal consistency if needed, 
      // or keep as object depending on downstream requirements.
      return typeof value === 'string' ? JSON.parse(value) : value;
    }

    if (transport === 'cli') {
      // WP-CLI returns strings. Ensure we have a parseable object.
      if (typeof value === 'string') {
        try {
          return JSON.parse(value);
        } catch {
          // Fallback for non-JSON strings
          return value;
        }
      }
      return value;
    }

    throw new Error(`Unsupported transport: ${transport}`);
  }

  /**
   * Prepares a value for writing to a specific transport.
   */
  static serializeForWrite(value: unknown, transport: 'rest' | 'cli'): string | object {
    if (transport === 'rest') {
      // REST often expects objects for registered meta.
      return typeof value === 'string' ? JSON.parse(value) : value;
    }
    
    // WP-CLI expects strings.
    return typeof value === 'string' ? value : JSON.stringify(value);
  }
}

Rationale: Normalization at the boundary prevents type errors deep in the domain logic. By centralizing the conversion, the MCP server can safely route data between REST and CLI tools without duplicating serialization logic.

2. SSH Path Probing and Binary Resolution

Non-interactive SSH sessions often have a stripped PATH environment variable. Assuming wp is available globally will cause command-not-found errors on managed hosts where WP-CLI is installed in user directories.

// ssh-executor.ts

import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

export class SshExecutor {
  private cachedPath: string | null = null;

  async resolveWpCliPath(hostConfig: { user: string; host: string }): Promise<string> {
    if (this.cachedPath) return this.cachedPath;

    const candidates = [
      'wp',
      '~/bin/wp.phar',
      '~/wp-cli.phar',
      '/usr/local/bin/wp',
    ];

    for (const candidate of candidates) {
      try {
        // Probe using 'command -v' which works in non-interactive shells
        const cmd = `ssh ${hostConfig.user}@${hostConfig.host} "command -v ${candidate}"`;
        const { stdout } = await execAsync(cmd);
        
        if (stdout.trim()) {
          this.cachedPath = stdout.trim();
          return this.cachedPath;
        }
      } catch {
        // Candidate not found, try next
        continue;
      }
    }

    throw new Error('WP-CLI binary not found in any standard location. Provide explicit path in config.');
  }

  async execute(hostConfig: { user: string; host: string }, wpCommand: string): Promise<string> {
    const wpPath = await this.resolveWpCliPath(hostConfig);
    const fullCommand = `ssh ${hostConfig.user}@${hostConfig.host} "${wpPath} ${wpCommand}"`;
    
    const { stdout, stderr } = await execAsync(fullCommand);
    
    // Apply stderr filtering here (see Pitfall Guide)
    const cleanStderr = this.filterBenignStderr(stderr);
    if (cleanStderr) {
      console.warn(`Stderr warning: ${cleanStderr}`);
    }

    return stdout;
  }

  private filterBenignStderr(stderr: string): string {
    const benignPatterns = [
      /post-quantum/i,
      /openssh\.com\/pq/i,
      /decrypt later/i,
    ];

    const lines = stderr.split('\n');
    const filtered = lines.filter(line => 
      !benignPatterns.some(pattern => pattern.test(line))
    );

    return filtered.join('\n').trim();
  }
}

Rationale: Auto-detection with caching reduces latency on subsequent calls while ensuring compatibility across diverse hosting environments. Filtering stderr prevents benign OpenSSH warnings from being misinterpreted as command failures.

3. Verification Loops for Critical Writes

The WordPress REST API may return 200 OK even when writes to unregistered postmeta keys are silently dropped. A verification loop is mandatory for data integrity.

// wp-rest-client.ts

export class WpRestClient {
  async writeMetaWithVerification(
    siteUrl: string, 
    postId: number, 
    key: string, 
    value: unknown, 
    token: string
  ): Promise<void> {
    const payload = { meta: { [key]: value } };
    
    // 1. Attempt write
    const response = await fetch(`${siteUrl}/wp-json/wp/v2/pages/${postId}`, {
      method: 'PUT',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`,
      },
      body: JSON.stringify(payload),
    });

    if (!response.ok) {
      throw new Error(`Write failed: ${response.statusText}`);
    }

    // 2. Verify persistence
    const verifyResponse = await fetch(`${siteUrl}/wp-json/wp/v2/pages/${postId}?context=edit`, {
      headers: { 'Authorization': `Bearer ${token}` },
    });

    if (!verifyResponse.ok) {
      throw new Error(`Verification read failed: ${verifyResponse.statusText}`);
    }

    const data = await verifyResponse.json();
    const persistedValue = data.meta?.[key];

    // 3. Compare values (deep equality recommended for objects)
    if (JSON.stringify(persistedValue) !== JSON.stringify(value)) {
      throw new Error(
        `Data integrity check failed. Key "${key}" was not persisted. ` +
        `Expected: ${JSON.stringify(value)}, Got: ${JSON.stringify(persistedValue)}. ` +
        `Consider using WP-CLI for unregistered meta keys.`
      );
    }
  }
}

Rationale: This pattern converts silent failures into explicit errors. If the REST API drops the write, the verification step detects the mismatch and throws, allowing the MCP server to fallback to WP-CLI or alert the user. This prevents the "data corruption disaster" scenario where the agent proceeds assuming the backup or update succeeded.

Pitfall Guide

1. Silent Meta Drops via REST

Explanation: WordPress REST API requires register_meta() with show_in_rest: true for a postmeta key to be writable. Custom keys invented at runtime are silently discarded, yet the API returns 200 OK. Fix: Never trust REST for unregistered meta writes. Use WP-CLI for custom keys or implement a verification loop to confirm persistence.

2. Non-Interactive SSH PATH Assumptions

Explanation: ssh user@host "command" executes in a non-interactive shell with a minimal PATH. Binaries like wp installed in ~/bin are often invisible. Fix: Probe for the binary using command -v or accept an explicit path configuration. Cache the resolved path to avoid repeated probes.

3. Stderr Conflation with Errors

Explanation: System banners (e.g., OpenSSH post-quantum warnings) are written to stderr. Naive error handling treats any stderr output as a command failure. Fix: Filter known benign patterns from stderr before evaluating command success. Whitelist substrings like post-quantum or openssh.com.

4. Transport Serialization Mismatches

Explanation: Registered meta keys may return parsed objects via REST but serialized JSON strings via WP-CLI. Passing a string to a REST endpoint expecting an object causes type errors. Fix: Normalize data types at the transport boundary. Parse strings to objects when reading from CLI; stringify objects when writing to CLI.

5. Cold Start Latency in Headless Tools

Explanation: Tools like Headless Chrome or heavy CLI processes may have significant cold-start latency (e.g., downloading codecs) that exceeds default timeouts. Fix: Configure timeouts based on worst-case scenarios, not happy-path benchmarks. Document cold-start behavior and consider warm-up strategies for latency-sensitive tools.

6. Unreliable Server-Side Meta Filtering

Explanation: WordPress REST meta_value filters are unreliable for unregistered meta keys. They may fall back to checking key existence only, returning incorrect results. Fix: Fetch the full collection and filter client-side. This ensures accurate results at the cost of additional bandwidth.

7. Pattern Replication Bugs

Explanation: Copy-pasting broken logic (e.g., a flawed filter) across multiple tools propagates the bug. Fix: Abstract common patterns into reusable utilities. When fixing a bug, search the codebase for the underlying pattern to ensure comprehensive remediation.

Production Bundle

Action Checklist

• Implement verification loops for all REST writes to custom or unregistered meta keys.
• Add SSH path probing logic with fallback candidates and caching.
• Filter benign stderr patterns (e.g., OpenSSH warnings) before error evaluation.
• Create a boundary normalizer to handle type differences between REST and CLI transports.
• Replace server-side meta filters with client-side filtering for unregistered keys.
• Configure timeouts to account for cold-start latency in headless tools.
• Run end-to-end tests against a live WordPress installation before publishing.
• Abstract shared logic to prevent copy-paste bug propagation.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Write custom postmeta	WP-CLI via SSH	REST silently drops unregistered keys. CLI is reliable.	Requires SSH access; higher setup complexity.
Filter templates by type	Client-side filtering	Server-side meta_value filter is unreliable for unregistered keys.	Increased bandwidth; negligible compute cost.
Read _elementor_page_settings	Boundary Normalization	REST returns object; CLI returns string. Normalization prevents type errors.	Minimal CPU overhead; improves reliability.
Execute remote WP-CLI	Probed Path Resolution	Non-interactive SSH has stripped PATH. Probing ensures binary discovery.	One-time latency per session; cached thereafter.
Screenshot generation	Configurable Timeout	Headless Chrome cold-start can exceed 30s. Default timeouts cause false failures.	Slightly longer max latency; fewer errors.

Configuration Template

{
  "mcp_server": {
    "name": "wp-automation-server",
    "version": "1.0.0",
    "transport": {
      "rest": {
        "verify_writes": true,
        "timeout_ms": 15000
      },
      "ssh": {
        "path_probe": true,
        "candidates": ["wp", "~/bin/wp.phar", "~/wp-cli.phar"],
        "timeout_ms": 30000
      }
    },
    "tools": {
      "screenshot": {
        "timeout_ms": 60000,
        "cold_start_warning": true
      },
      "meta_filtering": {
        "strategy": "client_side",
        "unregistered_keys": ["_elementor_template_type"]
      }
    },
    "stderr_filtering": {
      "enabled": true,
      "benign_patterns": [
        "post-quantum",
        "openssh.com/pq",
        "decrypt later"
      ]
    }
  }
}

Quick Start Guide

1. Initialize Configuration: Create a config.json using the template above. Set verify_writes to true and enable path_probe for SSH.
2. Define Transport Boundaries: Implement the MetaNormalizer class to handle serialization differences. Ensure all REST and CLI calls pass through this layer.
3. Deploy Verification Logic: Wrap all write operations in a verification loop. If the read-back value does not match the write payload, throw an explicit error.
4. Test Against Live Target: Run the MCP server against a staging WordPress installation. Execute tools that write custom meta and filter templates. Verify that errors are raised for silent drops and that filters return correct results.
5. Monitor Stderr: Check logs for filtered stderr messages. Ensure OpenSSH banners do not trigger error alerts. Adjust benign_patterns if new warnings appear.