Skip to main content Skip to navigation
Code on a laptop screen, representing troubleshooting MCP tool calls after a PHP version change

Why MCP Tool Calls Fail After a PHP Version Change

9 min read

We recently ran into a frustrating one: after a PHP version change on a WordPress server, the MCP tool calls coming from Claude started failing. The site itself loaded fine. The admin worked. But the AI connector, which had been running smoothly for weeks, suddenly could not complete a single call.

If you run an MCP server inside WordPress, this is worth understanding properly, because a PHP switch breaks MCP in ways that ordinary page loads never reveal. This guide walks through why it happens, the six most common causes, and a fast checklist to find and fix yours.

Why a PHP Version Change Breaks MCP but Not Your Website

A normal WordPress page is forgiving. If PHP prints a deprecation notice or a warning, the browser still renders the HTML around it, and most visitors never notice. MCP is not forgiving at all.

MCP uses JSON-RPC. Every tool call expects a clean, valid JSON response with the correct headers. A single stray line of output, a missing PHP extension, or a dropped authorization header turns that response into something the AI client cannot parse or accept. The result is a failed call, often with a vague error on the client side and nothing obvious on the website.

That is why “the site works, but the connector does not” is the classic signature of a PHP version problem. If you want the bigger picture of how MCP requests differ from normal web requests, our guide on MCP vs WordPress REST API covers it in detail.

The 6 Most Common Causes

1. PHP Extensions Were Not Installed for the New Version

On Ubuntu and Debian servers, each PHP version has its own set of extension packages. Installing a new PHP version does not carry over the extensions you had on the old one. If the old version had curl, mbstring, xml and intl, the new version may have none of them until you install them again.

MCP servers and the plugins around them commonly depend on these. A missing mbstring or curl can produce a fatal error only on the code paths the connector uses.

php -m                      # list loaded modules (CLI)
sudo apt install php8.x-curl php8.x-mbstring php8.x-xml php8.x-intl
sudo systemctl restart php8.x-fpm

Replace 8.x with your actual version.

2. Deprecation Notices Are Corrupting the JSON Response

Newer PHP versions deprecate older patterns. PHP 8.2 deprecated dynamic properties, and PHP 8.4 deprecated implicitly nullable parameter types, among others. Code that ran silently before can start emitting notices after an upgrade.

If display_errors is on, those notices are printed straight into the response body, ahead of the JSON. The MCP client receives something like Deprecated: ... {"jsonrpc":"2.0",...} and fails to parse it. Keep errors in the log, never in the output:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Then fix the underlying deprecations in the plugin rather than just hiding them.

3. The Authorization Header Is Being Stripped

This one catches a lot of people. MCP connectors typically authenticate with a bearer token in the Authorization header. When a PHP change also changes how PHP runs, for example moving from mod_php to PHP-FPM, Apache may stop passing that header to PHP. Every tool call then arrives unauthenticated and gets rejected with a 401, even though nothing about your tokens changed.

The fix on Apache is to forward the header explicitly in .htaccess or the virtual host:

CGIPassAuth On
# or, on older setups:
SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

Authentication handling is a core part of MCP safety, so it is worth reviewing alongside our WordPress MCP security guide.

4. Your php.ini Settings Did Not Follow You

Each PHP version reads its own configuration file, such as /etc/php/8.x/fpm/php.ini. Any limits you had raised on the old version, like memory_limit, max_execution_time or post_max_size, are back to defaults on the new one.

MCP calls that do heavier work, such as bulk updates, content searches or media handling, are the first to hit a lower memory or time limit. Re-apply your custom values to the new version’s php.ini and restart PHP-FPM.

5. The Web Server Is Running a Different PHP Than You Think

Running php -v in the terminal shows the CLI version. Your web server may be using a completely different one. After a switch, it is easy to end up with the CLI on the new version and PHP-FPM or Apache still on the old one, or the reverse.

On Nginx, a stale fastcgi_pass pointing to the old FPM socket, such as php8.3-fpm.sock when only php8.4-fpm.sock is running, produces 502 errors on every request, MCP included. Always confirm the version from inside WordPress under Tools β†’ Site Health β†’ Info β†’ Server.

6. A Downgrade Hit Code That Needs Newer PHP

Version changes are not always upgrades. Hosts sometimes roll a site back, or a staging copy runs on older PHP. Modern plugin code may use enums (PHP 8.1), readonly classes (PHP 8.2) or typed class constants (PHP 8.3). On an older version, that is a parse error, and the whole MCP endpoint goes down with it.

