@payloadcms/plugin-mcp 4.0.0-internal.e16cf59 → 4.0.0-internal.e55ccef

package/src/types.ts

@@ -1,542 +1,360 @@
 import type {
-  CollectionConfig,
+  CallToolResult,
+  ContentBlock,
+  JsonSchemaType,
+  McpServer,
+  ResourceTemplate,
+  ServerContext,
+  StandardSchemaWithJSON,
+  ToolAnnotations,
+} from '@modelcontextprotocol/server'
+import type {
+  AuthCollectionSlug,
   CollectionSlug,
   GlobalSlug,
+  MaybePromise,
   PayloadRequest,
-  TypedUser,
+  SanitizedPermissions,
 } from 'payload'
-import type { z } from 'zod'
 
-import { type ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { GetAuthorizedMCPArgs } from './endpoint/access.js'
+import type {
+  MCPCollectionAuthToolName,
+  MCPCollectionBuiltinName,
+  MCPGlobalBuiltinName,
+} from './mcp/builtinTools.js'
 
-export type MCPPluginConfig = {
-  /**
-   * Set the collections that should be available as resources via MCP.
-   */
-  collections?: Partial<
-    Record<
-      CollectionSlug,
-      {
-        /**
-         * Set the description of the collection. This is used by MCP clients to determine when to use the collecton as a resource.
-         */
-        description?: string
-        /**
-         * Set the enabled capabilities of the collection. Admins can then allow or disallow the use of the capability by MCP clients.
-         */
-        enabled:
-          | {
-              create?: boolean
-              delete?: boolean
-              find?: boolean
-              update?: boolean
-            }
-          | boolean
-
-        /**
-         * Override the response generated by the MCP client. This allows you to modify the response that is sent to the MCP client. This is useful for adding additional data to the response, data normalization, or verifying data.
-         */
-        overrideResponse?: (
-          response: {
-            content: Array<{
-              text: string
-              type: string
-            }>
-          },
-          doc: Record<string, unknown>,
-          req: PayloadRequest,
-        ) => {
-          content: Array<{
-            text: string
-            type: string
-          }>
-        }
-      }
-    >
-  >
-  /**
-   * Disable the MCP plugin.
-   */
-  disabled?: boolean
-  /**
-   * Experimental features
-   * **These features are for experimental purposes -- They are Disabled in Production by Default**
-   */
-  experimental?: {
-    /**
-     * These are MCP tools that can be used by a client to modify Payload.
-     */
-    tools: {
-      /**
-       * **Experimental** -- Auth MCP tools allow a client to change authentication priviliages for users. This is for developing ideas that help Admins with authentication tasks.
-       */
-      auth?: {
-        /**
-         * Enable the auth MCP tools. This allows Admins to enable or disable the auth capabilities.
-         * @default false
-         */
-        enabled: boolean
-      }
-      /**
-       * **Experimental** -- Collection MCP tools allow for the creation, modification, and deletion of Payload collections. This is for developing ideas that help Developers with collection tasks.
-       */
-      collections?: {
-        /**
-         * Set the directory path to the collections directory. This can be a directory outside of your default directory, or another Payload project.
-         */
-        collectionsDirPath: string
-        /**
-         * Enable the collection MCP tools. This allows Admins to enable or disable the Collection modification capabilities.
-         * @default false
-         */
-        enabled: boolean
-      }
-      /**
-       * **Experimental** -- Config MCP tools allow for the modification of a Payload Config. This is for developing ideas that help Developers with config tasks.
-       */
-      config?: {
-        /**
-         * Set the directory path to the config directory. This can be a directory outside of your default directory, or another Payload project.
-         */
-        configFilePath: string
-        /**
-         * Enable the config MCP tools. This allows Admins to enable or disable the Payload Config modification capabilities.
-         * @default false
-         */
-        enabled: boolean
-      }
-      /**
-       * **Experimental** -- Jobs MCP tools allow for the modification of Payload jobs. This is for developing ideas that help Developers with job tasks.
-       */
-      jobs?: {
-        /**
-         * Enable the jobs MCP tools. This allows Admins to enable or disable the Job modification capabilities.
-         * @default false
-         */
-        enabled: boolean
-        /**
-         * Set the directory path to the jobs directory. This can be a directory outside of your default directory, or another Payload project.
-         */
-        jobsDirPath: string
-      }
-    }
-  }
-  /**
-   * Set the globals that should be available as resources via MCP.
-   * Globals are singleton configuration objects (e.g., site settings, navigation).
-   * Note: Globals only support find and update operations.
-   */
-  globals?: Partial<
-    Record<
-      GlobalSlug,
-      {
-        /**
-         * Set the description of the global. This is used by MCP clients to determine when to use the global as a resource.
-         */
-        description?: string
-        /**
-         * Set the enabled capabilities of the global. Admins can then allow or disallow the use of the capability by MCP clients.
-         * Note: Globals only support find and update operations as they are singletons.
-         */
-        enabled:
-          | {
-              find?: boolean
-              update?: boolean
-            }
-          | boolean
-
-        /**
-         * Override the response generated by the MCP client. This allows you to modify the response that is sent to the MCP client. This is useful for adding additional data to the response, data normalization, or verifying data.
-         */
-        overrideResponse?: (
-          response: {
-            content: Array<{
-              text: string
-              type: string
-            }>
-          },
-          doc: Record<string, unknown>,
-          req: PayloadRequest,
-        ) => {
-          content: Array<{
-            text: string
-            type: string
-          }>
-        }
-      }
-    >
-  >
-  /**
-   * MCP Server options.
-   */
-  mcp?: {
-    handlerOptions?: MCPHandlerOptions
-    /**
-     * Add custom MCP Prompts.
-     */
-    prompts?: {
-      /**
-       * Set the args schema of the prompt. This is the args schema that will be passed to the prompt. This is used by MCP clients to determine the arguments that will be passed to the prompt.
-       */
-      argsSchema: z.ZodRawShape
-      /**
-       * Set the description of the prompt. This is used by MCP clients to determine when to use the prompt.
-       */
-      description: string
-      /**
-       * Set the handler of the prompt. This is the function that will be called when the prompt is used.
-       */
-      handler: (
-        args: Record<string, unknown>,
-        req: PayloadRequest,
-        _extra: unknown,
-      ) =>
-        | {
-            messages: Array<{
-              content: {
-                text: string
-                type: 'text'
-              }
-              role: 'assistant' | 'user'
-            }>
-          }
-        | Promise<{
-            messages: Array<{
-              content: {
-                text: string
-                type: 'text'
-              }
-              role: 'assistant' | 'user'
-            }>
-          }>
-      /**
-       * Set the function name of the prompt.
-       */
-      name: string
-      /**
-       * Set the title of the prompt. LLMs will interperate the title to determine when to use the prompt.
-       */
-      title: string
-    }[]
+export type { MCPCollectionAuthToolName, MCPCollectionBuiltinName, MCPGlobalBuiltinName }
 
-    /**
-     * Add custom MCP Resource.
-     */
-    resources?: {
-      /**
-       * Set the description of the resource. This is used by MCP clients to determine when to use the resource.
-       * example: 'Data is a resource that contains special data.'
-       */
-      description: string
-      /**
-       * Set the handler of the resource. This is the function that will be called when the resource is used.
-       * The handler can have either 3 arguments (when no args are passed) or 4 arguments (when args are passed).
-       */
-      handler: (...args: any[]) =>
-        | {
-            contents: Array<{
-              text: string
-              uri: string
-            }>
-          }
-        | Promise<{
-            contents: Array<{
-              text: string
-              uri: string
-            }>
-          }>
-      /**
-       * Set the mime type of the resource.
-       * example: 'text/plain'
-       */
-      mimeType: string
-      /**
-       * Set the function name of the resource.
-       * example: 'data'
-       */
-      name: string
-      /**
-       * Set the title of the resource. LLMs will interperate the title to determine when to use the resource.
-       * example: 'Data'
-       */
-      title: string
-      /**
-       * Set the uri of the resource.
-       * example: 'data://app'
-       */
-      uri: ResourceTemplate | string
-    }[]
-    serverOptions?: MCPServerOptions
-    /**
-     * Add custom MCP Tools.
-     */
-    tools?: {
-      /**
-       * Set the description of the tool. This is used by MCP clients to determine when to use the tool.
-       */
-      description: string
-      /**
-       * Set the handler of the tool. This is the function that will be called when the tool is used.
-       */
-      handler: (
-        args: Record<string, unknown>,
-        req: PayloadRequest,
-        _extra: unknown,
-      ) =>
-        | {
-            content: Array<{
-              text: string
-              type: 'text'
-            }>
-            role?: string
-          }
-        | Promise<{
-            content: Array<{
-              text: string
-              type: 'text'
-            }>
-            role?: string
-          }>
-      /**
-       * Set the name of the tool. This is the name that will be used to identify the tool. LLMs will interperate the name to determine when to use the tool.
-       */
-      name: string
-      /**
-       * Set the parameters of the tool. This is the parameters that will be passed to the tool.
-       */
-      parameters: z.ZodRawShape
-    }[]
-  }
+/** Re-exported from `@modelcontextprotocol/server` — common MCP types used in plugin config. */
+export type { JsonSchemaType, StandardSchemaWithJSON, ToolAnnotations }
 
-  /**
-   * Override the API key collection.
-   * This allows you to add fields to the API key collection or modify the collection in any way you want.
-   * @param collection - The API key collection.
-   * @returns The modified API key collection.
-   */
-  overrideApiKeyCollection?: (collection: CollectionConfig) => CollectionConfig
+/**
+ * What a tool's `input` (or a prompt's `argsSchema`) can be — either a raw
+ * JSON Schema 2020-12 literal, or a Standard Schema instance (Zod, Valibot, …).
+ * Raw schemas may omit `$schema`; when present it must declare the 2020-12 dialect.
+ */
+export type ToolInputSchema = JsonSchemaType | StandardSchemaWithJSON
 
+export type MCPToolResponse = {
+  content: ContentBlock[]
   /**
-   * Override the authentication method.
-   * This allows you to use a custom authentication method instead of the default API key authentication.
-   * @param req - The request object.
-   * @returns The MCP access settings.
+   * If available, return the document fetched within the
+   * mcp tool. This is threaded as an additional argument to
+   * overrideResponse functions and stripped before going on the wire.
    */
-  overrideAuth?: (
-    req: PayloadRequest,
-    getDefaultMcpAccessSettings: (overrideApiKey?: null | string) => Promise<MCPAccessSettings>,
-  ) => MCPAccessSettings | Promise<MCPAccessSettings>
+  doc?: Record<string, unknown>
+} & Pick<CallToolResult, '_meta' | 'isError' | 'structuredContent'>
 
-  /**
-   * Set the users collection that API keys should be associated with.
-   */
-  userCollection?: CollectionSlug
-}
+export type MCPResponseOverride = (
+  response: MCPToolResponse,
+  doc: Record<string, unknown>,
+  req: PayloadRequest,
+) => MCPToolResponse
+
+export type MCPAfterToolCallHook = (args: {
+  input: unknown
+  req: PayloadRequest
+  response: MCPToolResponse
+  toolName: string
+}) => MaybePromise<MCPToolResponse>
 
 /**
- * MCP Handler options.
+ * The handler's `input` type. A specific Standard Schema (Zod, Valibot, …) gets
+ * its inferred output; anything else falls back to `Record<string, unknown>`.
  */
-export type MCPHandlerOptions = {
-  /**
-   * Set the base path of the MCP handler. This is the path that will be used to access the MCP handler.
-   * @default /api
-   */
-  basePath?: string
+export type TypedInput<TSchema> = TSchema extends StandardSchemaWithJSON
+  ? StandardSchemaWithJSON extends TSchema
+    ? Record<string, unknown>
+    : StandardSchemaWithJSON.InferOutput<TSchema>
+  : Record<string, unknown>
+
+export type MCPAccessArgs = {
+  permissions?: SanitizedPermissions
+  req: PayloadRequest
+}
+
+export type CollectionMCPAccessArgs = {
+  collectionSlug: CollectionSlug
+} & MCPAccessArgs
+
+export type GlobalMCPAccessArgs = {
+  globalSlug: GlobalSlug
+} & MCPAccessArgs
+
+export type ToolHandlerArgs<TSchema = undefined> = {
+  authorizedMCP: AuthorizedMCP
+  input: TypedInput<TSchema>
+  req: PayloadRequest
+  serverContext: ServerContext
+}
+
+export type CollectionToolHandlerArgs<TSchema = undefined> = {
+  collectionSlug: CollectionSlug
+} & ToolHandlerArgs<TSchema>
+
+export type GlobalToolHandlerArgs<TSchema = undefined> = {
+  globalSlug: GlobalSlug
+} & ToolHandlerArgs<TSchema>
+
+export type Tool<TSchema extends ToolInputSchema | undefined = ToolInputSchema | undefined> = {
   /**
-   * If true, disables the SSE endpoint. Only Streamable HTTP will be available.
-   * @default true
+   * Runs while authorizing each MCP request, before the tool is advertised or called. Return
+   * `false` to make the tool unavailable for that request. This is skipped when `overrideAccess`
+   * is enabled.
    */
-  disableSse?: boolean
+  access?: (args: MCPAccessArgs) => MaybePromise<boolean>
+  annotations?: ToolAnnotations
+  description: string
+  handler: (args: ToolHandlerArgs<TSchema>) => MaybePromise<MCPToolResponse>
+  input?: TSchema
   /**
-   * Set the maximum duration of the MCP handler. This is the maximum duration that the MCP handler will run for.
-   * @default 60
+   * Override the return value of the tool handler
    */
-  maxDuration?: number
+  overrideResponse?: MCPResponseOverride
+}
+
+export type CollectionTool<
+  TSchema extends ToolInputSchema | undefined = ToolInputSchema | undefined,
+> = {
   /**
-   * Callback function that receives MCP events.
-   * This can be used to track analytics, debug issues, or implement custom behaviors.
+   * Runs while authorizing each MCP request for this collection. Return `false` to reject calls
+   * to this tool for the collection. The shared tool is not advertised when no collections allow
+   * it, but can remain advertised when it is available for another collection. This is skipped
+   * when `overrideAccess` is enabled.
    */
-  onEvent?: (event: unknown) => void
+  access?: (args: CollectionMCPAccessArgs) => MaybePromise<boolean>
+  handler: (args: CollectionToolHandlerArgs<TSchema>) => MaybePromise<MCPToolResponse>
+  input?: TSchema
+} & Pick<Tool, 'annotations' | 'description' | 'overrideResponse'>
+
+export type GlobalTool<TSchema extends ToolInputSchema | undefined = ToolInputSchema | undefined> =
+  {
+    /**
+     * Runs while authorizing each MCP request for this global. Return `false` to reject calls to
+     * this tool for the global. The shared tool is not advertised when no globals allow it, but
+     * can remain advertised when it is available for another global. This is skipped when
+     * `overrideAccess` is enabled.
+     */
+    access?: (args: GlobalMCPAccessArgs) => MaybePromise<boolean>
+    handler: (args: GlobalToolHandlerArgs<TSchema>) => MaybePromise<MCPToolResponse>
+    input?: TSchema
+  } & Pick<Tool, 'annotations' | 'description' | 'overrideResponse'>
+
+/**
+ * Configures (or disables) a built-in tool without replacing it.
+ * `handler?: never` prevents a full `CollectionTool`/`GlobalTool` (which has a
+ * required handler) from being silently accepted at a built-in key slot.
+ */
+export type MCPBuiltInCollectionToolOverride = {
   /**
-   * Set the Redis URL for the MCP handler. This is the URL that will be used to access the Redis server.
-   * @default process.env.REDIS_URL
+   * Replaces the built-in tool's access check. Return `false` to make the tool unavailable for
+   * this collection. This is skipped when `overrideAccess` is enabled.
    */
-  redisUrl?: string
+  access?: (args: CollectionMCPAccessArgs) => MaybePromise<boolean>
+  annotations?: ToolAnnotations
+  description?: string
+  handler?: never
+  overrideResponse?: MCPResponseOverride
+}
+
+export type MCPBuiltInGlobalToolOverride = {
   /**
-   * Set verbose logging.
-   * @default false
+   * Replaces the built-in tool's access check. Return `false` to make the tool unavailable for
+   * this global. This is skipped when `overrideAccess` is enabled.
    */
-  verboseLogs?: boolean
+  access?: (args: GlobalMCPAccessArgs) => MaybePromise<boolean>
+  annotations?: ToolAnnotations
+  description?: string
+  handler?: never
+  overrideResponse?: MCPResponseOverride
 }
 
 /**
- * MCP Server options.
+ * Value at a custom (non-built-in) tool key. Either the tool itself, or `false`
+ * to disable it (useful when one plugin defines a custom tool and another
+ * wants to opt out per-collection).
  */
-export type MCPServerOptions = {
-  /**
-   * Optional instructions describing how to use the server and its features.
-   */
-  instructions?: string
-  /**
-   * Set the server info of the MCP server.
-   */
-  serverInfo?: {
-    /**
-     * Set the name of the MCP server.
-     * @default 'Payload MCP Server'
-     */
-    name: string
-    /**
-     * Set the version of the MCP server.
-     * @default '1.0.0'
-     */
-    version: string
-  }
+export type MCPTopLevelToolEntry = Tool
+
+export type MCPCollectionToolsMap = {
+  [customToolName: string]: boolean | CollectionTool | MCPBuiltInCollectionToolOverride | undefined
+} & {
+  [K in MCPCollectionBuiltinName]?: false | MCPBuiltInCollectionToolOverride
 }
 
-export type MCPAccessSettings = {
-  auth?: {
-    auth?: boolean
-    forgotPassword?: boolean
-    login?: boolean
-    resetPassword?: boolean
-    unlock?: boolean
-    verify?: boolean
-  }
-  collections?: {
-    create?: boolean
-    delete?: boolean
-    find?: boolean
-    update?: boolean
-  }
-  config?: {
-    find?: boolean
-    update?: boolean
-  }
-  custom?: Record<string, boolean>
-  globals?: {
-    find?: boolean
-    update?: boolean
-  }
-  jobs?: {
-    create?: boolean
-    run?: boolean
-    update?: boolean
-  }
-  'payload-mcp-prompt'?: Record<string, boolean>
-  'payload-mcp-resource'?: Record<string, boolean>
-  'payload-mcp-tool'?: Record<string, boolean>
-  user: TypedUser
-} & Record<string, unknown>
+export type MCPAuthCollectionToolsMap = {
+  [K in MCPCollectionAuthToolName]?: MCPBuiltInCollectionToolOverride | true
+} & MCPCollectionToolsMap
 
-export type EntityConfig = MCPPluginConfig['collections'] | MCPPluginConfig['globals']
+/** Auth-enabled collections get auth-tool name autocomplete; others get CRUD-only. */
+export type MCPToolsMapForCollection<Slug extends CollectionSlug> = Slug extends AuthCollectionSlug
+  ? MCPAuthCollectionToolsMap
+  : MCPCollectionToolsMap
 
-export type FieldDefinition = {
-  description?: string
-  name: string
-  options?: { label: string; value: string }[]
-  position?: 'main' | 'sidebar'
-  required?: boolean
-  type: string
+export type MCPGlobalToolsMap = {
+  [customToolName: string]: boolean | GlobalTool | MCPBuiltInGlobalToolOverride | undefined
+} & {
+  [K in MCPGlobalBuiltinName]?: false | MCPBuiltInGlobalToolOverride
 }
 
-export type FieldModification = {
-  changes: {
-    description?: string
-    options?: { label: string; value: string }[]
-    position?: 'main' | 'sidebar'
-    required?: boolean
-    type?: string
-  }
-  fieldName: string
+export type MCPTopLevelToolsMap = Record<string, Tool>
+
+export type PromptHandlerArgs<TSchema = undefined> = {
+  input: TypedInput<TSchema>
+  req: PayloadRequest
+  serverContext: ServerContext
 }
 
-export type CollectionConfigUpdates = {
-  access?: {
-    create?: string
-    delete?: string
-    read?: string
-    update?: string
-  }
-  description?: string
-  slug?: string
-  timestamps?: boolean
-  versioning?: boolean
+export type Prompt<TSchema extends ToolInputSchema = ToolInputSchema> = {
+  /**
+   * Runs while authorizing each MCP request, before the prompt is advertised or used. Return
+   * `false` to make the prompt unavailable for that request. This is skipped when
+   * `overrideAccess` is enabled.
+   */
+  access?: (args: MCPAccessArgs) => MaybePromise<boolean>
+  argsSchema: TSchema
+  description: string
+  handler: (args: PromptHandlerArgs<TSchema>) => MaybePromise<{
+    messages: Array<{ content: { text: string; type: 'text' }; role: 'assistant' | 'user' }>
+  }>
+  title: string
 }
 
-export type AdminConfig = {
-  avatar?: string
-  css?: string
-  dateFormat?: string
-  inactivityRoute?: string
-  livePreview?: {
-    breakpoints?: Array<{
-      height: number
-      label: string
-      name: string
-      width: number
-    }>
-  }
-  logoutRoute?: string
-  meta?: {
-    favicon?: string
-    ogImage?: string
-    titleSuffix?: string
-  }
-  user?: string
+export type ResourceHandlerArgs = {
+  /** Variables extracted from a `ResourceTemplate` URI. Empty for static-URI resources. */
+  params: Record<string, string>
+  req: PayloadRequest
+  serverContext: ServerContext
+  uri: URL
+}
+
+export type Resource = {
+  /**
+   * Runs while authorizing each MCP request, before the resource is advertised or read. Return
+   * `false` to make the resource unavailable for that request. This is skipped when
+   * `overrideAccess` is enabled.
+   */
+  access?: (args: MCPAccessArgs) => MaybePromise<boolean>
+  description: string
+  handler: (args: ResourceHandlerArgs) => MaybePromise<{
+    contents: Array<{ text: string; uri: string }>
+  }>
+  mimeType: string
+  title: string
+  uri: ResourceTemplate | string
 }
 
-export type DatabaseConfig = {
-  connectOptions?: string
-  type?: 'mongodb' | 'postgres'
-  url?: string
+export type MCPPluginCollectionConfig<TSlug extends CollectionSlug> = {
+  description?: string
+  /** Fallback for built-in tools that don't set their own `overrideResponse`. */
+  overrideResponse?: MCPResponseOverride
+  tools?: MCPToolsMapForCollection<TSlug>
 }
 
-export type PluginUpdates = {
-  add?: string[]
-  remove?: string[]
+export type MCPPluginGlobalConfig = {
+  description?: string
+  overrideResponse?: MCPResponseOverride
+  tools?: MCPGlobalToolsMap
 }
 
-export type GeneralConfig = {
-  cookiePrefix?: string
-  cors?: string
-  csrf?: string
-  graphQL?: {
-    disable?: boolean
-    schemaOutputFile?: string
+/**
+ * The user-facing config shape passed to `mcpPlugin({ ... })`. Tools, prompts,
+ * resources, and per-collection/global tool maps live in their own nested
+ * fields. `sanitizeMCPConfig` flattens those into `items` and applies defaults
+ * to produce a `SanitizedMCPPluginConfig` — the form every internal consumer
+ * actually works with.
+ */
+export type MCPPluginConfig = {
+  collections?: {
+    [Slug in CollectionSlug]?: MCPPluginCollectionConfig<Slug>
   }
-  rateLimit?: {
-    max?: number
-    skip?: string
-    window?: number
+  /** Skip MCP endpoint registration. */
+  disabled?: boolean
+  globals?: {
+    [Slug in GlobalSlug]?: MCPPluginGlobalConfig
   }
-  secret?: string
-  serverURL?: string
-  typescript?: {
-    declare?: boolean
-    outputFile?: string
+  hooks?: {
+    /** Transform a tool response after its handler returns */
+    afterToolCall?: MCPAfterToolCallHook[]
+  }
+  mcp?: {
+    serverOptions?: MCPServerOptions
+    verboseLogs?: boolean
   }
+  /**
+   * Replace the default MCP authorization resolver.
+   *
+   * This hook replaces the default authentication flow. It must set `req.user` to the
+   * authenticated Payload user, or to `null` for an anonymous caller, before returning.
+   */
+  overrideGetAuthorizedMCP?: (
+    args: {
+      pluginConfig: SanitizedMCPPluginConfig
+    } & GetAuthorizedMCPArgs,
+  ) => MaybePromise<AuthorizedMCP>
+  prompts?: Record<string, Prompt>
+  resources?: Record<string, Resource>
+  /** Cross-cutting tools (not scoped to any collection or global). */
+  tools?: MCPTopLevelToolsMap
 }
 
-export interface SchemaField {
-  description?: string
-  name: string
-  options?: string[]
-  required?: boolean
-  type: string
+export type SanitizedMCPPluginConfig = {
+  items: MCPItem[]
+} & Pick<MCPPluginConfig, 'disabled' | 'hooks' | 'mcp' | 'overrideGetAuthorizedMCP'>
+
+export type MCPServerOptions = {
+  options?: ConstructorParameters<typeof McpServer>[1]
+  serverInfo?: Partial<ConstructorParameters<typeof McpServer>[0]>
 }
 
-export interface TaskSequenceItem {
-  description?: string
-  retries?: number
-  taskId: string
-  taskSlug: string
-  timeout?: number
+/**
+ * One MCP primitive plus the metadata needed for config-driven filtering and
+ * registration.
+ *
+ * - `configKey`: the config identifier, e.g. `find` or `echo`.
+ * - `mcpName`: the MCP wire name, e.g. `findDocuments` or `echo`.
+ * - `label`: human-readable display text.
+ */
+export type MCPItemBase = {
+  configKey: string
+  label: string
+  mcpName: string
 }
 
-export interface JobConfigUpdate {
-  description?: string
-  queue?: string
-  retries?: number
-  timeout?: number
+export type CollectionMCPItem = {
+  collectionSlug: CollectionSlug
+  tool: CollectionTool
+  type: 'collectionTool'
+} & MCPItemBase
+
+export type GlobalMCPItem = {
+  globalSlug: GlobalSlug
+  tool: GlobalTool
+  type: 'globalTool'
+} & MCPItemBase
+
+export type MCPItem =
+  | ({
+      prompt: Prompt
+      type: 'prompt'
+    } & MCPItemBase)
+  | ({
+      resource: Resource
+      type: 'resource'
+    } & MCPItemBase)
+  | ({
+      tool: Tool
+      type: 'tool'
+    } & MCPItemBase)
+  | CollectionMCPItem
+  | GlobalMCPItem
+
+/**
+ * The MCP items and access mode authorized for this request. The authenticated user is available
+ * as `req.user`.
+ */
+export type AuthorizedMCP = {
+  items: MCPItem[]
+  overrideAccess: boolean
 }