JuliusBrussee/caveman · error · Error

${a.display_name} MCP changes require the ownership transact

Error message

${a.display_name} MCP changes require the ownership transaction

What it means

Consistency guard in the MCP uninstall/install flow: the named agent's MCP config cannot be modified through the requested code path because the change must go through the owned-config transaction (journal + atomic replace). It fires when a code path attempts a direct mutation that would bypass ownership tracking.

Source

Thrown at packages/cli/src/index.ts:10678

function uninstallMcpForAgent(a: AgentProfile, serverName = "caveman"): boolean {
  switch (a.id) {
    case "claude": {
      const claude = which("claude");
      if (!claude) return true; // agent itself is gone; dropping the marker is all that's left
      try {
        execPortableIgnore(claude, ["mcp", "remove", serverName]);
      } catch {
        // not registered — fine, still a successful uninstall.
      }
      return true;
    }
    case "codex":
      return removeMcpCodexToml(serverName);
    case "opencode":
      return removeMcpJson(join(homedir(), ".config", "opencode", "opencode.json"), ["mcp", serverName]);
    case "kilo":
    case "qwen":
      throw new Error(`${a.display_name} MCP changes require the ownership transaction`);
    case "gemini":
      return removeMcpJson(join(homedir(), ".gemini", "settings.json"), ["mcpServers", serverName]);
    case "hermes":
      return removeMcpHermesYaml(serverName);
    case "openclaw":
      return uninstallMcpOpenClaw(serverName);
    default:
      return false;
  }
}

// removeMcpCodexToml drops the exact [mcp_servers.<name>] block mcpInstall wrote
// (header + its command/args lines, up to the next section or EOF).
function removeMcpCodexToml(serverName = "caveman"): boolean {
  const path = join(homedir(), ".codex", "config.toml");
  let existing = "";
  try {
    existing = readFileSync(path, "utf8");

View on GitHub (pinned to 5184b3d11a)

Solutions

1. Route the change through transactOwnedMcpConfig so the config write and ownership journal commit atomically
2. If calling programmatically, use the install/uninstall API that performs the transaction instead of raw config edits
3. Manually restore a consistent state (remove both the registration and its ownership marker) before re-running the managed install

When it happens

Trigger: Thrown at packages/cli/src/index.ts:10678 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of JuliusBrussee/caveman@5184b3d11a (2026-09-06). Data as JSON: /api/errors/924d223b2dda794b. Report an issue: GitHub.