# Your MCP Server Changed Its Tools. Would Your Agent Notice?

> Source: <https://dev.to/promptmaster/your-mcp-server-changed-its-tools-would-your-agent-notice-4j9a>
> Published: 2026-11-20 10:02:02+00:00

**Recommendation:** Pin your MCP server versions and run a tools/list snapshot diff in CI so a silent tool-set change on upgrade fails the build instead of reaching your agent.
More in the playbook "Securing agents and AI tools": <https://wpnews.pro/playbooks/agent-security>

Many MCP setup examples, including the ones in official client docs, start a local server without a version:

```
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects/demo"]
```

Which release you get then depends on `npx` and its cache, not on your config. Cursor's own docs tell you to clear the npm cache and re-add a server to get the latest version. A newer release can offer your agent a different set of tools, and because your config file hasn't changed, nothing looks different on your side.

To see what that looks like, this morning I took a snapshot of the tool list from two releases of the official filesystem server and compared them. Below: the script, the real output, what the protocol says, and how Claude Code, Codex and Cursor limit what a new tool can do.

The [5-question trust check](https://dev.to/promptmaster/before-you-connect-an-mcp-server-a-5-question-trust-check-kf) is for before you connect a server, and the [no-code walkthrough](https://dev.to/promptmaster/mcp-without-code-connect-your-ai-assistant-to-a-folder-step-by-step-33mb) covers setup. This one is for after the server is connected and working. Protocol and client details below are from the official docs, fetched on 20 Nov 2026.

The [MCP tools specification](https://modelcontextprotocol.io/specification/2026-07-28/server/tools) (current revision, 2026-07-28) says a server answers `tools/list` with the tools currently available, and that this set "MAY change over time." A server that declares `listChanged` should send a `notifications/tools/list_changed` notification when it does, and the client then asks for the list again.

That covers changes while a server is running. Claude Code's [MCP docs](https://code.claude.com/docs/en/mcp#dynamic-tool-updates) describe the client side: when the notification arrives in an interactive session, Claude Code fetches the updated list "so you don't need to reconnect it." Convenient, and it means the new list reaches the agent without any step from you.

A version upgrade is different: the server restarts with new code and simply reports a new list. No notification is involved.

The spec also gives you two reasons not to trust a list just because it arrived:

`readOnlyHint: true` is the server describing itself.
The script is Python, standard library only. `snap` starts a stdio server, sends `initialize` (2025-11-25 handshake) and `tools/list`, then saves each tool's name, a short hash of its description and input schema, and its annotations. `diff` compares two snapshots and exits with code 1 if anything changed, so it can run from cron or CI.

The full script is under 90 lines. This is a simplified excerpt of the `snap` part (the real script also stops the server on errors and follows pagination):

``` python
def snap(out, cmd):
    proc = subprocess.Popen(cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
                            stderr=subprocess.DEVNULL, text=True)
    init = rpc(proc, {"jsonrpc": "2.0", "id": 1, "method": "initialize",
                      "params": {"protocolVersion": "2025-11-25", "capabilities": {},
                                 "clientInfo": {"name": "tool-snapshot", "version": "0.1"}}})
    rpc(proc, {"jsonrpc": "2.0", "method": "notifications/initialized"})
    tools = rpc(proc, {"jsonrpc": "2.0", "id": 2, "method": "tools/list",
                       "params": {}})["tools"]   # full script follows nextCursor
    proc.terminate()
    snapshot = {"server": init["serverInfo"], "tools": {
        t["name"]: {"description": h(t.get("description", "")),
                    "inputSchema": h(t.get("inputSchema", {})),
                    "annotations": t.get("annotations", {})} for t in tools}}
    json.dump(snapshot, open(out, "w"), indent=2, sort_keys=True)
```

I ran it against two releases of `@modelcontextprotocol/server-filesystem`, each pointed at a scratch folder: `2026.1.14` (January) and `2.4.0`, which npm lists as published on 18 Nov and which is the current `latest` tag. Real output (the diff is trimmed after three changed tools):

``` bash
$ python3 mcp_tool_snapshot.py snap tools-2026.1.14.json -- npx -y @modelcontextprotocol/server-filesystem@2026.1.14 /tmp/mcpdemo
secure-filesystem-server 0.2.0: 14 tools, listChanged=True -> tools-2026.1.14.json

$ python3 mcp_tool_snapshot.py snap tools-2.4.0.json -- npx -y @modelcontextprotocol/server-filesystem@2.4.0 /tmp/mcpdemo
secure-filesystem-server 2.4.0: 16 tools, listChanged=True -> tools-2.4.0.json

$ python3 mcp_tool_snapshot.py diff tools-2026.1.14.json tools-2.4.0.json
0.2.0 -> 2.4.0
  + added    append_file
  + added    copy_file
  ~ changed  create_directory (inputSchema, annotations)
  ~ changed  directory_tree (description, inputSchema, annotations)
  ~ changed  edit_file (description, inputSchema, annotations)
  ...
Summary: 2 added, 0 removed, 14 changed
```

I also ran the unversioned command from the top of this article. On my machine today it resolved to 2.4.0: its diff against the pinned 2.4.0 snapshot was `0 added, 0 removed, 0 changed`, so it gets the 16-tool list.

Here's what was behind the output (I saved the full raw lists):

`append_file` appends text to a file and creates the file if it doesn't exist. `copy_file` copies a file and never overwrites. Both are marked `readOnlyHint: false`. Their descriptions say they only work inside the allowed directories, but they are new ways to change files.`number` limits became `integer` with bounds, and parameters gained descriptions. The annotations gained `idempotentHint`, `destructiveHint` and `openWorldHint`. Harmless, but you only know that after you look.` read_media_file` was described as reading an image or audio file. In 2.4.0 its description says any other file type is returned as an embedded resource. A changed description can mean the tool now does more.`serverInfo.version` "0.2.0", not 2026.1.14. Pin the package in your config, don't rely on what the server says about itself.
This isn't a criticism of the filesystem server: the changes look like normal improvements. That's the point. Even a well-run official server changes its tools, and you want to see it before your agent uses the new ones.

Pinning is one edit in the same file:

```
"args": ["-y", "@modelcontextprotocol/server-filesystem@2.4.0", "/Users/me/projects/demo"]
```

My upgrade routine:

`diff`. Read every A `diff` with exit code 1 doesn't mean "don't upgrade." It means read before you upgrade.

Pinning controls when the list changes. Client settings limit what an unreviewed tool can do.

**Claude Code.** In [permission rules](https://code.claude.com/docs/en/permissions), `mcp__filesystem__*` (or plain `mcp__filesystem`) matches every tool from that server, so an allow rule written that way also covers a tool added in the next release. To auto-approve only what you've reviewed, name the tools, for example `mcp__filesystem__read_text_file`, and leave the rest to the normal permission prompt.

**Codex.** The [MCP config](https://developers.openai.com/codex/mcp) has `enabled_tools` (a tool allow list) and `disabled_tools` (a deny list applied after it), plus `default_tools_approval_mode` per server. Its `writes` mode prompts for tools that aren't marked read-only, but remember that "read-only" is the server's own annotation.

```
# Not run: example config based on the Codex MCP docs
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem@2.4.0", "/Users/me/projects/demo"]
enabled_tools = ["read_text_file", "list_directory", "search_files"]
default_tools_approval_mode = "prompt"
```

**Cursor.** The [MCP docs](https://cursor.com/docs/mcp) say Cursor asks for approval before using MCP tools by default, and in Auto-review mode allowlisted MCP tools run right away. Keep your allowlist to tools you've read. A disabled server doesn't load or appear in chat, which also keeps its tool list out of your agent's context. (I covered the context side in [What to Trim First](https://dev.to/promptmaster/your-agents-context-fills-up-before-you-type-what-to-trim-first-36n0).)

`npx` (or similar) MCP server in your config.`readOnlyHint` as the server's claim, not a guarantee.`mcp__` rules in Claude Code, `enabled_tools` in Codex, a short Cursor allowlist.
The free [MCP Quick-Start Cheat Sheet](https://promptmasterstore.gumroad.com/l/mcp-cheat-sheet?utm_source=devto) is a 5-page PDF: MCP explained in 30 seconds, a 10-minute Claude Desktop setup with the config to copy, the servers worth connecting first, the 5-question trust check, and a one-page quick reference.

When you want the full picture without writing code, [MCP Made Simple](https://promptmasterstore.gumroad.com/l/mcp-made-simple?utm_source=devto) is a 46-page guide in 5 parts and 22 chapters: setup in Claude Desktop, Claude Code and Cursor, the config file explained, a troubleshooting chapter, choosing servers safely, real workflows, and a 7-day plan to build your own MCP stack.

*This article was written with the assistance of AI and reviewed by the author. Protocol details are from the official MCP specification (revision 2026-07-28: tools and versioning pages), and client behaviour is from the official Claude Code (MCP, permissions), Codex (MCP) and Cursor (MCP) docs, all fetched on 20 Nov 2026. The script output is a real run on 20 Nov 2026 against the published npm packages; the Codex config example was not run. PromptMaster guides are independent and not affiliated with or endorsed by Anthropic, OpenAI, Cursor or the MCP project.*
