How to pin MCP server versions for Claude Code and Cursor

The Claude Code and Cursor MCP docs do not describe a setting that pins an MCP server to a version. Their examples start servers with npx -y and a bare package name. Cursor’s FAQ says npm-based servers are updated by removing and re-adding them. Here is what you can control, and where the docs stop.
What the docs say about version pinning
Checked against the Claude Code MCP page (https://code.claude.com/docs/en/mcp) and the Cursor MCP page (https://cursor.com/docs/context/mcp), both fetched 2026-11-17. Neither page documents a version field, a version range or a lockfile for an MCP server.
The Claude Code page reads to its end without a pin for package versions. The page’s only “pin” is the OAuth scopes setting: “Set oauth.scopes to pin the scopes Claude Code requests during the authorization flow.” That is not a version pin. The Cursor page has no version specifier and no pinning text. Neither page says what npx -y resolves to when it runs.
So if your rule is “this exact server version,” the MCP docs give you no field to write it in. For an npm-based server you can still pin the package itself, because the launch command is handed to npx, and npx accepts an exact version in the package specifier. That is npm’s feature, not an MCP setting, and the next sections show it.
Compare the two config formats
Both tools read the server definition from a file in the project and from a user-level location. The launch examples are the same shape, and neither example includes a version.
| Item | Claude Code | Cursor |
|---|---|---|
| Project config | .mcp.json, shared with everyone in the project through the project scope |
.cursor/mcp.json in the project |
| User config | --scope user on claude mcp add |
~/.cursor/mcp.json in your home directory |
| Stdio launch example in the docs | npx -y airtable-mcp-server, no version |
"command": "npx" with "args": ["-y", "mcp-server"], no version |
| Environment variable syntax | Expands in command, args, env, url and headers (shown below) |
Resolves in command, args, env, url and headers (shown below) |
| Documented version field | None | None |
| Documented update path | None. The page says a server can change its tools while connected | Remove, clear the npm cache, re-add |
Pin the package in the launch command
npm’s npx takes a package name with an optional @version after it. The synopsis is on the npm docs page at https://docs.npmjs.com/cli/v11/commands/npx, which the session could not fetch on 2026-11-17, so check the synopsis against that page before publishing. A bare name takes whatever version resolves. A name with an exact version, such as @example/[email protected], names that release. Replace 1.2.3 with the release you reviewed and @example/mcp-server with your server’s package. These are illustrations of npm’s syntax. Neither MCP page documents version pinning, and we did not run these examples in either client.
claude mcp add example --env API_KEY=your-key -- npx -y @example/[email protected]
{
"mcpServers": {
"my-server": {
"command": "npx",
"args": ["-y", "@example/[email protected]"],
"env": {
"API_KEY": "${env:api-key}"
}
}
}
}
An exact version only fixes the package you name. It does not fix that package’s own dependencies, so a reviewer should still record what was approved, as the next section describes.
Use the launch command the docs show
- Add the server with the full launch command after
--. The Claude Code page says the double dash keeps flags such as-yaway from Claude Code’s own options. Anything after--goes to the server command untouched.
claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server
- Put the same command in the project file, so teammates and reviewers see the same launch line. In Cursor that file is
.cursor/mcp.json. The docs show the stdio shape withcommand,argsandenv.
{
"mcpServers": {
"my-server": {
"command": "npx",
"args": ["-y", "mcp-server"],
"env": {
"API_KEY": "${env:api-key}"
}
}
}
}
- Keep credentials as references, not literal values. Cursor’s FAQ says to “Use environment variables for secrets, never hardcode them.” Claude Code’s page expands variables in
command,args,env,urlandheaders, in two forms. The${VAR:-default}form falls back to the default only when the variable is unset. The page also warns that an empty string counts as set, so the default does not apply.
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": {
"Authorization": "Bearer ${API_KEY}"
}
- Record the server version you reviewed next to the config, in the same change that adds or edits it. This is our recommendation, not a documented feature. The docs fetched for this post do not describe either tool reading that record, so it only tells reviewers what was approved.
What the docs say about updates
Cursor’s FAQ gives the only update procedure in the fetched pages. For an npm-based server, it says to do three things, in order.
- “Remove the server from Customize”
- “Clear npm cache: npm cache clean –force”
- “Re-add the server to get the latest version”
npm cache clean --force
The FAQ says custom servers are different: “update your local files and restart Cursor.” It does not say which version a re-add picks beyond “the latest version,” and it does not describe pinning.
Claude Code’s page covers a different kind of change. An MCP server “can change the tools, prompts, or resources it offers while connected and send a list_changed notification.” In an interactive terminal session, Claude Code fetches the updated list, so you don’t need to reconnect. The page does not link this to a package update.
The client runtime selector
Claude Code documents a runtime selection. Set MCP_SDK_GENERATION to v1 or v2 to choose the MCP client runtime yourself. The v1 runtime uses MCP TypeScript SDK 1.x. The v2 runtime uses SDK 2.0 and adds MCP protocol revision 2026-07-28. Claude Code “picks a runtime each time you start it and keeps it until you exit.”
This is a runtime selector, not a version pin. It does not fix any server’s package, tools or version. The fetched Cursor page has no equivalent setting.
Where the docs stop
- Neither page has a version field, version range or lockfile for an MCP server. Pinning works only through the package specifier in the launch command, which is
npxbehavior. The Claude Code page mentions lock files only for shutdown: “If your server saves state or removes lock files at shutdown, handle the signal for your platform.” - The Claude Code page has no
uvxexample. Its onlyuvxmention is in a section heading. - GitHub’s Dependabot options reference describes
versioning-strategyas “Define how Dependabot should edit manifest files.” It lists npm among the supported ecosystems. Itslockfile-onlyvalue is “Only create pull requests to update lockfiles. Ignore any new versions that would require package manifest changes.” That covers dependencies in a repository’s manifests. The pages fetched for this post do not connect it to MCP launch commands, so treat it as a separate control.
A review checklist for MCP server versions
- Confirm the launch command in the project file matches the command you reviewed, including every argument.
- Check that each credential is a variable reference and not a literal value in the file.
- Confirm the launch command names an exact package version, for example
@example/[email protected], and record that version in the change that added the server. - After any update, remove and re-add the server if you use Cursor, then compare the tool list in the
/mcpview with the list you approved. - For Claude Code, check the tool list again after a
list_changednotification, since the server can change its tools while connected.
Next steps
The MCP security pillar covers controls for MCP servers as a whole. The posts on restricting which MCP servers Claude Code can use and on allowlisting MCP servers in Cursor cover the allow side. The MCP security checklist for enterprises lists the controls in one place. Product details are on the AIControls download page.
Frequently asked questions
Is there a setting to pin an MCP server version in Claude Code?
Not in the Claude Code MCP documentation fetched for this post. The page covers where servers are configured, the command, args and env fields, and environment variable expansion. It documents no version field, version range or lockfile for a server. Its only 'pin' is the OAuth scopes setting. MCP_SDK_GENERATION selects the client runtime, not a server version. Check the current docs before you rely on this answer.
Is there a setting to pin an MCP server version in Cursor?
Not in the Cursor MCP documentation fetched on 2026-11-17. The page describes .cursor/mcp.json in a project and ~/.cursor/mcp.json in your home directory, with command, args, env, url and headers fields, and shows no version field. For npm-based servers, the FAQ says to remove the server, clear the npm cache and re-add it to get the latest version. It does not describe pinning.
Does npx -y lock an MCP server to a version?
The fetched pages do not say. The Claude Code page shows npx -y with a bare package name and explains that flags after the double dash go to the server command. The Cursor page shows npx -y with a bare package name too, and does not explain what -y does. Neither page describes how npx chooses a version. Confirm the resolved version in your own environment before you treat a reviewed version as fixed.
Can an MCP server change its tools after you review it?
The Claude Code docs say an MCP server can change the tools, prompts or resources it offers while connected, and send a list_changed notification. In an interactive terminal session, Claude Code fetches the updated list without a reconnect. The docs do not tie this behavior to a package version, so compare the tool list with the /mcp command after any change.