MCP plugin: forward outputSchema for custom tools (enable structuredContent)

[jhb-dev]

Summary

@payloadcms/plugin-mcp lets custom tools declare an inputSchema (via parameters) but provides no way to declare an outputSchema, even though the underlying @modelcontextprotocol/sdk fully supports it. As a result, custom tools cannot advertise a structured-output contract, and any structuredContent a handler returns has no declared schema for clients to validate against — so spec-compliant clients ignore it.

This is the same shape of pass-through gap as #16744 (tool annotations), in the same registration code path.

Current behavior

In dist/mcp/getMcpHandler.js, custom tools are registered like this:

server.registerTool(
  tool.name,
  {
    description: tool.description,
    inputSchema: tool.parameters,
    ...(tool.annotations && { annotations: tool.annotations }),
  },
  payloadToolHandler(tool.handler),
)

Only description, inputSchema, and annotations are forwarded. There is no outputSchema key, and the custom-tool type exposes only parameters and annotations. A handler can already return { content, structuredContent } (the return value passes through untouched), but without a declared outputSchema the structuredContent is not spec-valid.

Proposed behavior

Allow custom tool definitions to provide an optional outputSchema (a ZodRawShape, mirroring how inputSchema uses parameters/.shape) and forward it to server.registerTool:

server.registerTool(
  tool.name,
  {
    description: tool.description,
    inputSchema: tool.parameters,
    ...(tool.annotations && { annotations: tool.annotations }),
    ...(tool.outputSchema && { outputSchema: tool.outputSchema }),
  },
  payloadToolHandler(tool.handler),
)

plus an optional outputSchema?: z.ZodRawShape on the custom-tool type. @modelcontextprotocol/sdk has supported outputSchema + structuredContent since 1.10.x, so this is purely a pass-through gap in the plugin.

Example consumer

const resultSchema = z.object({
  websiteId: z.string(),
  totals: z.object({ traffic: z.number(), leads: z.number() /* … */ }),
  dailyData: z.array(/* … */),
})

export const myTool = {
  name: 'getTrafficSummary',
  description: '…',
  parameters: argsSchema.shape,
  outputSchema: resultSchema.shape, // ← currently ignored by the plugin
  handler: async (args, req) => ({
    content: [{ type: 'text', text: JSON.stringify(result) }],
    structuredContent: result,
  }),
}

Environment

• @payloadcms/plugin-mcp: 3.84.1
• @modelcontextprotocol/sdk: 1.27.1
• Payload: 3.84.1
• Next.js: 16.2.6
• Node.js: 22.19.0