MCP Plugin: JSON Schema for blocks and relationship fields is incomplete

[jhb-dev]

Describe the Bug

The MCP plugin generates incomplete JSON schemas for blocks and relationship fields. When blocks use interfaceName, the generated schema loses the block definitions entirely, resulting in empty/useless schemas.

The Problem

When Payload generates JSON schemas, blocks with interfaceName use $ref references that point to root-level definitions:

{
  "$ref": "#/definitions/HeroBlock"
}

These block definitions exist at the root level of configSchema.definitions, not within the collection schema itself.

The MCP plugin appears to only extract the collection definition, missing these root-level $ref targets. This results in broken schemas like:

{
  "blocks": {
    "anyOf": [
      { "items": {}, "type": "array" },
      { "type": "null" }
    ]
  }
}

Instead of the expected complete schema with block field definitions.

Expected Behavior

The MCP schema should include all referenced block definitions.

Link to the code that reproduces this issue

https://github.com/jhb-dev/payload-mcp-schema-blocks-missing

Reproduction Steps

1. Clone the reproduction repository and run the development server with pnpm dev
2. Connect an MCP client to the Payload MCP endpoint
3. Inspect the schema for the posts collection's create or update tools
4. Observe that the blocks field has an empty/incomplete schema: {"anyOf": [{"items": {}, "type": "array"}, {"type": "null"}]}
5. When asking the LLM to use the createPosts tool to create a post with blocks, it fails

Which area(s) are affected?

plugin: mcp

Environment Info

Binaries:
  Node: 24.3.0
  npm: 11.4.2
  Yarn: 1.22.22
  pnpm: 10.12.4
Relevant Packages:
  payload: 3.68.4
  next: 15.4.10
  @payloadcms/db-mongodb: 3.68.4
  @payloadcms/graphql: 3.68.4
  @payloadcms/next/utilities: 3.68.4
  @payloadcms/plugin-mcp: 3.68.4
  @payloadcms/richtext-lexical: 3.68.4
  @payloadcms/translations: 3.68.4
  @payloadcms/ui/shared: 3.68.4
  react: 19.2.1
  react-dom: 19.2.1
Operating System:
  Platform: darwin
  Arch: arm64