MCP server cancellation

The cancellation protocol

MCP cancellation uses a standard JSON-RPC notification. When the client decides to cancel an in-flight tool call, it sends:

{
  "jsonrpc": "2.0",
  "method": "notifications/cancelled",
  "params": {
    "requestId": "42",
    "reason": "User cancelled"
  }
}

The MCP SDK receives this notification, locates the in-flight request by its requestId, and aborts the AbortController it created for that request. Your tool handler sees the abort via extra.signal.aborted === true or via an 'abort' event on the signal. You do not need to parse the notifications/cancelled message yourself — the SDK handles the mapping.

Cancellation is a best-effort mechanism. The notification may arrive after your handler has already returned a result, in which case both the result and the cancellation notification are discarded. This is normal; cancellation is not a guarantee of non-execution, only a request to stop if still possible.

Reading extra.signal

Every tool handler receives an AbortSignal in the second argument (extra) under the signal property. For tools where cancellation is not meaningful — fast operations that return in under a second — you can ignore it. For long-running tools, passing it to downstream operations is the key step.

server.tool(
  'bulk_process',
  { dataset_id: z.string(), operation: z.enum(['transform', 'validate', 'export']) },
  async (args, extra) => {
    const { signal } = extra;

    // Pass signal to every async operation that supports it
    const dataset = await fetchDataset(args.dataset_id, { signal });

    const results: string[] = [];
    for (const item of dataset.items) {
      if (signal.aborted) {
        // Early exit between items — clean state, no partial writes yet
        return {
          content: [{ type: 'text', text: `Cancelled after processing ${results.length} items.` }],
        };
      }

      const result = await processItem(item, args.operation, { signal });
      results.push(result);
    }

    return {
      content: [{ type: 'text', text: `Processed ${results.length} items.` }],
    };
  }
);

The signal.aborted check inside the loop is a polling pattern — it catches cancellation at the boundary between items. For operations where you want the cancellation to interrupt a long single step (a large fetch, a slow query), pass the signal as the AbortSignal option and let the underlying API throw an AbortError.

Propagating cancellation to fetch() and databases

Most modern async APIs accept an AbortSignal option directly. Pass extra.signal to every operation that might take more than a few hundred milliseconds.

// Native fetch — signal supported natively
const response = await fetch('https://api.example.com/data', {
  signal: extra.signal,
  headers: { Authorization: `Bearer ${apiKey}` },
});

// Node.js https — use undici Dispatcher or pass via AbortController
// undici fetch also accepts signal natively:
import { fetch } from 'undici';
const data = await fetch(url, { signal: extra.signal });

// node-postgres (pg)
// pg Client.query() does not accept AbortSignal — use a listener instead:
const ac = new AbortController();
extra.signal.addEventListener('abort', () => ac.abort(), { once: true });
const client = await pool.connect();
try {
  const result = await Promise.race([
    client.query('SELECT * FROM large_table WHERE id = $1', [args.id]),
    new Promise<never>((_, reject) =>
      ac.signal.addEventListener('abort', () => reject(new Error('Cancelled')))
    ),
  ]);
  return { content: [{ type: 'text', text: JSON.stringify(result.rows) }] };
} finally {
  client.release();
}

// Prisma — wrap in signal listener
const queryPromise = prisma.record.findMany({ where: { datasetId: args.id } });
const cancelPromise = new Promise<never>((_, reject) => {
  extra.signal.addEventListener('abort', () => reject(new Error('Cancelled')), { once: true });
});
const records = await Promise.race([queryPromise, cancelPromise]);

When fetch() receives an aborted signal, it throws a DOMException with name === 'AbortError'. Catch this specifically and return a clean cancelled result rather than letting it propagate as an unhandled exception, which would produce a JSON-RPC -32603 error and may confuse the client about whether the session is still usable.

try {
  const response = await fetch(url, { signal: extra.signal });
  const data = await response.json();
  return { content: [{ type: 'text', text: JSON.stringify(data) }] };
} catch (err) {
  if (err instanceof DOMException && err.name === 'AbortError') {
    return { content: [{ type: 'text', text: 'Request cancelled.' }] };
  }
  throw err; // unexpected error — let the SDK handle it
}

