{"record":{"id":"153f4bea7b056507","repo":"JuliusBrussee/caveman","slug":"could-not-install-caveman-cloud-mcp-for-agent","errorCode":null,"errorMessage":"could not install caveman-cloud MCP for ${agent}","messagePattern":"could not install caveman-cloud MCP for (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/index.ts","lineNumber":2691,"sourceCode":"    exact_shape: keys.length === 2 && keys[0] === \"args\" && keys[1] === \"command\",\n  };\n}\n\nfunction agentNativeCloudMcpMatches(agent: \"claude\" | \"codex\", mcp: { command: string; args: string[] }): boolean {\n  if (agent === \"codex\") return codexMcpRegistrationMatches(\"caveman-cloud\", mcp);\n  const actual = claudeMcpRegistration(\"caveman-cloud\");\n  return actual.present && actual.exact_shape && actual.command === mcp.command && JSON.stringify(actual.args) === JSON.stringify(mcp.args);\n}\n\nfunction installAgentNativeCloudMcp(agent: \"claude\" | \"codex\", mcp: { command: string; args: string[] }): void {\n  if (agentNativeCloudMcpMatches(agent, mcp)) {\n    writeMcpServerMarker(agent, \"caveman-cloud\", mcp, \"caveman_context\");\n    return;\n  }\n  const installed = agent === \"claude\"\n    ? installMcpJson(claudeGlobalConfigPath(), [\"mcpServers\", \"caveman-cloud\"], { command: mcp.command, args: mcp.args })\n    : installMcpForAgent(findAgent(agent)!, mcp, \"caveman-cloud\");\n  if (!installed) throw new Error(`could not install caveman-cloud MCP for ${agent}`);\n  writeMcpServerMarker(agent, \"caveman-cloud\", mcp, \"caveman_context\");\n}\n\nfunction uninstallAgentNativeCloudMcp(agent: \"claude\" | \"codex\"): void {\n  const removed = agent === \"claude\"\n    ? removeMcpJson(claudeGlobalConfigPath(), [\"mcpServers\", \"caveman-cloud\"])\n    : uninstallMcpForAgent(findAgent(agent)!, \"caveman-cloud\");\n  if (!removed) throw new Error(`could not remove caveman-cloud MCP for ${agent}`);\n  try { unlinkSync(mcpServerMarkerPath(agent, \"caveman-cloud\")); } catch (error) {\n    if ((error as NodeJS.ErrnoException).code !== \"ENOENT\") throw error;\n  }\n}\n\nfunction agentNativeSkillFiles(agent: \"claude\" | \"codex\"): Array<{ name: string; file: string; body: string }> {\n  const names = AGENT_SKILL_SUITES[\"agent-native\"] ?? [];\n  const root = agent === \"claude\" ? join(claudeConfigDir(), \"skills\") : join(codexHomeDir(), \"skills\");\n  return names.map((name) => ({ name, file: join(root, name, \"SKILL.md\"), body: SKILLS[name]! }));\n}","sourceCodeStart":2673,"sourceCodeEnd":2709,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/cli/src/index.ts#L2673-L2709","documentation":"installAgentNativeCloudMcp tries to register the caveman-cloud MCP server for the target agent ('claude' via the global MCP JSON config, 'codex' via installMcpForAgent). If the agent-specific installer reports it could not write the config, this error is thrown before the success marker is written.","triggerScenarios":"installMcpJson(claudeGlobalConfigPath(), ...) or installMcpForAgent(findAgent(agent)!, ...) returns false — typically because the agent config file could not be written/parsed/updated, or findAgent(agent) could not resolve the agent installation.","commonSituations":"Claude/Codex config file (e.g. claude_desktop_config.json) malformed or read-only; agent CLI not installed so findAgent fails; config directory missing or read-only.","solutions":["Verify the agent (claude/codex) is installed and discoverable by the CLI.","Check the agent's global config file for invalid JSON and fix or regenerate it.","Fix permissions on the agent config file/directory.","Run the agent once to create its config, then retry the MCP install."],"exampleFix":"// before: claude_desktop_config.json is invalid JSON\n// after\nmv claude_desktop_config.json claude_desktop_config.json.bak\nclaude --version   # regenerates config\ncaveman install   # retry MCP registration","handlingStrategy":"validation","validationCode":"const cfgPath = claudeGlobalConfigPath();\nif (!existsSync(cfgPath)) throw new Error(`run claude once to create ${cfgPath}`);\nJSON.parse(readFileSync(cfgPath, 'utf8')); // throws on malformed config\n","typeGuard":null,"tryCatchPattern":"try { setupCloudMcp('claude') } catch (e) { if (String(e.message).startsWith('could not install caveman-cloud MCP')) { fixAgentConfig(); setupCloudMcp('claude'); } }","preventionTips":["Install the target agent CLI before registering MCP servers for it.","Keep agent config files valid JSON — validate after hand edits.","Ensure the agent config directory is writable by the installing user."],"tags":["mcp","config","claude","codex","install"],"backgroundTag":"config-write-failed","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}