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 protocol expects tool lists to change
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:
- Clients "MUST consider tool annotations to be untrusted unless they come from trusted servers." A
readOnlyHint: trueis the server describing itself. - There "SHOULD always be a human in the loop with the ability to deny tool invocations."
Snapshot the tool list, then compare
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.
Read the diff
Here's what was behind the output (I saved the full raw lists):
- Two new tools, both writes.
append_fileappends text to a file and creates the file if it doesn't exist.copy_filecopies a file and never overwrites. Both are markedreadOnlyHint: false. Their descriptions say they only work inside the allowed directories, but they are new ways to change files. - Most "changed" lines are format changes. The schemas moved from JSON Schema draft-07 to 2020-12,
numberlimits becameintegerwith bounds, and parameters gained descriptions. The annotations gainedidempotentHint,destructiveHintandopenWorldHint. Harmless, but you only know that after you look. - Some descriptions describe wider behaviour. In January,
read_media_filewas 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. - The reported version isn't the package version. The January package reports
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.
Pin the version, then upgrade on purpose
Pinning is one edit in the same file:
"args": ["-y", "@modelcontextprotocol/server-filesystem@2.4.0", "/Users/me/projects/demo"] My upgrade routine:
- Snapshot the version you run today.
- Snapshot the candidate version with the same command and a scratch folder.
- Run
diff. Read every added tool's description and annotations, and skim changed descriptions. - Update the version in your config, restart the client, and keep the new snapshot as the next baseline.
A diff with exit code 1 doesn't mean "don't upgrade." It means read before you upgrade.
Limit what a new tool can do in each client
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.
# 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 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.)
Checklist
- Put an explicit version on every
npx(or similar) MCP server in your config. - Keep a tool-list snapshot per server; before upgrading, diff the new version and read every added tool.
- Treat annotations like
readOnlyHintas the server's claim, not a guarantee. - Auto-approve named tools, not whole servers: specific
mcp__rules in Claude Code,enabled_toolsin Codex, a short Cursor allowlist. - Disable servers you don't use in a project.
- Re-run the diff on a schedule for servers you can't pin, such as remote ones.
Where to go next
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.

