MCP server tool approval

Tool risk classification

Not all tools need approval gates. Applying confirmation dialogs to read-only tools creates friction without adding safety. The right approach is to classify tools at registration time and apply the appropriate enforcement level.

The classification is set at tool registration time and stored in tool metadata, not in the LLM's system prompt. The handler checks its own risk tier and enforces the gate unconditionally — the LLM has no mechanism to override it.

// tool-registry.ts
type RiskTier = 'read' | 'low-write' | 'high-write' | 'critical';

interface ToolMeta {
  name: string;
  riskTier: RiskTier;
  description: string;
}

const TOOL_REGISTRY: ToolMeta[] = [
  { name: 'get_record',      riskTier: 'read',       description: 'Fetch a single record by ID' },
  { name: 'delete_record',   riskTier: 'high-write', description: 'Permanently delete a record' },
  { name: 'send_email_blast',riskTier: 'critical',   description: 'Send email to all subscribers' },
];

Implementing approval with elicitation

MCP elicitation (available in clients that support the elicitation capability) is the right protocol mechanism for approval gates. The tool handler computes a change preview, sends it to the user, and waits for a boolean confirm/deny response before executing.

// tools/delete-record.ts
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { requireApproval } from '../lib/approval.js';
import { db } from '../lib/db.js';

export function registerDeleteRecord(server: McpServer) {
  server.tool(
    'delete_record',
    {
      record_id: { type: 'string', description: 'ID of the record to delete' },
    },
    async (args, extra) => {
      // 1. Fetch what will be deleted (preview)
      const record = await db.records.findById(args.record_id);
      if (!record) {
        return {
          content: [{ type: 'text', text: `No record found with ID ${args.record_id}` }],
          isError: true,
        };
      }

      const preview = [
        `Record: ${record.name} (${record.id})`,
        `Type: ${record.type}`,
        `Created: ${record.created_at}`,
        `This action is permanent and cannot be undone.`,
      ].join('\n');

      // 2. Gate on approval
      const approved = await requireApproval(extra, {
        action: 'delete_record',
        preview,
        warningLevel: 'high',
      });

      if (!approved) {
        return { content: [{ type: 'text', text: 'Delete cancelled — record not deleted.' }] };
      }

      // 3. Execute only after approval
      await db.records.delete(args.record_id);
      await audit.log({ action: 'delete_record', recordId: args.record_id, approved: true });

      return { content: [{ type: 'text', text: `Record ${args.record_id} deleted.` }] };
    }
  );
}

// lib/approval.ts
import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/server/mcp.js';

interface ApprovalOptions {
  action: string;
  preview: string;
  warningLevel: 'low' | 'high' | 'critical';
}

export async function requireApproval(
  extra: RequestHandlerExtra,
  opts: ApprovalOptions
): Promise<boolean> {
  if (!extra.clientCapabilities?.elicitation) {
    throw new Error(
      `Tool "${opts.action}" requires user approval but the connected client ` +
      `does not support elicitation. Use a client with elicitation support.`
    );
  }

  const result = await extra.requestElicitation({
    message: `⚠️ Confirm ${opts.warningLevel === 'critical' ? 'CRITICAL ' : ''}action:\n\n${opts.preview}`,
    requestedSchema: {
      type: 'object',
      properties: {
        confirmed: {
          type: 'boolean',
          title: 'I confirm this action',
          description: 'Check this box to proceed',
        },
      },
      required: ['confirmed'],
    },
  });

  if (result.action !== 'accept') return false;
  return result.content.confirmed === true;
}

Why server-side enforcement is non-negotiable

It's tempting to put the approval requirement in the system prompt: "Before calling delete_record, always ask the user for confirmation." This approach has a critical flaw: the LLM controls whether the confirmation happens, not the server. Three failure modes:

Server-side enforcement means the gate runs in the handler before any database write, regardless of what instructions the LLM did or didn't follow. The LLM cannot call delete_record without the approval dialog appearing — the server enforces it unconditionally.

Showing a diff preview before confirmation

For update operations, a flat string preview is less useful than a diff. Showing the user exactly what will change before they confirm reduces both false approvals (clicking through without reading) and false denials (declining because the preview was unclear).

// For record updates: compute a before/after diff
async function buildUpdatePreview(
  current: Record<string, unknown>,
  updates: Record<string, unknown>
): Promise<string> {
  const lines: string[] = ['Changes to be applied:'];

  for (const [key, newValue] of Object.entries(updates)) {
    const oldValue = current[key];
    if (oldValue !== newValue) {
      lines.push(`  ${key}:`);
      lines.push(`    before: ${JSON.stringify(oldValue)}`);
      lines.push(`    after:  ${JSON.stringify(newValue)}`);
    }
  }

  if (lines.length === 1) {
    return 'No changes detected.';
  }

  return lines.join('\n');
}

// In the tool handler:
const preview = await buildUpdatePreview(existingRecord, args.updates);
const approved = await requireApproval(extra, {
  action: 'update_record',
  preview,
  warningLevel: 'high',
});

Approval timeouts

Elicitation requests don't expire on their own — the tool handler will wait indefinitely for a response. For approval dialogs on critical operations, add a timeout that auto-denies if the user doesn't respond within a reasonable window.

export async function requireApprovalWithTimeout(
  extra: RequestHandlerExtra,
  opts: ApprovalOptions,
  timeoutMs = 60_000
): Promise<boolean> {
  const elicitationPromise = extra.requestElicitation({
    message: `Confirm action (auto-denied in ${timeoutMs / 1000}s if no response):\n\n${opts.preview}`,
    requestedSchema: {
      type: 'object',
      properties: {
        confirmed: { type: 'boolean', title: 'Confirm' },
      },
      required: ['confirmed'],
    },
  });

  const timeoutPromise = new Promise<never>((_, reject) =>
    setTimeout(() => reject(new Error('Approval timed out')), timeoutMs)
  );

  try {
    const result = await Promise.race([elicitationPromise, timeoutPromise]);
    return result.action === 'accept' && result.content.confirmed === true;
  } catch (err) {
    await audit.log({ action: opts.action, approved: false, reason: 'timeout' });
    return false;
  }
}

Audit trail

Every approval and denial should be logged. The audit trail is your evidence that the system worked as intended, and it's essential for post-incident investigation if a destructive action is taken that the user claims they didn't authorize.

// lib/audit.ts
import { db } from './db.js';

interface ApprovalEvent {
  timestamp: string;
  userId: string;
  sessionId: string;
  toolName: string;
  arguments: Record<string, unknown>;
  action: 'approved' | 'denied' | 'timeout' | 'no_elicitation_support';
  preview: string;
}

export const audit = {
  async logApproval(event: ApprovalEvent): Promise<void> {
    await db.approvalEvents.insert({
      ...event,
      timestamp: event.timestamp ?? new Date().toISOString(),
    });
  },
};

The audit log should be append-only and stored separately from the tables the destructive tools operate on. If a tool deletes records from records, the approval log should be in a different table (or different database) so deleting a record doesn't also delete the approval evidence.

The audit logging guide covers retention, access control, and querying approval history in more detail.

Further reading

• MCP server elicitation — requesting user input mid-tool-call
• MCP server audit logging — structured event trails for compliance
• MCP server RBAC — role-based access control for tool calls
• MCP server prompt injection defense — protecting tools from adversarial output
• MCP server error handling — isError, McpError, and structured failures
• AliveMCP — continuous protocol monitoring for MCP servers