Versioning

mctx uses versioned endpoints so subscribers can choose when to adopt updates. Each version runs as an independent deployment with its own URL.

URL Format

MCP server endpoints follow this format:

https://{slug}.mctx.ai/v{version}

Examples

Semantic Versioning

mctx servers use semantic versioning (semver):

MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

Version Components

Valid Version Examples

Invalid Version Examples

Version Detection

mctx detects new versions by comparing the version field in mctx.json against already-deployed versions:

1. You push changes to your branch
2. GitHub webhook notifies mctx
3. mctx reads mctx.json from your repository
4. If version is new, deployment is triggered
5. If version already exists, deployment is skipped

Important: Changing your code without bumping the version will not trigger a new deployment.

Request Routing

When a request arrives at a versioned endpoint:

1. Parse version - Dispatch worker extracts version from URL path
2. Lookup config - Retrieves version-specific config from KV (tenant:{slug}:v{version})
3. Validate auth - Checks JWT and subscription status in D1
4. Route request - Forwards to tenant worker via Workers for Platforms dispatch namespace
5. Return response - Streams response back to client

Each version routes to a completely separate worker deployment. There is no shared state between versions.

Multiple Concurrent Versions

mctx allows multiple versions to run simultaneously:

• Independent deployments - Each version is a separate Cloudflare Worker
• Separate environment variables - Version-level variables override server-level
• No shared state - Versions don't communicate with each other
• Subscriber choice - Each subscriber picks their version

Example Scenario

You have three versions deployed:

All three run concurrently. Subscribers on 1.0.0 are unaffected by changes to 2.0.0-beta.1.

Version Lifecycle States

State Transitions

New Version → Deploying → Active
                      ↓
                   Failed

Active → Deprecated → Deleted

Finding Available Versions

Via Server Info Page

Visit {slug}.mctx.ai (or {slug}-test.mctx.ai for test environment) to see:

• Latest version number
• Full version history
• Endpoint URL for each version
• Deprecation notices

Via Version Dropdown

On the server info page:

1. Select version from dropdown
2. View version-specific details
3. Copy installation instructions for that version

Via API (Subscriber Perspective)

When you call an endpoint, the MCP initialize response includes the version:

{
  "jsonrpc": "2.0",
  "result": {
    "protocolVersion": "2025-11-25",
    "serverInfo": {
      "name": "Weather API",
      "version": "1.0.0"
    },
    "capabilities": {}
  },
  "id": 1
}

Version Compatibility Guidance

For subscribers choosing which version to use:

Version Removal

Developers can remove old versions to reduce maintenance burden:

1. Navigate to server detail page
2. Select version from version history
3. Click Delete Version
4. Confirm removal

Effect:

• Version worker is deleted from dispatch namespace
• Version config is removed from KV
• Endpoint becomes unavailable (404 responses)
• Subscribers on that version lose access

Best Practice: Deprecate versions first to give subscribers warning before removal.

Deprecation

To mark a version as deprecated:

1. Navigate to server detail page
2. Select version from version history
3. Click Mark as Deprecated
4. Optionally add deprecation message

Effect:

• Version remains functional
• Deprecation notice shown on server info page
• Subscribers are notified to upgrade

Note: This feature helps communicate lifecycle without breaking existing subscribers.

Version Errors

Version Not Found (404)

Response:

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

Causes:

1. Version never deployed
2. Version was removed
3. Typo in version number

Solution: Check server info page for available versions and update your configuration.

Version Deployment Failed

Causes:

1. Invalid mctx.json schema
2. Entrypoint file not found
3. Worker code syntax error
4. Environment variable missing

Solution: Check deploy logs in dashboard for specific error messages.

Version Limits

Note: Contact support if you need higher limits.

Versioning Best Practices

For Developers

1. Follow semver strictly - Helps subscribers make upgrade decisions
2. Test before major bumps - Use pre-release versions for breaking changes
3. Document breaking changes - Clear changelog explaining what changed
4. Deprecate before removal - Give subscribers time to migrate
5. Keep LTS versions - Consider maintaining long-term support versions

For Subscribers

1. Pin to specific versions - Don't use "latest" aliases (not supported)
2. Test before upgrading - Especially for major version changes
3. Monitor for deprecations - Plan upgrades when versions are marked deprecated
4. Read changelogs - Understand what changed between versions

See Also

• mctx.json Reference - Version field specification

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