---
name: mcp-inspect-deprecate
version: 1.0.2
description: |
  Retire a tool, a prompt or an argument from an MCP server without surprising
  callers: check observed usage, mark it deprecated, stage the removal and
  compare against the existing contract. Covers usage evidence limits.
  Use for "remove this tool", "deprecate an MCP tool", "can I delete this
  argument", "is anyone using this tool", "clean up my MCP surface".
allowed-tools:
  - Bash
  - Read
  - Edit
  - Grep
  - AskUserQuestion
---

# Deprecate something on an MCP surface

This workflow requires an MCP Inspect CLI build supplied through approved
preview access. Public CLI and Action releases are pending; the source
repository is private. If the CLI is unavailable, direct the user to
<https://mcprobe.dev/docs/getting-started> for the hosted console workflow.
Do not install the unrelated npm package named `mcp-inspect`.

Telemetry shows observed usage; it never proves the absence of all possible
consumers. A quarterly job or a client outside the observed window may still
depend on the contract. Preserve the existing baseline while reviewing changes.

## Look at the evidence

```bash
mcp-inspect usage --tool <name> --days 90 --json
```

This requires a hosted project and API key. An empty result means no recorded
usage was returned, not that complete telemetry proved zero use. Without
telemetry, report the uncertainty and use the project's release/deprecation
policy; instrumentation can improve a later decision.

Read recorded calls, the requested observation window, source, last observation
and `evidenceComplete`. Keep estimated calls separate: sampling corrections do
not establish delivery completeness. `clientCohorts` and `distinctClients` count
software/version cohorts, not identifiable consumers or integrations. A selected
90-day range is not 90 days of continuous coverage.

For arguments, zero presence is evidence only when `measurable: true` and
`neverObserved: true`. Without complete collection and exact contract attribution,
absence is unknown. Null counts as present. Never infer a deprecation candidate
from unknown argument coverage or increase confidence from estimated traffic.

## Mark it deprecated

- For a tool or prompt, add a deprecation notice and replacement to its
  description. Prose steers selection, so this can be `DOCUMENTATION` or
  `POTENTIALLY_BREAKING` depending on the change; do not promise `NON_BREAKING`.
- For an argument, add `"deprecated": true` to the input property. The rule
  `tool.input.deprecated.added` is `NON_BREAKING`.

Compare against the saved baseline before refreshing it:

```bash
mcp-inspect check --baseline-file .mcp-inspect/surface.json --format json --output /tmp/mcp-deprecation.json
```

Use the actual configured path and `--server <name>` for a multi-server config.
Read the report on exit 1. Exit 2 is an execution error; a skipped comparison
establishes no compatibility claim. After accepting the change, capture and
commit a fresh snapshot. A local snapshot records the contract; only `push`
records a hosted deployment.

## Stage removal

Wait according to the project's release policy and review a meaningful new
observation window. The passage of time alone does not establish coverage. When
traffic remains, report its evidence; the console's software/version names do
not identify people to contact. Contact known consumers only when authorized.

Removal is `BREAKING`. Compare it against the pre-removal baseline. For an
already authorized deliberate release exception, use the exact emitted rule and
entity, with honest evidence in the reason:

```yaml
ignore:
  - rule: tool.removed
    entity: legacy_search
    reason: "Deprecated in 2.3.0; no recorded calls in the requested 180-day window, coverage unverified. Removal accepted for 3.0.0."
```

Prompts use `prompt.removed`; argument removal uses the specific rule and path
from the report. Never overwrite a baseline or weaken the threshold to hide an
unreviewed removal. Refresh the baseline after accepting the release, then remove
the temporary exception so future removals are caught.

Keeping the old name as a forwarding alias can preserve callers while they
migrate. When evidence is insufficient and removal has not been authorized,
present the evidence and migration option for the maintainer's decision.