MCP plugin: expose tool annotations (hints like readOnlyHint) for generated and custom tools

[jhb-dev]

Plugin: @payloadcms/plugin-mcp

Summary

The MCP plugin auto-generates tools for collections (find/create/update/delete) and globals (find/update), but it does not expose any way to set MCP tool annotations (a.k.a. "hints") on those tools. These annotations — readOnlyHint, destructiveHint, idempotentHint, openWorldHint, and title — are part of the MCP spec and are used by clients to communicate tool behavior to the user and the model.

Notably, claude.ai uses these hints to group tools (e.g. separating read-only tools from tools that modify data), and to drive how/when a tool requires confirmation. Without them, every Payload-generated tool is treated identically, which makes the tool list harder to reason about and approve.

Background

Per the MCP spec, a tool definition may include an optional annotations object:

Annotation	Type	Default	Meaning
title	string	–	Human-readable display title for the tool
readOnlyHint	boolean	false	The tool does not modify its environment
destructiveHint	boolean	true	The tool may perform destructive (irreversible) updates
idempotentHint	boolean	false	Repeated calls with the same args have no additional effect
openWorldHint	boolean	true	The tool interacts with external entities

These map very naturally onto the operations the plugin already generates:

• find* → readOnlyHint: true, idempotentHint: true
• create* → readOnlyHint: false
• update* → readOnlyHint: false
• delete* → readOnlyHint: false, destructiveHint: true

Current behavior

There is no configuration option to set annotations on the generated tools, and the plugin does not appear to set sensible defaults for them. The relevant config shapes (collections[slug], globals[slug], and mcp.tools[]) expose enabled, description, overrideResponse, etc., but nothing for annotations/hints.

Desired behavior

1. Sensible defaults — the plugin should set the obviously-correct hints on the tools it generates (find* read-only + idempotent, delete* destructive, etc.) so clients like claude.ai can group/handle them correctly out of the box.

2. Custom tools — allow passing annotations through mcp.tools[] so custom tools can declare hints too:

   mcp: {
     tools: [
       {
         name: 'searchPosts',
         description: '...',
         parameters: schema,
         annotations: { readOnlyHint: true, idempotentHint: true },
         handler,
       },
     ],
   }

Why this matters

• claude.ai (and other MCP clients) group and present tools based on these hints; read-only tools can be surfaced/auto-approved differently from destructive ones.
• It improves trust & safety: a delete* tool flagged with destructiveHint: true can be gated behind stronger confirmation.
• It's low-risk: the underlying MCP SDK already supports annotations on tool registration — the plugin just needs to forward them.