Upgrading
Upgrade xmcp 0.x projects to 1.x with npx xmcp@latest upgrade and a list of breaking changes
For the complete documentation index, see llms.txt. Markdown variants of every page are available by appending .md to the URL.Upgrade with one command
From your project folder, run:
Use @latest. Without it, npx runs the old xmcp already installed in your
project, and 0.x versions have no upgrade command.
The command:
- sets
xmcpto the current release - adds the
@xmcp-dev/compilerdevelopment dependency that runsxmcp devandxmcp build - moves
zodto^4.0.0when it is older - removes
swc-loader, which xmcp no longer uses - raises
engines.nodeto>=22.12when yourpackage.jsonsets a lower minimum - installs dependencies with the package manager that matches your lockfile, from the workspace root in a monorepo
It then lists code changes it found but did not make. Your package.json
scripts stay the same.
| Option | Behavior |
|---|---|
--dry-run | Prints the planned package.json changes without writing them |
--no-install | Updates package.json and skips installing dependencies |
The command never asks for input, so it also works in CI and in coding agents.
A dependency like "xmcp": "^0.2.0" never installs 1.x by itself. For 0.x
versions, a caret range only allows patch releases, so reinstalling an old
project keeps installing the same 0.x version.
Breaking changes
Projects created with create-xmcp-app 0.6.x usually need no manual changes.
Projects from 0.2.x need the src/resources change below. The other items apply
only if your project uses that feature.
xmcp devandxmcp buildneed@xmcp-dev/compiler(since 0.8.0). Handled by the command.- Node.js 22.12 or newer is required (since 1.10.2). Update Node.js locally, in CI, and in your deploy target.
InferSchematypes need zod 4 (1.x). Handled by the command. See the zod 4 changelog if your schemas use APIs that changed.- The default
src/tools,src/prompts, andsrc/resourcesfolders must exist (after 0.2.1). Create the missing folder, or disable it withpathsinxmcp.config.ts(see below). - The
webpackoption is nowbundlerand receives Rspack options (since 0.5.0). Rename the option. See Bundler. experimental.oauthwas removed (since 0.6.0). Use an authentication plugin.@modelcontextprotocol/sdkis no longer installed with xmcp (since 1.0.0). Import from@modelcontextprotocol/server, or add the SDK as your own dependency.extra.elicit()throws for clients on the 2026-07-28 protocol (since 1.0.0). ReturninputRequired()instead.src/skillsis loaded as agent skills (since 1.10.0). If that folder holds something else, setpaths.skillstofalse. See Skills.- Deep imports such as
xmcp/src/...are no longer published (since 0.7.1). Import fromxmcp. joseis an optional peer of the Cloudflare JWT middleware (1.x). Installjoseif you import the JWT middleware fromxmcp/cloudflare.- Client helpers only advertise sampling, elicitation, and roots when you pass
handlers(since 1.12.0). PasshandlerstocreateHTTPClientorcreateSTDIOClientif you relied on them.
Projects scaffolded with 0.2.x have no src/resources folder. Disable it in
your configuration:
These stay the same between 0.x and 1.x: the tool, prompt, and resource file
conventions (schema, metadata, default export), InferSchema,
ToolMetadata, PromptMetadata, the http, stdio, and paths options, and
the xmcp dev and xmcp build scripts.
Upgrade manually
Install the runtime, the compiler, and zod with your package manager:
Then remove swc-loader if it is in your package.json, and work through the
breaking changes above.
Check the result
If the build passes, start the server as before and test a tool from your MCP client.