Cleaning up in finally blocks

Resources acquired before a cancellation point must be released regardless of how the handler exits. Use try/finally to guarantee cleanup even when an AbortError propagates through the call stack.

server.tool('write_report', { ... }, async (args, extra) => {
  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'report-'));
  const lock = await acquireLock(`report:${args.id}`);

  try {
    const data = await gatherData(args, { signal: extra.signal });
    const reportPath = path.join(tmpDir, 'report.pdf');
    await generatePdf(data, reportPath, { signal: extra.signal });
    const buffer = await fs.readFile(reportPath);

    return {
      content: [{ type: 'image', data: buffer.toString('base64'), mimeType: 'application/pdf' }],
    };
  } catch (err) {
    if (err instanceof DOMException && err.name === 'AbortError') {
      return { content: [{ type: 'text', text: 'Report generation cancelled.' }] };
    }
    throw err;
  } finally {
    // Always runs — even on AbortError or unexpected exceptions
    await lock.release();
    await fs.rm(tmpDir, { recursive: true, force: true });
  }
});

Rolling back partial writes

Cancellation is most dangerous when a tool has already begun writing to durable state — a database, a file, a third-party API — and is interrupted mid-way. The correct approach depends on what you are writing:

Database writes: use transactions. Start a transaction before any writes. On cancellation or error, roll back. The database returns to a consistent state regardless of how many rows were written before the signal fired.

const client = await pool.connect();
await client.query('BEGIN');
try {
  for (const record of args.records) {
    if (extra.signal.aborted) throw new Error('Cancelled');
    await client.query(
      'INSERT INTO records (id, data) VALUES ($1, $2)',
      [record.id, record.data]
    );
  }
  await client.query('COMMIT');
  return { content: [{ type: 'text', text: `Inserted ${args.records.length} records.` }] };
} catch (err) {
  await client.query('ROLLBACK');
  if (err.message === 'Cancelled') {
    return { content: [{ type: 'text', text: 'Insert cancelled — no records written.' }] };
  }
  throw err;
} finally {
  client.release();
}

File writes: write to a temp file, then atomic rename. Write to a temporary path in the same directory; on success, fs.rename() the temp file to the final path. Cancellation before the rename leaves the original file untouched and the temp file is cleaned up in finally.

Third-party API calls: idempotency keys. For APIs that support idempotency keys, generate a key from the session ID and tool call arguments before starting. If the call is cancelled and later retried, the same key produces the same result without a duplicate action on the remote system.

Cancellation vs timeout

Both cancellation and timeout use the same AbortSignal mechanism. A tool that imposes its own timeout does so with an AbortController that it aborts after a deadline:

server.tool('timed_tool', { ... }, async (args, extra) => {
  // Merge timeout signal with client cancellation signal
  const timeoutController = new AbortController();
  const timeoutId = setTimeout(() => timeoutController.abort(), 30_000);

  // Combine: aborted if either the client cancels OR the timeout fires
  const combined = AbortSignal.any([extra.signal, timeoutController.signal]);

  try {
    const result = await runOperation(args, { signal: combined });
    return { content: [{ type: 'text', text: result }] };
  } catch (err) {
    if (err instanceof DOMException && err.name === 'AbortError') {
      const reason = extra.signal.aborted ? 'cancelled by client' : 'timed out after 30 seconds';
      return { content: [{ type: 'text', text: `Operation ${reason}.` }], isError: true };
    }
    throw err;
  } finally {
    clearTimeout(timeoutId);
  }
});

AbortSignal.any() (Node.js 20+) returns a signal that fires when any of the input signals aborts. This is the cleanest way to combine client-cancellation and server-timeout into a single signal that you can pass throughout your code.

Further reading

• MCP server progress notifications — streaming updates from long-running tools
• MCP server session lifecycle — connection management and reconnection
• MCP server graceful shutdown — draining sessions on SIGTERM
• MCP server error handling — JSON-RPC codes and isError patterns
• MCP server retry logic — exponential backoff and idempotency keys
• AliveMCP — continuous protocol monitoring for MCP servers