cd /news/ai-agents/your-mcp-server-changed-its-tools-wo… · home › topics › ai-agents › article
[ARTICLE · art-173160] src=dev.to ↗ pub= topic=ai-agents verified=true sentiment=· neutral

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

A developer built a small Python script that snapshots an MCP server's tool list by sending initialize and tools/list over stdio, then diffs two snapshots and exits with code 1 on any change so it can run in cron or CI. Comparing two releases of the official @modelcontextprotocol/server-filesystem (2026.1.14 and 2.4.0) showed that a version upgrade can hand an agent a different tool set with no notification and no visible change to the client config, since unpinned npx installs resolve to whatever release the cache serves.

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 playbook: Securing agents and AI tools
by read6 min views2 publishedNov 20, 2026

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 is for before you connect a server, and the no-code walkthrough 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 (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 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):

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):

$ 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, 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 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.

[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 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.)

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 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 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.

── more in #ai-agents 4 stories · sorted by recency
── more on @model context protocol 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/your-mcp-server-chan…] indexed:0 read:6min 2026-11-20 · —