{"record":{"id":"68c7930e49b855fb","repo":"thedotmack/claude-mem","slug":"transport","errorCode":"transport","errorMessage":"${toolName} requires CLAUDE_MEM_RUNTIME=server. Current runtime is \"worker\"; use the existing search/timeline/get_observations tools for worker-mode memory access.","messagePattern":"(.+?) requires CLAUDE_MEM_RUNTIME=server\\. Current runtime is \"worker\"; use the existing search/timeline/get_observations tools for worker-mode memory access\\.","errorType":"exception","errorClass":"ServerClientError","httpStatus":null,"severity":"error","filePath":"src/servers/mcp-server.ts","lineNumber":207,"sourceCode":"      text: `Tool error: ${error instanceof Error ? error.message : String(error)}`,\n    }],\n    isError: true as const,\n  };\n}\n\nfunction formatJsonResult(payload: unknown): { content: Array<{ type: 'text'; text: string }> } {\n  return {\n    content: [{\n      type: 'text' as const,\n      text: JSON.stringify(payload, null, 2),\n    }],\n  };\n}\n\nfunction requireServerForObservationTool(toolName: string): ServerAvailable {\n  const resolution = resolveServerToolContext();\n  if (!resolution) {\n    throw new ServerClientError(\n      'transport',\n      `${toolName} requires CLAUDE_MEM_RUNTIME=server. Current runtime is \"worker\"; use the existing search/timeline/get_observations tools for worker-mode memory access.`,\n    );\n  }\n  if (!resolution.available) {\n    throw new ServerClientError('missing_api_key', `${toolName}: ${resolution.reason}`);\n  }\n  return resolution;\n}\n\nfunction wrapHandler<Args>(\n  toolName: string,\n  execute: (args: Args) => Promise<{ content: Array<{ type: 'text'; text: string }> }>,\n): (args: Args) => Promise<{ content: Array<{ type: 'text'; text: string }>; isError?: boolean }> {\n  return async (args: Args) => {\n    try {\n      return await execute(args);\n    } catch (error) {","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/thedotmack/claude-mem/blob/d8bc9755e74915e5c3b999181e10a67c889bce2a/src/servers/mcp-server.ts#L189-L225","documentation":"requireServerForObservationTool guards server-only observation tools (like observation_add) behind runtime resolution. If resolveServerToolContext() returns nothing — meaning CLAUDE_MEM_RUNTIME is 'worker' (the default) so no server context exists — it throws a ServerClientError with code 'transport' telling the caller the tool needs CLAUDE_MEM_RUNTIME=server and pointing them to the worker-mode tools (search, timeline, get_observations) instead. This is an intentional routing error: the capability exists only in server runtime.","triggerScenarios":"Invoking a server-only MCP tool (e.g. observation_add, handleSessionStartContext's ctx resolution) while the MCP server runs with CLAUDE_MEM_RUNTIME unset or = 'worker', so resolveServerToolContext() yields no server context.","commonSituations":"User configured claude-mem in default worker mode but an agent/workflow tries the newer server-only tools; docs or prompts referencing observation_add without mentioning the runtime requirement; env var typo'd or set only in the worker process and not the MCP server process.","solutions":["Switch to server runtime: set CLAUDE_MEM_RUNTIME=server for the MCP server process and provide the required server config (API key, server URL).","If you intend to stay in worker mode, use the worker-mode tools instead: search, timeline, get_observations.","Verify the variable is exported in the environment where the MCP server itself launches (e.g. Claude Code MCP config env block), not just a shell.","After changing the runtime, restart the MCP server so resolveServerToolContext() re-reads the environment."],"exampleFix":"// before: calling server-only tool in worker mode\nobservation_add({ content: 'note' })  // ServerClientError: transport\n// after: either set CLAUDE_MEM_RUNTIME=server in the MCP server env, or in worker mode use:\nsearch({ query: 'note' })","handlingStrategy":"type-guard","validationCode":"function canUseServerObservationTools(): boolean {\n  return (process.env.CLAUDE_MEM_RUNTIME ?? '').trim() === 'server';\n}\n// call only if canUseServerObservationTools(), else use search/timeline/get_observations","typeGuard":"function isServerRuntime(env: NodeJS.ProcessEnv = process.env): boolean {\n  return (env.CLAUDE_MEM_RUNTIME ?? '').trim() === 'server';\n}","tryCatchPattern":"try {\n  ctx = requireServerForObservationTool('observation_add');\n} catch (err) {\n  if (err instanceof ServerClientError && err.code === 'transport') {\n    // fall back to worker-mode tooling (search/timeline/get_observations)\n  }\n  throw err;\n}","preventionTips":["Set CLAUDE_MEM_RUNTIME=server explicitly in the MCP server's launch config when using server-only tools.","Advertise only runtime-appropriate tools (getAdvertisedMcpToolsForRuntime) so agents never see observation_add in worker mode.","Document in agent prompts which tools require server runtime.","After runtime changes, restart the MCP server so the env is re-read."],"tags":["mcp","configuration","runtime","tools"],"backgroundTag":"missing-env-var","analyzedSha":"d8bc9755e74915e5c3b999181e10a67c889bce2a","analyzedAt":"2026-09-17T16:40:26.182Z","contentChangedAt":"2026-09-17T16:40:26.182Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}