Skip to content

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:

Shell

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 xmcp to the current release
  • adds the @xmcp-dev/compiler development dependency that runs xmcp dev and xmcp build
  • moves zod to ^4.0.0 when it is older
  • removes swc-loader, which xmcp no longer uses
  • raises engines.node to >=22.12 when your package.json sets 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.

OptionBehavior
--dry-runPrints the planned package.json changes without writing them
--no-installUpdates package.json and skips installing dependencies

The command never asks for input, so it also works in CI and in coding agents.

Why old projects stay on 0.x

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 dev and xmcp build need @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.
  • InferSchema types 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, and src/resources folders must exist (after 0.2.1). Create the missing folder, or disable it with paths in xmcp.config.ts (see below).
  • The webpack option is now bundler and receives Rspack options (since 0.5.0). Rename the option. See Bundler.
  • experimental.oauth was removed (since 0.6.0). Use an authentication plugin.
  • @modelcontextprotocol/sdk is 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). Return inputRequired() instead.
  • src/skills is loaded as agent skills (since 1.10.0). If that folder holds something else, set paths.skills to false. See Skills.
  • Deep imports such as xmcp/src/... are no longer published (since 0.7.1). Import from xmcp.
  • jose is an optional peer of the Cloudflare JWT middleware (1.x). Install jose if you import the JWT middleware from xmcp/cloudflare.
  • Client helpers only advertise sampling, elicitation, and roots when you pass handlers (since 1.12.0). Pass handlers to createHTTPClient or createSTDIOClient if you relied on them.

Projects scaffolded with 0.2.x have no src/resources folder. Disable it in your configuration:

xmcp.config.ts

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:

Shell

Then remove swc-loader if it is in your package.json, and work through the breaking changes above.

Check the result

Shell

If the build passes, start the server as before and test a tool from your MCP client.

One framework to rule them all