Check the Requires PHP header of your MCP plugin and match the server to it. If you build your own tools, declare that minimum honestly. Our guide on adding MCP support to a WordPress plugin covers good practice here.

Quick Reference: Symptom to Likely Cause

SymptomMost likely causeFirst check
401 / unauthorized on every callAuthorization header strippedCGIPassAuth or SetEnvIf rule
JSON parse error on the clientNotices printed into outputdisplay_errors and WP_DEBUG_DISPLAY
500 error on certain tools onlyMissing PHP extensionphp -m and the error log
502 Bad Gateway on everythingWrong PHP-FPM socketfastcgi_pass path in Nginx
Timeouts on heavy toolsphp.ini limits resetmemory_limit, max_execution_time
Endpoint fully down after rollbackCode needs newer PHPPlugin’s Requires PHP header

A 5-Minute Diagnostic Checklist

Work through these in order. Most issues show up in the first three steps.

  1. Confirm the real version. Check Site Health, not just the terminal.
  2. Read the error log. Enable WP_DEBUG_LOG with display off, then reproduce a failing tool call and read wp-content/debug.log.
  3. Call the endpoint directly. A raw curl request to your MCP endpoint with your token shows exactly what the client receives, including any stray output before the JSON.
  4. Compare extensions. Run php -m for the new version and compare it against what the old version had loaded.
  5. Restart and retest. Restart PHP-FPM and the web server so OPcache and config changes take effect, then retry the call.
curl -i -X POST https://yoursite.com/your-mcp-endpoint \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

If that response starts with anything other than a clean JSON body, you have found your problem.

How to Avoid This Next Time

A PHP change should be treated as a deployment, not a settings toggle. A few habits prevent most of the pain:

  • Test on staging first, including at least one real MCP tool call, not just a page load.
  • Keep a list of required extensions for each site so you can reinstall them in one command.
  • Version-control your php.ini changes or keep them in a small override file you can copy across.
  • Keep display_errors off in production permanently, so a notice can never corrupt a response.
  • Add a health check that calls tools/list after any server change and alerts you if it fails.

If you are giving an AI client write access to your site, safe change management matters even more. We cover that in Is It Safe to Give Claude Access to WordPress?

Frequently Asked Questions

Why does my WordPress site work but MCP tool calls fail?

Web pages tolerate stray output and warnings, but MCP needs a clean JSON response and valid authentication on every call. Problems like printed deprecation notices or a stripped Authorization header break MCP while leaving normal pages untouched.

Which PHP version should I use for a WordPress MCP server?

Use an actively supported PHP 8.x release that meets your MCP plugin’s Requires PHP value. Test the exact version on staging with real tool calls before switching production.

How do I know if the Authorization header is being stripped?

If every call returns 401 even with a valid token, log the incoming headers in PHP or check whether HTTP_AUTHORIZATION is empty. Adding CGIPassAuth On usually fixes it on Apache with PHP-FPM.

Is it safe to just hide PHP deprecation notices?

Hiding them from output is correct in production, but keep logging them and fix the code. Deprecations become hard errors in later PHP versions, so ignoring them only delays the next outage.

Do I need to reinstall PHP extensions after every upgrade?

On most Linux servers, yes. Extensions are packaged per PHP version, so a new version starts without the ones you added to the old one. Managed hosts often handle this for you, but it is worth checking.

Conclusion

When MCP tool calls fail right after a PHP version change, the cause is almost never the AI client. It is usually one of six server-side gaps: missing extensions, notices leaking into output, a stripped Authorization header, reset php.ini limits, a mismatched PHP runtime, or code that needs a newer version. Check the real version, read the log, call the endpoint directly, and you will usually find the culprit in minutes. For building tools that hold up across environments, see how to create custom MCP tools for WordPress.

Build on a Reliable WordPress Stack

ByteCore Stack builds free, open-source WordPress plugins designed to run cleanly across modern PHP versions:

  • AI Connector: connect Claude and other AI clients to WordPress over MCP, with scoped permissions and audit logging.
  • SMTP Manager: reliable transactional email with proper SMTP authentication.
  • Lightsail Manager: manage your AWS Lightsail CDN cache straight from WordPress.

Need help with a PHP upgrade or a broken MCP setup on your own site? Contact our team and we will take a look.

Leave a Reply