How to mark MCP tools read-only or destructive

// policy.mjs: turn tool annotations into a confirmation decision.
// Annotations are optional hints. When one is missing, the spec defines a
// default, and the safe reading is the cautious one. Fill defaults first.
export function resolveAnnotations(tool) {
  const a = tool.annotations ?? {};
  return {
    readOnlyHint: a.readOnlyHint ?? false,      // assume it can write
    destructiveHint: a.destructiveHint ?? true, // assume writes can destroy
    idempotentHint: a.idempotentHint ?? false,  // assume repeats add effects
    openWorldHint: a.openWorldHint ?? true,     // assume it reaches outside
  };
}

// Return "auto", "notify", or "confirm" for a tool.
export function decide(tool) {
  const { readOnlyHint, destructiveHint, openWorldHint } = resolveAnnotations(tool);

  // Read-only and closed-world: nothing to undo, no outside reach. Auto-run.
  if (readOnlyHint && !openWorldHint) return "auto";

  // destructiveHint only means anything when the tool is not read-only.
  if (!readOnlyHint && destructiveHint) return "confirm";

  // Writes, but reversible: run it, tell the user what happened.
  return "notify";
}

// server.mjs: an MCP server whose tools declare behavior with annotations.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export function buildServer() {
  const server = new McpServer({ name: "notes-server", version: "1.0.0" });

  // Read-only, closed-world: safe to call without asking the user.
  server.registerTool(
    "search_notes",
    {
      title: "Search notes",
      description: "Full-text search over the local notes index.",
      inputSchema: { query: z.string() },
      annotations: {
        title: "Search notes",
        readOnlyHint: true,
        openWorldHint: false,
      },
    },
    async ({ query }) => ({
      content: [{ type: "text", text: `3 notes match "${query}"` }],
    })
  );

  // Writes, but not destructive, and safe to repeat: create-or-replace by id.
  server.registerTool(
    "upsert_note",
    {
      title: "Save note",
      description: "Create or overwrite a note by id.",
      inputSchema: { id: z.string(), body: z.string() },
      annotations: {
        title: "Save note",
        readOnlyHint: false,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: false,
      },
    },
    async ({ id }) => ({
      content: [{ type: "text", text: `Saved note ${id}` }],
    })
  );

  // Irreversible local change: destructive, so a client should confirm first.
  server.registerTool(
    "delete_note",
    {
      title: "Delete note",
      description: "Permanently delete a note by id.",
      inputSchema: { id: z.string() },
      annotations: {
        title: "Delete note",
        readOnlyHint: false,
        destructiveHint: true,
        idempotentHint: true,
        openWorldHint: false,
      },
    },
    async ({ id }) => ({
      content: [{ type: "text", text: `Deleted note ${id}` }],
    })
  );

  // Reaches an external system: not read-only, and open-world.
  server.registerTool(
    "send_email",
    {
      title: "Send email",
      description: "Send an email to an external address.",
      inputSchema: { to: z.string(), subject: z.string() },
      annotations: {
        title: "Send email",
        readOnlyHint: false,
        destructiveHint: true,
        idempotentHint: false,
        openWorldHint: true,
      },
    },
    async ({ to }) => ({
      content: [{ type: "text", text: `Email sent to ${to}` }],
    })
  );

  return server;
}

// run.mjs: connect a client to the server in-process, read every tool's
// annotations, and apply the confirmation policy. One command, no network.
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { buildServer } from "./server.mjs";
import { decide, resolveAnnotations } from "./policy.mjs";

const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
const server = buildServer();
await server.connect(serverTransport);

const client = new Client({ name: "notes-host", version: "1.0.0" });
await client.connect(clientTransport);

const { tools } = await client.listTools();

console.log("tool           read  destr  idem  open   -> action");
console.log("-------------- ----- ------ ----- -----  ---------");
for (const tool of tools) {
  const a = resolveAnnotations(tool);
  const action = decide(tool);
  const flag = (b) => (b ? "yes" : "no ");
  console.log(
    tool.name.padEnd(14),
    flag(a.readOnlyHint).padEnd(5),
    flag(a.destructiveHint).padEnd(6),
    flag(a.idempotentHint).padEnd(5),
    flag(a.openWorldHint).padEnd(5),
    "->",
    action
  );
}

// Prove the policy gates a real call. A destructive tool needs a yes first.
async function callWithPolicy(name, args, userSaysYes) {
  const tool = tools.find((t) => t.name === name);
  const action = decide(tool);
  if (action === "confirm" && !userSaysYes) {
    return `BLOCKED: ${name} needs confirmation`;
  }
  const res = await client.callTool({ name, arguments: args });
  return `${action.toUpperCase()}: ${res.content[0].text}`;
}

console.log("");
console.log(await callWithPolicy("search_notes", { query: "mcp" }, false));
console.log(await callWithPolicy("delete_note", { id: "42" }, false));
console.log(await callWithPolicy("delete_note", { id: "42" }, true));

await client.close();
await server.close();

npm init -y
npm i @modelcontextprotocol/[email protected] [email protected]
node run.mjs

tool           read  destr  idem  open   -> action
-------------- ----- ------ ----- -----  ---------
search_notes   yes   yes    no    no    -> auto
upsert_note    no    no     yes   no    -> notify
delete_note    no    yes    yes   no    -> confirm
send_email     no    yes    no    yes   -> confirm

AUTO: 3 notes match "mcp"
BLOCKED: delete_note needs confirmation
CONFIRM: Deleted note 42