@payloadcms/plugin-mcp 4.0.0-internal.203916b → 4.0.0-internal.2071af3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (210) hide show
  1. package/dist/defaultAccess.d.ts.map +1 -1
  2. package/dist/defineTool.d.ts +8 -8
  3. package/dist/defineTool.d.ts.map +1 -1
  4. package/dist/endpoint/access.d.ts +2 -7
  5. package/dist/endpoint/access.d.ts.map +1 -1
  6. package/dist/endpoint/access.js +29 -16
  7. package/dist/endpoint/access.js.map +1 -1
  8. package/dist/endpoint/index.d.ts.map +1 -1
  9. package/dist/endpoint/index.js +45 -4
  10. package/dist/endpoint/index.js.map +1 -1
  11. package/dist/endpoint/oauth.d.ts +35 -0
  12. package/dist/endpoint/oauth.d.ts.map +1 -0
  13. package/dist/endpoint/oauth.js +96 -0
  14. package/dist/endpoint/oauth.js.map +1 -0
  15. package/dist/endpoint/oauthLoginToken.d.ts +21 -0
  16. package/dist/endpoint/oauthLoginToken.d.ts.map +1 -0
  17. package/dist/endpoint/oauthLoginToken.js +79 -0
  18. package/dist/endpoint/oauthLoginToken.js.map +1 -0
  19. package/dist/endpoint/oauthServer.d.ts +12 -0
  20. package/dist/endpoint/oauthServer.d.ts.map +1 -0
  21. package/dist/endpoint/oauthServer.js +361 -0
  22. package/dist/endpoint/oauthServer.js.map +1 -0
  23. package/dist/index.d.ts +10 -2
  24. package/dist/index.d.ts.map +1 -1
  25. package/dist/index.js +15 -2
  26. package/dist/index.js.map +1 -1
  27. package/dist/mcp/buildMcpServer.d.ts +2 -2
  28. package/dist/mcp/buildMcpServer.d.ts.map +1 -1
  29. package/dist/mcp/buildMcpServer.js +36 -24
  30. package/dist/mcp/buildMcpServer.js.map +1 -1
  31. package/dist/mcp/builtin/collections/authTools.d.ts.map +1 -1
  32. package/dist/mcp/builtin/collections/authTools.js +80 -56
  33. package/dist/mcp/builtin/collections/authTools.js.map +1 -1
  34. package/dist/mcp/builtin/collections/countTool.d.ts.map +1 -1
  35. package/dist/mcp/builtin/collections/countTool.js +10 -16
  36. package/dist/mcp/builtin/collections/countTool.js.map +1 -1
  37. package/dist/mcp/builtin/collections/countVersionsTool.d.ts.map +1 -1
  38. package/dist/mcp/builtin/collections/countVersionsTool.js +10 -15
  39. package/dist/mcp/builtin/collections/countVersionsTool.js.map +1 -1
  40. package/dist/mcp/builtin/collections/createTool.d.ts +1 -1
  41. package/dist/mcp/builtin/collections/createTool.d.ts.map +1 -1
  42. package/dist/mcp/builtin/collections/createTool.js +104 -54
  43. package/dist/mcp/builtin/collections/createTool.js.map +1 -1
  44. package/dist/mcp/builtin/collections/deleteTool.d.ts.map +1 -1
  45. package/dist/mcp/builtin/collections/deleteTool.js +45 -45
  46. package/dist/mcp/builtin/collections/deleteTool.js.map +1 -1
  47. package/dist/mcp/builtin/collections/duplicateTool.d.ts.map +1 -1
  48. package/dist/mcp/builtin/collections/duplicateTool.js +32 -39
  49. package/dist/mcp/builtin/collections/duplicateTool.js.map +1 -1
  50. package/dist/mcp/builtin/collections/fileInput.d.ts +28 -0
  51. package/dist/mcp/builtin/collections/fileInput.d.ts.map +1 -0
  52. package/dist/mcp/builtin/collections/fileInput.js +88 -0
  53. package/dist/mcp/builtin/collections/fileInput.js.map +1 -0
  54. package/dist/mcp/builtin/collections/findDistinctTool.d.ts.map +1 -1
  55. package/dist/mcp/builtin/collections/findDistinctTool.js +12 -28
  56. package/dist/mcp/builtin/collections/findDistinctTool.js.map +1 -1
  57. package/dist/mcp/builtin/collections/findTool.d.ts.map +1 -1
  58. package/dist/mcp/builtin/collections/findTool.js +30 -49
  59. package/dist/mcp/builtin/collections/findTool.js.map +1 -1
  60. package/dist/mcp/builtin/collections/findVersionByIDTool.d.ts.map +1 -1
  61. package/dist/mcp/builtin/collections/findVersionByIDTool.js +18 -28
  62. package/dist/mcp/builtin/collections/findVersionByIDTool.js.map +1 -1
  63. package/dist/mcp/builtin/collections/findVersionsTool.d.ts.map +1 -1
  64. package/dist/mcp/builtin/collections/findVersionsTool.js +17 -32
  65. package/dist/mcp/builtin/collections/findVersionsTool.js.map +1 -1
  66. package/dist/mcp/builtin/collections/getCollectionSchemaTool.d.ts.map +1 -1
  67. package/dist/mcp/builtin/collections/getCollectionSchemaTool.js +68 -12
  68. package/dist/mcp/builtin/collections/getCollectionSchemaTool.js.map +1 -1
  69. package/dist/mcp/builtin/collections/restoreVersionTool.d.ts.map +1 -1
  70. package/dist/mcp/builtin/collections/restoreVersionTool.js +15 -28
  71. package/dist/mcp/builtin/collections/restoreVersionTool.js.map +1 -1
  72. package/dist/mcp/builtin/collections/updateTool.d.ts.map +1 -1
  73. package/dist/mcp/builtin/collections/updateTool.js +67 -87
  74. package/dist/mcp/builtin/collections/updateTool.js.map +1 -1
  75. package/dist/mcp/builtin/collections/uploadInstructionsTool.d.ts +2 -0
  76. package/dist/mcp/builtin/collections/uploadInstructionsTool.d.ts.map +1 -0
  77. package/dist/mcp/builtin/collections/uploadInstructionsTool.js +55 -0
  78. package/dist/mcp/builtin/collections/uploadInstructionsTool.js.map +1 -0
  79. package/dist/mcp/builtin/formatEntityError.d.ts +16 -0
  80. package/dist/mcp/builtin/formatEntityError.d.ts.map +1 -0
  81. package/dist/mcp/builtin/formatEntityError.js +55 -0
  82. package/dist/mcp/builtin/formatEntityError.js.map +1 -0
  83. package/dist/mcp/builtin/getConfigInfoTool.d.ts.map +1 -1
  84. package/dist/mcp/builtin/getConfigInfoTool.js +5 -7
  85. package/dist/mcp/builtin/getConfigInfoTool.js.map +1 -1
  86. package/dist/mcp/builtin/globals/countVersionsTool.d.ts.map +1 -1
  87. package/dist/mcp/builtin/globals/countVersionsTool.js +10 -15
  88. package/dist/mcp/builtin/globals/countVersionsTool.js.map +1 -1
  89. package/dist/mcp/builtin/globals/findTool.d.ts.map +1 -1
  90. package/dist/mcp/builtin/globals/findTool.js +12 -18
  91. package/dist/mcp/builtin/globals/findTool.js.map +1 -1
  92. package/dist/mcp/builtin/globals/findVersionByIDTool.d.ts.map +1 -1
  93. package/dist/mcp/builtin/globals/findVersionByIDTool.js +14 -26
  94. package/dist/mcp/builtin/globals/findVersionByIDTool.js.map +1 -1
  95. package/dist/mcp/builtin/globals/findVersionsTool.d.ts.map +1 -1
  96. package/dist/mcp/builtin/globals/findVersionsTool.js +14 -31
  97. package/dist/mcp/builtin/globals/findVersionsTool.js.map +1 -1
  98. package/dist/mcp/builtin/globals/getGlobalSchemaTool.d.ts.map +1 -1
  99. package/dist/mcp/builtin/globals/getGlobalSchemaTool.js +46 -12
  100. package/dist/mcp/builtin/globals/getGlobalSchemaTool.js.map +1 -1
  101. package/dist/mcp/builtin/globals/restoreVersionTool.d.ts.map +1 -1
  102. package/dist/mcp/builtin/globals/restoreVersionTool.js +16 -24
  103. package/dist/mcp/builtin/globals/restoreVersionTool.js.map +1 -1
  104. package/dist/mcp/builtin/globals/updateTool.d.ts.map +1 -1
  105. package/dist/mcp/builtin/globals/updateTool.js +28 -37
  106. package/dist/mcp/builtin/globals/updateTool.js.map +1 -1
  107. package/dist/mcp/builtinTools.d.ts +6 -0
  108. package/dist/mcp/builtinTools.d.ts.map +1 -1
  109. package/dist/mcp/builtinTools.js +9 -3
  110. package/dist/mcp/builtinTools.js.map +1 -1
  111. package/dist/mcp/sanitizeMCPConfig.d.ts.map +1 -1
  112. package/dist/mcp/sanitizeMCPConfig.js +7 -1
  113. package/dist/mcp/sanitizeMCPConfig.js.map +1 -1
  114. package/dist/stdio.d.ts.map +1 -1
  115. package/dist/stdio.js +6 -4
  116. package/dist/stdio.js.map +1 -1
  117. package/dist/types.d.ts +143 -14
  118. package/dist/types.d.ts.map +1 -1
  119. package/dist/types.js +2 -4
  120. package/dist/types.js.map +1 -1
  121. package/dist/utils/camelCase.d.ts.map +1 -1
  122. package/dist/utils/resolveProjectRoot.d.ts.map +1 -1
  123. package/dist/utils/seal.d.ts +18 -0
  124. package/dist/utils/seal.d.ts.map +1 -0
  125. package/dist/utils/seal.js +27 -0
  126. package/dist/utils/seal.js.map +1 -0
  127. package/dist/utils/toStandardSchema.d.ts.map +1 -1
  128. package/dist/utils/toStandardSchema.js.map +1 -1
  129. package/package.json +23 -28
  130. package/src/endpoint/access.ts +27 -16
  131. package/src/endpoint/index.ts +41 -3
  132. package/src/endpoint/oauth.ts +100 -0
  133. package/src/endpoint/oauthLoginToken.ts +91 -0
  134. package/src/endpoint/oauthServer.ts +396 -0
  135. package/src/index.ts +40 -5
  136. package/src/mcp/buildMcpServer.ts +40 -30
  137. package/src/mcp/builtin/collections/authTools.ts +82 -71
  138. package/src/mcp/builtin/collections/countTool.ts +10 -23
  139. package/src/mcp/builtin/collections/countVersionsTool.ts +10 -23
  140. package/src/mcp/builtin/collections/createTool.ts +108 -77
  141. package/src/mcp/builtin/collections/deleteTool.ts +37 -66
  142. package/src/mcp/builtin/collections/duplicateTool.ts +37 -88
  143. package/src/mcp/builtin/collections/fileInput.spec.ts +93 -0
  144. package/src/mcp/builtin/collections/fileInput.ts +127 -0
  145. package/src/mcp/builtin/collections/findDistinctTool.ts +12 -64
  146. package/src/mcp/builtin/collections/findTool.ts +26 -109
  147. package/src/mcp/builtin/collections/findVersionByIDTool.ts +16 -60
  148. package/src/mcp/builtin/collections/findVersionsTool.ts +15 -87
  149. package/src/mcp/builtin/collections/getCollectionSchemaTool.ts +60 -15
  150. package/src/mcp/builtin/collections/restoreVersionTool.ts +16 -59
  151. package/src/mcp/builtin/collections/updateTool.ts +63 -101
  152. package/src/mcp/builtin/collections/uploadInstructionsTool.ts +64 -0
  153. package/src/mcp/builtin/formatEntityError.ts +77 -0
  154. package/src/mcp/builtin/getConfigInfoTool.ts +4 -5
  155. package/src/mcp/builtin/globals/countVersionsTool.ts +10 -22
  156. package/src/mcp/builtin/globals/findTool.ts +15 -54
  157. package/src/mcp/builtin/globals/findVersionByIDTool.ts +14 -54
  158. package/src/mcp/builtin/globals/findVersionsTool.ts +15 -94
  159. package/src/mcp/builtin/globals/getGlobalSchemaTool.ts +41 -9
  160. package/src/mcp/builtin/globals/restoreVersionTool.ts +17 -48
  161. package/src/mcp/builtin/globals/updateTool.ts +40 -63
  162. package/src/mcp/builtinTools.ts +9 -2
  163. package/src/mcp/sanitizeMCPConfig.ts +5 -1
  164. package/src/stdio.ts +4 -3
  165. package/src/types.ts +142 -14
  166. package/src/utils/seal.ts +46 -0
  167. package/src/utils/toStandardSchema.ts +1 -1
  168. package/dist/mcp/builtin/collections/formatCollectionError.d.ts +0 -9
  169. package/dist/mcp/builtin/collections/formatCollectionError.d.ts.map +0 -1
  170. package/dist/mcp/builtin/collections/formatCollectionError.js +0 -60
  171. package/dist/mcp/builtin/collections/formatCollectionError.js.map +0 -1
  172. package/dist/mcp/builtin/validateEntityData.d.ts +0 -14
  173. package/dist/mcp/builtin/validateEntityData.d.ts.map +0 -1
  174. package/dist/mcp/builtin/validateEntityData.js +0 -82
  175. package/dist/mcp/builtin/validateEntityData.js.map +0 -1
  176. package/dist/utils/getVirtualFieldNames.d.ts +0 -14
  177. package/dist/utils/getVirtualFieldNames.d.ts.map +0 -1
  178. package/dist/utils/getVirtualFieldNames.js +0 -35
  179. package/dist/utils/getVirtualFieldNames.js.map +0 -1
  180. package/dist/utils/localAPIDefaults.d.ts +0 -20
  181. package/dist/utils/localAPIDefaults.d.ts.map +0 -1
  182. package/dist/utils/localAPIDefaults.js +0 -19
  183. package/dist/utils/localAPIDefaults.js.map +0 -1
  184. package/dist/utils/schemaConversion/getEntityInputSchema.d.ts +0 -11
  185. package/dist/utils/schemaConversion/getEntityInputSchema.d.ts.map +0 -1
  186. package/dist/utils/schemaConversion/getEntityInputSchema.js +0 -32
  187. package/dist/utils/schemaConversion/getEntityInputSchema.js.map +0 -1
  188. package/dist/utils/schemaConversion/sanitizeEntitySchema.d.ts +0 -10
  189. package/dist/utils/schemaConversion/sanitizeEntitySchema.d.ts.map +0 -1
  190. package/dist/utils/schemaConversion/sanitizeEntitySchema.js +0 -384
  191. package/dist/utils/schemaConversion/sanitizeEntitySchema.js.map +0 -1
  192. package/dist/utils/schemaConversion/sanitizeEntitySchema.spec.js +0 -133
  193. package/dist/utils/schemaConversion/sanitizeEntitySchema.spec.js.map +0 -1
  194. package/dist/utils/transformPointDataToPayload.d.ts +0 -7
  195. package/dist/utils/transformPointDataToPayload.d.ts.map +0 -1
  196. package/dist/utils/transformPointDataToPayload.js +0 -28
  197. package/dist/utils/transformPointDataToPayload.js.map +0 -1
  198. package/dist/utils/whereSchema.d.ts +0 -9
  199. package/dist/utils/whereSchema.d.ts.map +0 -1
  200. package/dist/utils/whereSchema.js +0 -13
  201. package/dist/utils/whereSchema.js.map +0 -1
  202. package/src/mcp/builtin/collections/formatCollectionError.ts +0 -84
  203. package/src/mcp/builtin/validateEntityData.ts +0 -132
  204. package/src/utils/getVirtualFieldNames.ts +0 -53
  205. package/src/utils/localAPIDefaults.ts +0 -22
  206. package/src/utils/schemaConversion/getEntityInputSchema.ts +0 -62
  207. package/src/utils/schemaConversion/sanitizeEntitySchema.spec.ts +0 -96
  208. package/src/utils/schemaConversion/sanitizeEntitySchema.ts +0 -432
  209. package/src/utils/transformPointDataToPayload.ts +0 -40
  210. package/src/utils/whereSchema.ts +0 -24
