App Versioning

mctx supports four URL patterns for connecting to a versioned App. You can pin to an exact version for reproducible results, float within a major or minor version for stability, or always connect to the latest version. No other MCP hosting platform does this.

How Version Resolution Works

Every connection to an mctx-hosted App goes through the dispatch layer at https://{slug}.mctx.ai. When you connect, the dispatch layer:

1. Resolves your URL pattern to a specific semantic version
2. Locks the session to that resolved version
3. Returns the resolved version in the X-MCP-Version response header

This means mid-session deploys have no effect on your active connection. If a developer deploys v1.2.4 while you're connected to v1.2.3, your session continues on v1.2.3 until you reconnect.

Version URL Patterns

Exact Version

Connect to a specific version and never move.

https://{slug}.mctx.ai/v1.2.3

Use this for:

• CI/CD pipelines where reproducible results matter
• Automated testing with known behavior
• Applications that have been validated against a specific version

curl -X POST https://my-app.mctx.ai/v1.2.3 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Major Version

Connect to the latest version within a major release (e.g., 1.x.x).

https://{slug}.mctx.ai/v1

Use this for:

• Production agents where you want stability within a major line
• Integrations that expect compatible changes within the same major version
• Staying current without tracking every patch

curl -X POST https://my-app.mctx.ai/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

When you connect with /v1, the session resolves to the latest 1.x.x version available at that moment and stays there for the duration of the session.

Minor Version

Connect to the latest patch within a minor release (e.g., 1.2.x).

https://{slug}.mctx.ai/v1.2

Use this for:

• Staying on a known-good minor version while patches are applied
• Gradual migration when you want to control which minor version you're on
• Use cases where minor releases contain breaking changes

curl -X POST https://my-app.mctx.ai/v1.2 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Versionless (Latest)

Connect to the latest live version, resolved at session start.

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

Use this for:

• Interactive development where you always want the newest tools and capabilities
• Exploring a server's current feature set
• Situations where version stability is not a concern

curl -X POST https://my-app.mctx.ai/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Response Headers

Every response includes two version headers:

Checking Your Connected Version

To see which version you are connected to, inspect the response headers:

curl -s -D - -X POST https://my-app.mctx.ai/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | grep -i "x-mcp"

Example output:

X-MCP-Version: 1.2.3
X-MCP-Latest-Version: 1.3.0

Detecting Available Updates

When X-MCP-Latest-Version differs from X-MCP-Version, a newer version is available. You can use this to notify users or automate reconnection logic in your integration.

MCP_VERSION=$(curl -s -I -X POST https://my-app.mctx.ai/v1.2 \
  -H "Authorization: Bearer $TOKEN" \
  | grep -i "x-mcp-version:" | awk '{print $2}' | tr -d '\r')

MCP_LATEST=$(curl -s -I -X POST https://my-app.mctx.ai/v1.2 \
  -H "Authorization: Bearer $TOKEN" \
  | grep -i "x-mcp-latest-version:" | awk '{print $2}' | tr -d '\r')

if [ "$MCP_VERSION" != "$MCP_LATEST" ]; then
  echo "A newer version ($MCP_LATEST) is available. Currently on $MCP_VERSION."
fi

Choosing a Version Strategy

For Claude Desktop Users

When you install an App from mctx, the dashboard shows an installation command like:

claude mcp add --transport http my-app https://my-app.mctx.ai/v1

The version in this command determines your resolution strategy. Change /v1 to /v1.2.3 if you want to pin to an exact release, or remove the version entirely for always-latest.

For Developers Building Integrations

If you are building an integration on top of an mctx-hosted server:

• Use exact versions in production — Your users should get consistent behavior regardless of when the developer deploys updates.
• Use major versions in pre-production — Pick up fixes and improvements without chasing every patch release.
• Document which version your integration targets — Tell your users what version behavior to expect.

For CI/CD Pipelines

Pin to an exact version in your pipeline configuration:

# Example: GitHub Actions workflow
env:
  MCP_SERVER_URL: https://my-app.mctx.ai/v1.2.3

steps:
  - name: Run MCP tests
    run: |
      curl -X POST $MCP_SERVER_URL \
        -H "Authorization: Bearer ${{ secrets.MCP_TOKEN }}" \
        -H "Content-Type: application/json" \
        -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

When the developer releases a new version, deliberately update the pinned version in your pipeline after validating compatibility.

Session Behavior

Once a version is resolved at session start, it stays fixed for the duration of that connection. This protects you from unexpected behavior mid-session:

• New deploys don't affect active sessions — If v1.3.0 ships while you're on v1.2.3, you continue on v1.2.3.
• Version is resolved per connection — Each new connection re-resolves. If you reconnect after a deploy, you get the latest version matching your URL pattern.
• Partial versions resolve greedily — /v1 resolves to the highest live 1.x.x version at connect time.

Troubleshooting

Connected to an older version than expected

Check X-MCP-Version in the response headers. If it shows an older version than you expect, confirm:

1. The developer has deployed the version you want — contact the server developer if unsure.
2. Your URL pattern is broad enough to pick up that version — /v1.2.3 will never resolve to v1.3.0.
3. You are not in a cached session — disconnect and reconnect to re-resolve.

Cannot connect to a specific version

If your request returns a 404 for a specific version like /v1.2.3, that version is not currently live. Possible causes:

• The version was never deployed
• The version was replaced by a newer patch and the older version is no longer active

Use /v1.2 or /v1 to connect to the latest available version within that line.

Version header missing from response

The X-MCP-Version header is present on all valid MCP responses from mctx. If it is missing, the request may have been blocked before reaching the MCP layer (authentication failure, rate limit, etc.). Check the response status code and body for error details.

Related Documentation

• How Authentication Works — OAuth 2.0 authentication flow
• Platform Requirements — Prerequisites for keeping your server live
• Building MCP Servers — Guide for deploying your first server

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