MCP Version Mismatch Handling

How the MCP server handles solutions created with a different FrameworX version, and how to point an MCP client at a specific installed version.

AI Integration → MCP SDK Reference → MCP Version Mismatch Handling

Compatibility Baselines

Two facts drive every routing decision:

• 10.1.0 through 10.1.4 are patch releases of the same baseline. They are interchangeable — any 10.1.x Designer in this range can open any 10.1.0-10.1.4 solution. Crossing inside the baseline does not require a prompt or an explicit upgrade.
• 10.1.5 introduces a new baseline. Crossing from 10.1.0-10.1.4 into 10.1.5 is an explicit upgrade (schema migration + backup). Crossing the other way is not possible — 10.1.5 solutions cannot be opened by a 10.1.4 Designer.

Legacy 9.2 and earlier (.tproj) solutions are out of scope for MCP. Use Solution Center to upgrade them first.

Routing Outcomes

When open_solution (DesignerMCP / ConsoleMCP) or open_workspace (ConsoleMCP) is called, the MCP server reads the solution's ProductVersion and compares it to the running server's version. One of three outcomes applies.

Prompt-Upgrade Response Format

When the server returns Prompt upgrade, the response is success-shape JSON (not an error) so the LLM can present the options in chat rather than fail the turn:

{
  "success": false,
  "versionMismatch": true,
  "solutionVersion": "fx-10.1.4",
  "runningVersion": "fx-10.1.5",
  "solutionName": "Demo",
  "message": "Solution 'Demo' was created with version fx-10.1.4. This MCP server is running version fx-10.1.5.",
  "options": [
    {
      "option": "upgrade",
      "description": "Upgrade the solution from fx-10.1.4 to fx-10.1.5. A backup will be created automatically. To proceed, call open_solution again — the upgrade happens automatically."
    },
    {
      "option": "use_older_version",
      "description": "Keep the solution at version fx-10.1.4. The user must change their MCP server configuration to point to the older version's DesignerMCP: C:\\Program Files\\Tatsoft\\FrameworX\\fx-10.1.4\\net8.0\\DesignerMCP.dll"
    }
  ]
}

LLM retry semantics

If the user accepts the upgrade, the LLM calls open_solution a second time for the same solution. The server remembers that the version mismatch has already been surfaced for that solution name and bypasses the check on the retry — the second call proceeds directly into the normal open flow, which creates the versioned backup and migrates the schema transparently.

The bypass is per-solution-name and applies only to PromptUpgrade. The VERSION_NEWER outcome is not bypassed on retry: a solution that requires a newer product version cannot be opened no matter how many times the LLM is asked, so the server keeps refusing until the product is updated.

Pointing an MCP Client at a Specific Installed Version

When the user chooses use_older_version, the fix is in the MCP client configuration — not in FrameworX. Replace the DesignerMCP.dll path with the one that matches the solution's version.

Install-Path Convention

The canonical primary install location is C:\Program Files\Tatsoft\FrameworX\fx-10\ — one flat root for the currently active FrameworX install. The MCP DLLs live in a TFM subfolder under that root, named after the .NET target framework.

This is the path used in every other MCP setup page on docs.tatsoft.com — see Claude Code MCP Setup and MCP and Claude Setup. Use it for normal single-version installs of 10.1.5.

Side-by-Side Installs (Multi-Version Coexistence)

When a machine has two FrameworX versions installed concurrently (for example, 10.1.4 kept available while 10.1.5 is the day-to-day driver), the secondary version lands in a version-pinned folder named fx-10.1.4\, fx-10.1.5\, and so on. The primary install keeps the bare fx-10\ path.

The version-pinned folders exist only when their matching version is installed alongside another version. Use them only when targeting a non-primary version from an MCP client.

Example: Claude Desktop

To target 10.1.4 from Claude Desktop, edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "FrameworX-Designer": {
      "command": "dotnet",
      "args": [
        "C:\\Program Files\\Tatsoft\\FrameworX\\fx-10.1.4\\net8.0\\DesignerMCP.dll"
      ],
      "transport": "stdio"
    }
  }
}

Save the file, fully quit Claude Desktop, and relaunch. The MCP server that starts up is now the 10.1.4 server — the versionMismatch response disappears for 10.1.4 solutions.

Example: VS Code GitHub Copilot

For Copilot, edit mcp.json (Command Palette → MCP: Open User Configuration) and use the same versioned path in args:

{
  "servers": {
    "FrameworX-Designer": {
      "type": "stdio",
      "command": "dotnet",
      "args": [
        "C:\\Program Files\\Tatsoft\\FrameworX\\fx-10.1.4\\net8.0\\DesignerMCP.dll"
      ]
    }
  }
}

Restart the MCP server from MCP: List Servers after saving.

Troubleshooting

Related

• MCP SDK Reference — server surfaces, runtime requirements, and transport model.
• MCP and Claude Setup — end-to-end setup for Claude Desktop and VS Code Copilot.
• Claude Code MCP Setup — Claude Code integration, including ConsoleMCP for file-based engineering.

In this section...