@@ -3,6 +3,7 @@ import type { PayloadHandler, PayloadRequest } from 'payload'
3
3
  import {
4
4
  createMcpHandler,
5
5
  isLegacyRequest,
6
+ readRequestBody,
6
7
  WebStandardStreamableHTTPServerTransport,
7
8
  } from '@modelcontextprotocol/server'
8
9
  import { APIError } from 'payload'
@@ -10,6 +11,7 @@ import { APIError } from 'payload'
10
11
  import { buildMcpServer } from '../mcp/buildMcpServer.js'
11
12
  import { getPluginConfig } from '../utils/getPluginConfig.js'
12
13
  import { getAuthorizedMCP } from './access.js'
14
+ import { getMCPResource, oauthChallenge } from './oauth.js'
13
15
 
14
16
  export const mcpEndpoint: PayloadHandler = async (req) => {
15
17
  if (!req.url) {
@@ -17,6 +19,8 @@ export const mcpEndpoint: PayloadHandler = async (req) => {
17
19
  }
18
20
 
19
21
  req.payloadAPI = 'MCP' as const
22
+ // Lets auth strategies check that an OAuth access token was issued for this MCP server
23
+ req.context.mcp = { resource: getMCPResource({ req }) }
20
24
 
21
25
  const pluginConfig = getPluginConfig({ config: req.payload.config })
22
26
  const overrideAccessParam = new URL(req.url).searchParams.get('overrideAccess')
@@ -33,14 +37,22 @@ export const mcpEndpoint: PayloadHandler = async (req) => {
33
37
  }
34
38
 
35
39
  const authorizedMCP = await getAuthorizedMCP({ overrideAccess, req })
40
+
41
+ if (pluginConfig.oauth && !req.user) {
42
+ return oauthChallenge({ req })
43
+ }
44
+
45
+ const maxRequestBodySize = pluginConfig.mcp?.maxRequestBodySize
36
46
  // Payload augments the original web-standard Request in place.
37
47
  const mcpRequest = req as PayloadRequest & Request
48
+ const parsedBody = await parseRequestBody({ maxRequestBodySize, request: mcpRequest })
38
49
 
39
50
  // Keep the old JSON-only, stateless behavior because the SDK's 2025 fallback uses SSE.
40
- if (await isLegacyRequest(mcpRequest)) {
51
+ if (await isLegacyRequest(mcpRequest, parsedBody, { maxRequestBodySize })) {
41
52
  const server = buildMcpServer({ authorizedMCP, pluginConfig, req })
42
53
  const transport = new WebStandardStreamableHTTPServerTransport({
43
54
  enableJsonResponse: true,
55
+ maxRequestBodySize,
44
56
  sessionIdGenerator: undefined, // stateless mode
45
57
  })
46
58
  transport.onerror = (err) => {
@@ -49,7 +61,7 @@ export const mcpEndpoint: PayloadHandler = async (req) => {
49
61
 
50
62
  try {
51
63
  await server.connect(transport)
52
- return await transport.handleRequest(mcpRequest)
64
+ return await transport.handleRequest(mcpRequest, { parsedBody })
53
65
  } finally {
54
66
  await server.close().catch((err) => {
55
67
  req.payload.logger.error({ err, msg: 'Error closing MCP server' })
@@ -59,6 +71,7 @@ export const mcpEndpoint: PayloadHandler = async (req) => {
59
71
 
60
72
  const handler = createMcpHandler(() => buildMcpServer({ authorizedMCP, pluginConfig, req }), {
61
73
  legacy: 'reject',
74
+ maxRequestBodySize,
62
75
  // SDK subscriptions always use SSE, so disable them to keep every response JSON-only.
63
76
  maxSubscriptions: 0,
64
77
  onerror: (err) => {
@@ -68,10 +81,35 @@ export const mcpEndpoint: PayloadHandler = async (req) => {
68
81
  })
69
82
 
70
83
  try {
71
- return await handler.fetch(mcpRequest)
84
+ return await handler.fetch(mcpRequest, { parsedBody })
72
85
  } finally {
73
86
  await handler.close().catch((err) => {
74
87
  req.payload.logger.error({ err, msg: 'Error closing modern MCP handler' })
75
88
  })
76
89
  }
77
90
  }
91
+
92
+ /**
93
+ * Parses a POST body once so the era check and the SDK handler can share it. The SDK
94
+ * skips its size limit for a pre-parsed body, so this reads with the same limit. It reads
95
+ * a clone and returns `undefined` for any body the SDK should reject (too large, unreadable,
96
+ * or not JSON), leaving the original request for the SDK to read and answer.
97
+ */
98
+ const parseRequestBody = async ({
99
+ maxRequestBodySize,
100
+ request,
101
+ }: {
102
+ maxRequestBodySize?: number
103
+ request: Request
104
+ }): Promise<unknown> => {
105
+ if (request.method.toUpperCase() !== 'POST') {
106
+ return undefined
107
+ }
108
+
109
+ try {
110
+ const body = await readRequestBody(request.clone(), maxRequestBodySize)
111
+ return body.tooLarge ? undefined : JSON.parse(body.text)
112
+ } catch {
113
+ return undefined
114
+ }
115
+ }
@@ -0,0 +1,100 @@
1
+ import type { OAuthProtectedResourceMetadata } from '@modelcontextprotocol/server'
2
+ import type { PayloadHandler, PayloadRequest, SanitizedConfig } from 'payload'
3
+
4
+ import {
5
+ bearerAuthChallengeResponse,
6
+ OAuthError,
7
+ OAuthErrorCode,
8
+ } from '@modelcontextprotocol/server'
9
+ import { createPayloadRequest, getPayload } from 'payload'
10
+
11
+ import { getPluginConfig } from '../utils/getPluginConfig.js'
12
+
13
+ /**
14
+ * Serves the OAuth protected resource metadata (RFC 9728) at `/api/mcp/oauth-protected-resource`.
15
+ * The OAuth challenge links here, so MCP clients find the authorization server without setup.
16
+ */
17
+ export const oauthProtectedResourceEndpoint: PayloadHandler = (req) => getMetadataResponse({ req })
18
+
19
+ /**
20
+ * Serves the same metadata for clients that ignore the challenge's link and only look at
21
+ * `/.well-known/oauth-protected-resource`. Mount it at the site root, e.g. in Next.js at
22
+ * `app/.well-known/oauth-protected-resource/[[...path]]/route.ts`:
23
+ *
24
+ * ```ts
25
+ * import config from '@payload-config'
26
+ * import { oauthProtectedResourceHandler } from '@payloadcms/plugin-mcp'
27
+ *
28
+ * export const GET = oauthProtectedResourceHandler(config)
29
+ * ```
30
+ */
31
+ export const oauthProtectedResourceHandler =
32
+ (config: Promise<SanitizedConfig> | SanitizedConfig) =>
33
+ async (request: Request): Promise<Response> =>
34
+ getMetadataResponse({
35
+ req: await createPayloadRequest({ payload: await getPayload({ config }), req: request }),
36
+ })
37
+
38
+ /**
39
+ * Answers an unauthenticated MCP request with a challenge linking to the protected resource
40
+ * metadata, which starts the client's OAuth flow.
41
+ */
42
+ export const oauthChallenge = ({ req }: { req: PayloadRequest }): Response => {
43
+ const { oauth } = getPluginConfig({ config: req.payload.config })
44
+ const response = bearerAuthChallengeResponse(
45
+ new OAuthError(OAuthErrorCode.InvalidToken, req.t('error:unauthorized')),
46
+ {
47
+ requiredScopes: oauth?.type === 'external' ? oauth.scopes : undefined,
48
+ resourceMetadataUrl: `${getMCPResource({ req })}/oauth-protected-resource`,
49
+ },
50
+ )
51
+
52
+ // Lets browser-based MCP clients read the challenge, when Payload's `cors` setting allows them
53
+ response.headers.set('Access-Control-Expose-Headers', 'WWW-Authenticate')
54
+
55
+ return response
56
+ }
57
+
58
+ /**
59
+ * The MCP endpoint's address, as advertised in the metadata's `resource`. The metadata link and
60
+ * the built-in authorization server's issuer are based on it. Clients send it when they sign in,
61
+ * and authorization servers that support it put it in the access token's audience.
62
+ */
63
+ export const getMCPResource = ({ req }: { req: PayloadRequest }): string => {
64
+ const { config } = req.payload
65
+ const resource = getPluginConfig({ config }).oauth?.resource
66
+
67
+ if (typeof resource === 'function') {
68
+ return resource({ req })
69
+ }
70
+
71
+ return resource ?? new URL(`${config.routes.api}/mcp`, config.serverURL || req.url).href
72
+ }
73
+
74
+ const getMetadataResponse = async ({ req }: { req: PayloadRequest }): Promise<Response> => {
75
+ const { config } = req.payload
76
+ const { oauth } = getPluginConfig({ config })
77
+
78
+ if (!oauth) {
79
+ return new Response(null, { status: 404 })
80
+ }
81
+
82
+ const resource = getMCPResource({ req })
83
+
84
+ return Response.json(
85
+ {
86
+ authorization_servers:
87
+ oauth.type === 'builtin'
88
+ ? [`${resource}/oauth`]
89
+ : typeof oauth.authorizationServers === 'function'
90
+ ? await oauth.authorizationServers({ req })
91
+ : oauth.authorizationServers,
92
+ bearer_methods_supported: ['header'],
93
+ resource,
94
+ scopes_supported: oauth.type === 'external' ? oauth.scopes : undefined,
95
+ } satisfies OAuthProtectedResourceMetadata,
96
+ // Public document, readable by browser-based MCP clients on any origin. Not cached, since its
97
+ // URLs can depend on the request.
98
+ { headers: { 'Access-Control-Allow-Origin': '*', 'Cache-Control': 'no-store' } },
99
+ )
100
+ }
@@ -0,0 +1,91 @@
1
+ import type { PayloadRequest } from 'payload'
2
+
3
+ import { APIError, createAuthToken, executeAuthStrategies, redeemRefreshToken } from 'payload'
4
+
5
+ import type { MCPOAuthTokens } from '../types.js'
6
+
7
+ import { seal, unseal } from '../utils/seal.js'
8
+
9
+ /**
10
+ * The default `issueToken`: a Payload login token, sealed so it only works for MCP, where
11
+ * `authenticateLoginToken` unseals it. Otherwise an MCP client could use it as the user's admin
12
+ * panel login. When the collection uses sessions, the client also gets a refresh token.
13
+ */
14
+ export const issueLoginToken = async ({
15
+ req,
16
+ }: {
17
+ req: PayloadRequest
18
+ }): Promise<MCPOAuthTokens> => {
19
+ const collectionConfig = req.payload.collections[req.user!.collection]!.config
20
+
21
+ if (collectionConfig.auth.disableLocalStrategy) {
22
+ throw new APIError(
23
+ `MCP clients can't get Payload login tokens for the "${collectionConfig.slug}" collection because its local strategy is disabled. Pass oauth.issueToken to the MCP plugin.`,
24
+ )
25
+ }
26
+
27
+ // The full document, like the one a password login starts its session on
28
+ const user = (await req.payload.db.findOne<NonNullable<PayloadRequest['user']>>({
29
+ collection: collectionConfig.slug,
30
+ req,
31
+ where: { id: { equals: req.user!.id } },
32
+ }))!
33
+
34
+ const { refreshToken, token } = await createAuthToken({
35
+ collectionConfig,
36
+ email: user.email!,
37
+ req,
38
+ shouldCreateRefreshToken: true,
39
+ user,
40
+ })
41
+
42
+ return {
43
+ accessToken: sealLoginToken({ req, token }),
44
+ expiresIn: collectionConfig.auth.tokenExpiration,
45
+ refreshToken,
46
+ }
47
+ }
48
+
49
+ /** The default `refreshToken`. Payload logs out the session when a refresh token is reused. */
50
+ export const refreshLoginToken = async ({
51
+ refreshToken,
52
+ req,
53
+ }: {
54
+ refreshToken: string
55
+ req: PayloadRequest
56
+ }): Promise<MCPOAuthTokens | null> => {
57
+ const refreshed = await redeemRefreshToken({ refreshToken, req })
58
+
59
+ return (
60
+ refreshed && {
61
+ accessToken: sealLoginToken({ req, token: refreshed.token }),
62
+ expiresIn: refreshed.collectionConfig.auth.tokenExpiration,
63
+ refreshToken: refreshed.refreshToken,
64
+ }
65
+ )
66
+ }
67
+
68
+ /** Finds the user of an MCP request's access token from `issueLoginToken`. */
69
+ export const authenticateLoginToken = async ({
70
+ req,
71
+ token,
72
+ }: {
73
+ req: PayloadRequest
74
+ token: string
75
+ }): Promise<PayloadRequest['user']> => {
76
+ const loginToken = unseal<{ token: string }>({ type: 'access', req, value: token })
77
+
78
+ if (!loginToken) {
79
+ return null
80
+ }
81
+
82
+ const headers = new Headers({
83
+ Authorization: `JWT ${loginToken.token}`,
84
+ DisableAutologin: 'true',
85
+ })
86
+
87
+ return (await executeAuthStrategies({ headers, payload: req.payload, req })).user
88
+ }
89
+
90
+ const sealLoginToken = ({ req, token }: { req: PayloadRequest; token: string }): string =>
91
+ seal({ type: 'access', data: { token }, req })
@@ -0,0 +1,396 @@
1
+ import type {
2
+ OAuthClientInformationFull,
3
+ OAuthTokens,
4
+ OpenIdProviderDiscoveryMetadata,
5
+ } from '@modelcontextprotocol/server'
6
+ import type { Endpoint, PayloadHandler, PayloadRequest } from 'payload'
7
+
8
+ import { OAuthErrorCode } from '@modelcontextprotocol/server'
9
+ import { createHash } from 'crypto'
10
+ import { formatAdminURL } from 'payload/shared'
11
+
12
+ import type { MCPBuiltinOAuthConfig, MCPOAuthTokens } from '../types.js'
13
+
14
+ import { getPluginConfig } from '../utils/getPluginConfig.js'
15
+ import { seal, unseal } from '../utils/seal.js'
16
+ import { getMCPResource } from './oauth.js'
17
+ import { issueLoginToken, refreshLoginToken } from './oauthLoginToken.js'
18
+
19
+ type Client = { name: string; redirectURIs: string[] }
20
+
21
+ type Consent = {
22
+ clientID: string
23
+ codeChallenge: string
24
+ collection: string
25
+ redirectURI: string
26
+ state: null | string
27
+ userID: number | string
28
+ }
29
+
30
+ type Code = {
31
+ clientID: string
32
+ codeChallenge: string
33
+ redirectURI: string
34
+ tokens: MCPOAuthTokens
35
+ }
36
+
37
+ type RefreshToken = {
38
+ clientID: string
39
+ refreshToken: string
40
+ }
41
+
42
+ /**
43
+ * Turns Payload into the OAuth authorization server for MCP clients when `oauth.type` is
44
+ * `'builtin'`. Clients register, the user allows them after logging in to the admin panel, and
45
+ * the client receives the tokens `issueToken` creates.
46
+ *
47
+ * Clients, consent forms, authorization codes, and refresh tokens are encrypted and handed to the
48
+ * client instead of being stored. Only the default tokens write to the database, to the user's
49
+ * login sessions.
50
+ */
51
+ export const oauthServerEndpoints: Endpoint[] = [
52
+ {
53
+ disableAuth: true,
54
+ handler: (req) => withIssuer(req, (issuer) => metadataResponse(issuer)),
55
+ method: 'get',
56
+ // OpenID discovery is the only metadata location MCP clients check below the issuer's path,
57
+ // which lets this work under /api without a route at the site root
58
+ path: '/mcp/oauth/.well-known/openid-configuration',
59
+ },
60
+ {
61
+ disableAuth: true,
62
+ handler: (req) => withIssuer(req, () => Response.json({ keys: [] })),
63
+ method: 'get',
64
+ path: '/mcp/oauth/jwks',
65
+ },
66
+ {
67
+ disableAuth: true,
68
+ handler: (req) => withIssuer(req, () => register(req)),
69
+ method: 'post',
70
+ path: '/mcp/oauth/register',
71
+ },
72
+ {
73
+ handler: (req) => withIssuer(req, () => authorize(req)),
74
+ method: 'get',
75
+ path: '/mcp/oauth/authorize',
76
+ },
77
+ {
78
+ handler: (req) => withIssuer(req, () => approve(req)),
79
+ method: 'post',
80
+ path: '/mcp/oauth/authorize',
81
+ },
82
+ {
83
+ disableAuth: true,
84
+ handler: (req) => withIssuer(req, () => token(req)),
85
+ method: 'post',
86
+ path: '/mcp/oauth/token',
87
+ },
88
+ ]
89
+
90
+ /** The authorization server URL, or `undefined` when Payload isn't the authorization server. */
91
+ const getIssuer = (req: PayloadRequest): string | undefined =>
92
+ getPluginConfig({ config: req.payload.config }).oauth?.type === 'builtin'
93
+ ? `${getMCPResource({ req })}/oauth`
94
+ : undefined
95
+
96
+ const withIssuer = (
97
+ req: PayloadRequest,
98
+ handler: (issuer: string) => Promise<Response> | Response,
99
+ ): Promise<Response> | Response => {
100
+ const issuer = getIssuer(req)
101
+ return issuer ? handler(issuer) : new Response(null, { status: 404 })
102
+ }
103
+
104
+ /**
105
+ * The user logged in to this browser, who can allow MCP clients. Tokens and API keys in the
106
+ * `Authorization` header can't, or an MCP client could use its access token to approve itself a
107
+ * new, separate login.
108
+ */
109
+ const getBrowserUser = (req: PayloadRequest): PayloadRequest['user'] =>
110
+ req.headers.has('Authorization') ? null : req.user
111
+
112
+ const metadataResponse = (issuer: string): Response =>
113
+ Response.json(
114
+ {
115
+ authorization_endpoint: `${issuer}/authorize`,
116
+ code_challenge_methods_supported: ['S256'],
117
+ grant_types_supported: ['authorization_code', 'refresh_token'],
118
+ // Required by OpenID discovery. No ID tokens are issued.
119
+ id_token_signing_alg_values_supported: ['RS256'],
120
+ issuer,
121
+ jwks_uri: `${issuer}/jwks`,
122
+ registration_endpoint: `${issuer}/register`,
123
+ response_types_supported: ['code'],
124
+ subject_types_supported: ['public'],
125
+ token_endpoint: `${issuer}/token`,
126
+ token_endpoint_auth_methods_supported: ['none'],
127
+ } satisfies OpenIdProviderDiscoveryMetadata,
128
+ // Not cached, since without `serverURL` its URLs come from the request
129
+ { headers: { 'Access-Control-Allow-Origin': '*', 'Cache-Control': 'no-store' } },
130
+ )
131
+
132
+ const register: PayloadHandler = async (req) => {
133
+ const { client_name, redirect_uris } = await req.json!().catch(() => ({}))
134
+
135
+ if (
136
+ !Array.isArray(redirect_uris) ||
137
+ !redirect_uris.length ||
138
+ !redirect_uris.every(
139
+ (uri) => typeof uri === 'string' && URL.canParse(uri) && !uri.includes('#'),
140
+ )
141
+ ) {
142
+ return Response.json({ error: OAuthErrorCode.InvalidRedirectUri }, { status: 400 })
143
+ }
144
+
145
+ const client: Client = {
146
+ name: typeof client_name === 'string' ? client_name : 'An MCP client',
147
+ redirectURIs: redirect_uris,
148
+ }
149
+
150
+ return Response.json(
151
+ {
152
+ client_id: seal({ type: 'client', data: client, req }),
153
+ client_name: client.name,
154
+ grant_types: ['authorization_code', 'refresh_token'],
155
+ redirect_uris: client.redirectURIs,
156
+ response_types: ['code'],
157
+ token_endpoint_auth_method: 'none',
158
+ } satisfies OAuthClientInformationFull,
159
+ { status: 201 },
160
+ )
161
+ }
162
+
163
+ const authorize: PayloadHandler = (req) => {
164
+ const url = new URL(req.url!)
165
+ const params = url.searchParams
166
+ const clientID = params.get('client_id')
167
+ const client = unseal<Client>({ type: 'client', req, value: clientID })
168
+ const redirectURI = params.get('redirect_uri')
169
+
170
+ // Never redirect to an address the client didn't register
171
+ if (!client || !redirectURI || !client.redirectURIs.includes(redirectURI)) {
172
+ return page({
173
+ content: '<p>Start the sign-in again from your MCP client.</p>',
174
+ status: 400,
175
+ title: 'This sign-in link is invalid',
176
+ })
177
+ }
178
+
179
+ const state = params.get('state')
180
+ const codeChallenge = params.get('code_challenge')
181
+
182
+ if (
183
+ params.get('response_type') !== 'code' ||
184
+ params.get('code_challenge_method') !== 'S256' ||
185
+ !codeChallenge
186
+ ) {
187
+ return redirect({ params: { error: OAuthErrorCode.InvalidRequest, state }, redirectURI })
188
+ }
189
+
190
+ const user = getBrowserUser(req)
191
+
192
+ if (!user) {
193
+ const loginURL = formatAdminURL({ adminRoute: req.payload.config.routes.admin, path: '/login' })
194
+
195
+ return new Response(null, {
196
+ headers: {
197
+ Location: `${loginURL}?redirect=${encodeURIComponent(url.pathname + url.search)}`,
198
+ },
199
+ status: 302,
200
+ })
201
+ }
202
+
203
+ const consent: Consent = {
204
+ clientID: clientID!,
205
+ codeChallenge,
206
+ collection: user.collection,
207
+ redirectURI,
208
+ state,
209
+ userID: user.id,
210
+ }
211
+
212
+ return page({
213
+ content: `<p>It will be able to use this app's MCP tools as ${escapeHTML(String(user.email ?? user.id))}, and you will return to ${escapeHTML(new URL(redirectURI).host || redirectURI)}.</p>
214
+ <form method="post">
215
+ <input name="consent" type="hidden" value="${seal({ type: 'consent', data: consent, expiresIn: 20 * 60 * 60, req })}">
216
+ <button name="decision" type="submit" value="allow">Allow</button>
217
+ <button name="decision" type="submit" value="deny">Deny</button>
218
+ </form>`,
219
+ status: 200,
220
+ title: `Allow ${client.name} to use your account?`,
221
+ })
222
+ }
223
+
224
+ const approve: PayloadHandler = async (req) => {
225
+ const form = new URLSearchParams(await req.text!())
226
+ const consent = unseal<Consent>({ type: 'consent', req, value: form.get('consent') })
227
+ const user = getBrowserUser(req)
228
+
229
+ // The form is only valid for the user it was shown to
230
+ if (!consent || user?.id !== consent.userID || user.collection !== consent.collection) {
231
+ return page({
232
+ content: '<p>Start the sign-in again from your MCP client.</p>',
233
+ status: 400,
234
+ title: 'This sign-in request expired',
235
+ })
236
+ }
237
+
238
+ const { clientID, codeChallenge, redirectURI, state } = consent
239
+
240
+ if (form.get('decision') !== 'allow') {
241
+ return redirect({ params: { error: OAuthErrorCode.AccessDenied, state }, redirectURI })
242
+ }
243
+
244
+ const code: Code = {
245
+ clientID,
246
+ codeChallenge,
247
+ redirectURI,
248
+ tokens: await getTokenHooks(req).issueToken({ req }),
249
+ }
250
+
251
+ return redirect({
252
+ params: { code: seal({ type: 'code', data: code, expiresIn: 60, req }), state },
253
+ redirectURI,
254
+ })
255
+ }
256
+
257
+ const token: PayloadHandler = async (req) => {
258
+ const form = new URLSearchParams(await req.text!())
259
+ const clientID = form.get('client_id')
260
+ const tokens =
261
+ clientID &&
262
+ (form.get('grant_type') === 'refresh_token'
263
+ ? await refresh({ clientID, form, req })
264
+ : redeemCode({ clientID, form, req }))
265
+
266
+ if (!clientID || !tokens) {
267
+ return Response.json({ error: OAuthErrorCode.InvalidGrant }, { status: 400 })
268
+ }
269
+
270
+ return Response.json(
271
+ {
272
+ access_token: tokens.accessToken,
273
+ expires_in: tokens.expiresIn,
274
+ refresh_token:
275
+ tokens.refreshToken &&
276
+ seal({
277
+ type: 'refresh',
278
+ data: { clientID, refreshToken: tokens.refreshToken } satisfies RefreshToken,
279
+ req,
280
+ }),
281
+ token_type: 'Bearer',
282
+ } satisfies OAuthTokens,
283
+ { headers: { 'Cache-Control': 'no-store' } },
284
+ )
285
+ }
286
+
287
+ const redeemCode = ({
288
+ clientID,
289
+ form,
290
+ req,
291
+ }: {
292
+ clientID: string
293
+ form: URLSearchParams
294
+ req: PayloadRequest
295
+ }): MCPOAuthTokens | undefined => {
296
+ const code = unseal<Code>({ type: 'code', req, value: form.get('code') })
297
+
298
+ if (
299
+ form.get('grant_type') === 'authorization_code' &&
300
+ code?.clientID === clientID &&
301
+ code.redirectURI === form.get('redirect_uri') &&
302
+ // PKCE: only the client that started the sign-in knows the verifier
303
+ createHash('sha256')
304
+ .update(form.get('code_verifier') ?? '')
305
+ .digest('base64url') === code.codeChallenge
306
+ ) {
307
+ return code.tokens
308
+ }
309
+ }
310
+
311
+ const refresh = async ({
312
+ clientID,
313
+ form,
314
+ req,
315
+ }: {
316
+ clientID: string
317
+ form: URLSearchParams
318
+ req: PayloadRequest
319
+ }): Promise<MCPOAuthTokens | null | undefined> => {
320
+ const refreshToken = unseal<RefreshToken>({
321
+ type: 'refresh',
322
+ req,
323
+ value: form.get('refresh_token'),
324
+ })
325
+
326
+ // Only the client a refresh token was issued to can use it
327
+ if (refreshToken?.clientID === clientID) {
328
+ return await getTokenHooks(req).refreshToken?.({
329
+ refreshToken: refreshToken.refreshToken,
330
+ req,
331
+ })
332
+ }
333
+ }
334
+
335
+ /** `issueToken` and `refreshToken`, or the defaults for Payload login tokens. */
336
+ const getTokenHooks = (req: PayloadRequest) => {
337
+ const oauth = getPluginConfig({ config: req.payload.config }).oauth as MCPBuiltinOAuthConfig
338
+
339
+ return oauth.issueToken
340
+ ? { issueToken: oauth.issueToken, refreshToken: oauth.refreshToken }
341
+ : { issueToken: issueLoginToken, refreshToken: refreshLoginToken }
342
+ }
343
+
344
+ const redirect = ({
345
+ params,
346
+ redirectURI,
347
+ }: {
348
+ params: Record<string, null | string>
349
+ redirectURI: string
350
+ }): Response => {
351
+ const location = new URL(redirectURI)
352
+
353
+ for (const [key, value] of Object.entries(params)) {
354
+ if (value) {
355
+ location.searchParams.set(key, value)
356
+ }
357
+ }
358
+
359
+ return new Response(null, { headers: { Location: location.href }, status: 302 })
360
+ }
361
+
362
+ const page = ({
363
+ content,
364
+ status,
365
+ title,
366
+ }: {
367
+ content: string
368
+ status: number
369
+ title: string
370
+ }): Response =>
371
+ new Response(
372
+ `<!doctype html>
373
+ <html lang="en">
374
+ <head>
375
+ <meta charset="utf-8">
376
+ <meta name="viewport" content="width=device-width, initial-scale=1">
377
+ <title>${escapeHTML(title)}</title>
378
+ <style>
379
+ body { font-family: system-ui, sans-serif; margin: 4rem auto; max-width: 32rem; overflow-wrap: anywhere; padding: 0 1rem }
380
+ button { font: inherit; margin-inline-end: 0.5rem; padding: 0.5rem 1rem }
381
+ </style>
382
+ </head>
383
+ <body><h1>${escapeHTML(title)}</h1>${content}</body>
384
+ </html>`,
385
+ {
386
+ headers: {
387
+ // Stop other sites from framing the page to trick users into clicking Allow
388
+ 'Content-Security-Policy': "frame-ancestors 'none'",
389
+ 'Content-Type': 'text/html; charset=utf-8',
390
+ },
391
+ status,
392
+ },
393
+ )
394
+
395
+ const escapeHTML = (value: string): string =>
396
+ value.replace(/[&<>"']/g, (character) => `&#${character.charCodeAt(0)};`)