Route agent MCP parent via query param

packages/server/src/server/agent/providers/claude-agent.ts

@@ -231,6 +231,17 @@ const DEFAULT_AGENT_CONTROL_MCP: AgentControlMcpConfig = {
   },
 };
 
+function appendCallerAgentId(url: string, agentId: string): string {
+  try {
+    const parsed = new URL(url);
+    parsed.searchParams.set("callerAgentId", agentId);
+    return parsed.toString();
+  } catch {
+    const separator = url.includes("?") ? "&" : "?";
+    return `${url}${separator}callerAgentId=${encodeURIComponent(agentId)}`;
+  }
+}
+
 export function extractUserMessageText(
   content: string | ClaudeContentChunk[]
 ): string | null {
@@ -690,16 +701,14 @@ class ClaudeAgentSession implements AgentSession {
 
     // Always include the agent-control MCP server so agents can launch other agents
     const agentControlConfig = this.agentControlMcp ?? DEFAULT_AGENT_CONTROL_MCP;
-    // Merge base headers with the caller agent ID header for parent-child relationships
+    const agentControlUrl = this.managedAgentId
-    const agentControlHeaders: Record<string, string> = {
+      ? appendCallerAgentId(agentControlConfig.url, this.managedAgentId)
-      ...agentControlConfig.headers,
+      : agentControlConfig.url;
-      ...(this.managedAgentId ? { "X-Caller-Agent-Id": this.managedAgentId } : {}),
-    };
     const defaultMcpServers: Record<string, ClaudeMcpServerConfig> = {
       "agent-control": {
         type: "http",
-        url: agentControlConfig.url,
+        url: agentControlUrl,
-        ...(Object.keys(agentControlHeaders).length > 0 ? { headers: agentControlHeaders } : {}),
+        ...(agentControlConfig.headers ? { headers: agentControlConfig.headers } : {}),
       },
       playwright: {
         type: "stdio",

packages/server/src/server/index.ts

@@ -185,8 +185,14 @@ async function main() {
           });
           return;
         }
-        // Extract caller agent ID from header (sent by agents when connecting)
+        // Extract optional caller agent ID from query string (sent by agents when connecting)
-        const callerAgentId = req.header("X-Caller-Agent-Id");
+        const callerAgentIdRaw = req.query.callerAgentId;
+        const callerAgentId =
+          typeof callerAgentIdRaw === "string"
+            ? callerAgentIdRaw
+            : Array.isArray(callerAgentIdRaw)
+              ? callerAgentIdRaw[0]
+              : undefined;
         transport = await createAgentMcpTransport(callerAgentId);
       }