Repository navigation
plugin-mcp: revalidatePath/revalidateTag called in hooks during MCP tool calls are silently dropped #18490
Description
Describe the Bug
Changes made through the MCP plugin's tools are saved, but revalidatePath/revalidateTag calls from collection or global hooks (e.g. afterChange) have no effect, so statically rendered pages keep showing the old content. The same change saved in the admin panel revalidates as expected. Nothing throws or logs.
Cause: the /api/mcp endpoint (built on mcp-handler) returns its text/event-stream response as soon as the stream opens and runs the tool while the body streams. mcp-handler's response adapter resolves the Response once the headers are written, before the tool has finished. Next.js applies a route handler's pending revalidations when the handler returns, so revalidations called during the tool call come too late and are dropped. Locally, the handler returned about 120 ms before revalidatePath ran.
Workaround: wrap the plugin and let the POST /mcp handler read the whole response before returning, so the tool finishes inside the handler:
const awaitResponseBody =
(handler: PayloadHandler): PayloadHandler =>
async (request) => {
const response = await handler(request);
return new Response(await response.arrayBuffer(), response);
};Possible fix in the plugin: buffer the response in the /mcp endpoint like above (Payload's tools only return a single result). Alternatively, mcp-handler could expose the SDK transport's enableJsonResponse option, but it currently only passes sessionIdGenerator.
Longer write-up: https://lukashechenberger.com/blog/your-payload-mcp-edits-never-show-up-on-the-site
Link to the code that reproduces this issue
(A public site that contains the workaround. Using @payloadcms/plugin-mcp directly instead of this wrapper in payload.config.ts reproduces the bug.)
Reproduction Steps
- Add an
afterChangehook that callsrevalidatePath('/', 'layout')to a collection that a statically rendered page reads. - Update a document through an MCP update tool (
POST /api/mcp). - The document is updated, but the page still shows the old content. Saving the same document in the admin panel refreshes it.
Which area(s) are affected?
plugin: mcp
Environment Info
payload: 3.90.2
@payloadcms/plugin-mcp: 3.90.2
mcp-handler: 1.1.0
next: 16.3.6
Node.js: 24
Activity
aayushbaluni commentedon Oct 6, 2026
Your diagnosis matches the code on the branch you are running, and it does not
match
main— which I think makes this a "which branch gets the fix" questionrather than a "what is the cause" one.
On
3.x(packages/plugin-mcp/package.json): version3.90.2, exactlywhat you report, depending on
mcp-handler: ^1.0.7— consistent with themcp-handler: 1.1.0in your environment block. So the mechanism you describe,the response resolving once the stream's headers are written and the tool
finishing afterwards, applies to the code you are actually running.
On
main:plugin-mcpis4.0.0-canary.37andmcp-handleris gone. Theendpoint now uses
@modelcontextprotocol/server@2.3.1viacreateMcpHandlerwith
and the legacy path passes
enableJsonResponse: true. That migration landed ind947584 (2026-07-06), before this report. A JSON-mode response has to be
buffered to be emitted at all, so
await handler.fetch(...)should not resolveuntil the tool has returned — which is the thing that was going wrong for you.
So the possibilities look like:
mcp-handlerera and is already moot on 4.x, inwhich case this is a backport decision for
3.xrather than a fix onmain; orcase the cause in the report needs revisiting against the new transport.
I would rather not guess which. If a maintainer says 1 and wants
3.xfixed, Iam happy to open a PR against that branch using the shape from your wrapper —
reading the response body to completion inside the handler so the tool finishes
before Next.js flushes pending revalidations — with the
afterChange+revalidatePathcase as a test. If the answer is "upgrade to 4.x", that is worthsaying on the issue so the next person finds it.
Caveat on my side: this is verification of the code and the dependency graph on
both branches, not a reproduction. I have not run either version, so if you can
reproduce on a 4.x canary that settles it against option 2 immediately.