feat(plugin-mcp): add draft parameter support to MCP find resource tool (#14924)

### What?

Add `draft` parameter support to the MCP plugin's find tool

###   Why?

MCP clients currently have no way to query draft/unpublished documents.
When a collection has drafts enabled, agents need the ability to
retrieve draft versions of documents for preview, editing workflows, or
content management tasks.

###   How?

- Added `draft` boolean parameter to the `findResources` schema in
`schemas.ts`
- Updated `find.ts` to accept and pass the `draft` parameter to both
`payload.find()` and `payload.findByID()` calls
  - Enabled drafts on the test Posts collection to support testing
  - Added integration tests

Co-authored-by: Kendell Joseph <kjoseph@figma.com>

Author: jhb-dev

packages/plugin-mcp/src/mcp/tools/resource/find.ts

@@ -22,6 +22,7 @@ export const findResourceTool = (
     where?: string,
     locale?: string,
     fallbackLocale?: string,
+    draft?: boolean,
   ): Promise<{
     content: Array<{
       text: string
@@ -71,6 +72,7 @@ export const findResourceTool = (
             user,
             ...(locale && { locale }),
             ...(fallbackLocale && { fallbackLocale }),
+            ...(draft !== undefined && { draft }),
           })
 
           if (verboseLogs) {
@@ -126,6 +128,7 @@ ${JSON.stringify(doc, null, 2)}`,
         user,
         ...(locale && { locale }),
         ...(fallbackLocale && { fallbackLocale }),
+        ...(draft !== undefined && { draft }),
       }
 
       if (sort) {
@@ -196,8 +199,8 @@ Page: ${result.page} of ${result.totalPages}
       `find${collectionSlug.charAt(0).toUpperCase() + toCamelCase(collectionSlug).slice(1)}`,
       `${collections?.[collectionSlug]?.description || toolSchemas.findResources.description.trim()}`,
       toolSchemas.findResources.parameters.shape,
-      async ({ id, fallbackLocale, limit, locale, page, sort, where }) => {
-        return await tool(id, limit, page, sort, where, locale, fallbackLocale)
+      async ({ id, draft, fallbackLocale, limit, locale, page, sort, where }) => {
+        return await tool(id, limit, page, sort, where, locale, fallbackLocale, draft)
       },
     )
   }

packages/plugin-mcp/src/mcp/tools/schemas.ts

@@ -34,6 +34,12 @@ export const toolSchemas = {
         .describe(
           'Optional: specific document ID to retrieve. If not provided, returns all documents',
         ),
+      draft: z
+        .boolean()
+        .optional()
+        .describe(
+          'Optional: Whether the document should be queried from the versions table/collection or not.',
+        ),
       fallbackLocale: z
         .string()
         .optional()

test/plugin-mcp/collections/Posts.ts

@@ -2,6 +2,9 @@ import type { CollectionConfig } from 'payload'
 
 export const Posts: CollectionConfig = {
   slug: 'posts',
+  versions: {
+    drafts: true,
+  },
   fields: [
     {
       name: 'title',

test/plugin-mcp/int.spec.ts

@@ -769,6 +769,108 @@ describe('@payloadcms/plugin-mcp', () => {
     )
   })
 
+  describe('Drafts', () => {
+    it('should include draft parameter in find tool schema', async () => {
+      const apiKey = await getApiKey()
+      const response = await restClient.POST('/mcp', {
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          Accept: 'application/json, text/event-stream',
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          id: 1,
+          jsonrpc: '2.0',
+          method: 'tools/list',
+          params: {},
+        }),
+      })
+
+      const json = await parseStreamResponse(response)
+      const findTool = json.result.tools.find((t: any) => t.name === 'findPosts')
+
+      expect(findTool).toBeDefined()
+      expect(findTool.inputSchema.properties.draft).toBeDefined()
+      expect(findTool.inputSchema.properties.draft.type).toBe('boolean')
+      expect(findTool.inputSchema.properties.draft.description).toContain('versions')
+    })
+
+    it('should find draft documents when draft is true', async () => {
+      // Create a published post
+      const post = await payload.create({
+        collection: 'posts',
+        data: {
+          title: 'Published Title',
+          content: 'Published Content',
+        },
+      })
+
+      // Update with draft content (not published)
+      await payload.update({
+        id: post.id,
+        collection: 'posts',
+        data: {
+          title: 'Draft Title',
+          content: 'Draft Content',
+        },
+        draft: true,
+      })
+
+      const apiKey = await getApiKey()
+
+      // Find without draft flag - should get published version
+      const publishedResponse = await restClient.POST('/mcp', {
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          Accept: 'application/json, text/event-stream',
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          id: 1,
+          jsonrpc: '2.0',
+          method: 'tools/call',
+          params: {
+            name: 'findPosts',
+            arguments: {
+              id: post.id,
+            },
+          },
+        }),
+      })
+
+      const publishedJson = await parseStreamResponse(publishedResponse)
+      expect(publishedJson.result.content[0].text).toContain(
+        '"title": "Published Title (MCP Hook Override)"',
+      )
+
+      // Find with draft: true - should get draft version
+      const draftResponse = await restClient.POST('/mcp', {
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          Accept: 'application/json, text/event-stream',
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          id: 1,
+          jsonrpc: '2.0',
+          method: 'tools/call',
+          params: {
+            name: 'findPosts',
+            arguments: {
+              id: post.id,
+              draft: true,
+            },
+          },
+        }),
+      })
+
+      const draftJson = await parseStreamResponse(draftResponse)
+      expect(draftJson.result.content[0].text).toContain(
+        '"title": "Draft Title (MCP Hook Override)"',
+      )
+    })
+  })
+
   it('should find site-settings global', async () => {
     const apiKey = await getApiKey(false, false, true)
     const response = await restClient.POST('/mcp', {