Versioning

Ready to ship an update? Bump the version in package.json, push to GitHub, and mctx deploys it automatically. Your existing versions keep running -- subscribers upgrade when they're ready.

The Simple Case

{
  "version": "1.0.0"
}

Change it to 1.1.0, push, and mctx deploys a new version. Both 1.0.0 and 1.1.0 are live at the same time:

https://weather-api.mctx.ai/v1.0.0   (still running)
https://weather-api.mctx.ai/v1.1.0   (just deployed)

Every version gets its own URL, its own worker, and its own environment variables. Subscribers on v1.0.0 are completely unaffected by your v1.1.0 deploy.

How mctx Detects New Versions

mctx watches your repository. When you push:

1. GitHub sends a webhook to mctx
2. mctx reads the version field from your package.json
3. If the version is new, deployment starts automatically
4. If the version already exists, nothing happens

The key rule: no version bump, no deployment. You can push code changes all day, but if package.json still says 1.0.0, mctx won't redeploy.

Semantic Versioning

mctx uses semver. Here's when to bump each number:

Pre-release Versions

Testing something before a full release? Use pre-release tags:

{
  "version": "2.0.0-beta.1"
}

Pre-release versions deploy and get their own URL just like any other version. They're useful for letting a few subscribers test breaking changes before you commit to them.

Valid pre-release examples: 1.0.0-alpha, 1.0.0-beta.1, 1.0.0-rc.2

What Makes a Valid Version

Running Multiple Versions

All your deployed versions run at the same time. Each one is an independent Cloudflare Worker with its own URL, environment variables, and isolated state.

A typical server might look like this:

Subscribers pick their version when they subscribe. By default, they use the versionless URL and always connect to your latest deployed version automatically.

Version Modes

mctx supports four URL patterns, giving subscribers control over how much auto-upgrade risk they accept.

Versionless URL (recommended default)

The versionless URL has no version segment at all:

https://weather-api.mctx.ai

When a subscriber connects, the dispatch worker resolves to the latest version you have deployed and routes the session there. If you deploy a new version later, new sessions connect to the new version automatically. Existing sessions stay on the version they resolved to when they connected.

This is the recommended default for most subscribers. It removes the need to update configuration after every deploy.

Partial version specifiers

Partial specifiers let subscribers pin to a compatibility tier while still receiving updates within that tier.

https://weather-api.mctx.ai/v1        # Latest 1.x.x
https://weather-api.mctx.ai/v1.2      # Latest 1.2.x

These are useful when a subscriber wants patch fixes automatically but wants to review minor or major releases first.

Exact version URL

The exact URL (/v1.2.3) is the most conservative option. The session always connects to that specific version, regardless of what you deploy afterward.

https://weather-api.mctx.ai/v1.2.3   # Always version 1.2.3

Session behavior

Once a session is established, the connection stays on the resolved version for the lifetime of that session. If you deploy a new version while a subscriber is connected, their current session is unaffected.

To connect to a newer version, the subscriber must start a new session. With most MCP clients, this means removing and re-adding the server, or using the client's reconnect option.

Mid-session deploys with partial specifiers: If a subscriber uses /v1 and you deploy 1.3.0 while they have an active session, their current session remains on whatever version it resolved to when it connected. The new version becomes available on the next new session.

Deprecating a Version

When you want subscribers to move off an old version:

1. Go to your server detail page
2. Select the version from Version History
3. Click Mark as Deprecated
4. Optionally add a message explaining why

The version keeps working, but subscribers see a deprecation notice on your server info page. This is the polite way to signal "please upgrade" without breaking anyone.

Removing a Version

When a version has served its purpose:

1. Go to your server detail page
2. Select the version
3. Click Delete Version

The version's worker gets deleted, its endpoint returns 404, and subscribers on that version lose access. Always deprecate first to give people time to migrate.

Checking Available Versions

Your server info page at {slug}.mctx.ai lists all live versions, their endpoints, and any deprecation notices.

The version dropdown on the server info page lets visitors select a version and copy the installation instructions for it.

The MCP initialize response includes the version, so clients always know what they're connected to:

{
  "jsonrpc": "2.0",
  "result": {
    "serverInfo": {
      "name": "Weather API",
      "version": "1.0.0"
    },
    "capabilities": {}
  },
  "id": 1
}

Troubleshooting

I pushed code but nothing deployed

mctx only deploys when the version number changes. Bump the version field in package.json and push again.

Version Not Found (404)

{
  "error": {
    "code": -32001,
    "message": "Version not found",
    "data": {
      "requestedVersion": "1.0.0",
      "availableVersions": ["1.1.0", "2.0.0"]
    }
  }
}

The version was never deployed, was already removed, or has a typo. Check your server info page for available versions.

Deployment failed

Check the deploy logs in your dashboard. Common causes:

• Invalid package.json (run validation locally first)
• Main file doesn't exist at the specified path
• Syntax error in your worker code
• Missing required environment variable

Limits

Reasonable limits on concurrent live versions apply. If you need to discuss specific scale requirements, contact support.

See Also

• package.json Configuration - Where the version field lives

See something wrong? Report it or suggest an improvement — your feedback helps make these docs better.