From c1d6829850c894e6fc6a2b495ebc9a4ddcd480b9 Mon Sep 17 00:00:00 2001
From: Thomas Kosiewski <tk@coder.com>
Date: Wed, 17 Dec 2025 17:06:33 +0100
Subject: [PATCH 1/4] =?UTF-8?q?=F0=9F=A4=96=20feat:=20add=20HTTP/SSE=20MCP?=
 =?UTF-8?q?=20servers=20and=20usage=20telemetry?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Change-Id: I9b4ba646bded38efa160d25e5d4514db2350c06c
Signed-off-by: Thomas Kosiewski <tk@coder.com>
---
 .../sections/ProjectSettingsSection.tsx       | 243 ++++++--
 src/common/orpc/schemas/mcp.ts                | 123 +++-
 src/common/orpc/schemas/telemetry.ts          |  76 +++
 src/common/telemetry/payload.ts               |  76 +++
 src/common/types/mcp.ts                       |  34 +-
 src/node/orpc/router.ts                       | 232 +++++++-
 src/node/services/aiService.ts                |  65 ++-
 src/node/services/mcpConfigService.test.ts    |  60 +-
 src/node/services/mcpConfigService.ts         | 179 +++++-
 src/node/services/mcpServerManager.ts         | 547 +++++++++++++++---
 src/node/services/serviceContainer.ts         |   1 +
 11 files changed, 1423 insertions(+), 213 deletions(-)

diff --git a/src/browser/components/Settings/sections/ProjectSettingsSection.tsx b/src/browser/components/Settings/sections/ProjectSettingsSection.tsx
index e9e8aa5dc..76ceb2aa5 100644
--- a/src/browser/components/Settings/sections/ProjectSettingsSection.tsx
+++ b/src/browser/components/Settings/sections/ProjectSettingsSection.tsx
@@ -27,7 +27,12 @@ import { createEditKeyHandler } from "@/browser/utils/ui/keybinds";
 import { Switch } from "@/browser/components/ui/switch";
 import { cn } from "@/common/lib/utils";
 import { formatRelativeTime } from "@/browser/utils/ui/dateTime";
-import type { CachedMCPTestResult, MCPServerInfo } from "@/common/types/mcp";
+import type {
+  CachedMCPTestResult,
+  MCPHeaderValue,
+  MCPServerInfo,
+  MCPServerTransport,
+} from "@/common/types/mcp";
 import { useMCPTestCache } from "@/browser/hooks/useMCPTestCache";
 import { ToolSelector } from "@/browser/components/ToolSelector";
 
@@ -185,14 +190,28 @@ export const ProjectSettingsSection: React.FC = () => {
   } = useMCPTestCache(selectedProject);
   const [testingServer, setTestingServer] = useState<string | null>(null);
 
+  interface EditableServer {
+    name: string;
+    transport: MCPServerTransport;
+    /** command (stdio) or url (http/sse/auto) */
+    value: string;
+    /** JSON string for headers (http/sse/auto only) */
+    headersJson: string;
+  }
+
   // Add form state
-  const [newServer, setNewServer] = useState({ name: "", command: "" });
+  const [newServer, setNewServer] = useState<EditableServer>({
+    name: "",
+    transport: "stdio",
+    value: "",
+    headersJson: "",
+  });
   const [addingServer, setAddingServer] = useState(false);
   const [testingNew, setTestingNew] = useState(false);
   const [newTestResult, setNewTestResult] = useState<CachedMCPTestResult | null>(null);
 
   // Edit state
-  const [editing, setEditing] = useState<{ name: string; command: string } | null>(null);
+  const [editing, setEditing] = useState<EditableServer | null>(null);
   const [savingEdit, setSavingEdit] = useState(false);
 
   // Idle compaction state
@@ -235,10 +254,10 @@ export const ProjectSettingsSection: React.FC = () => {
     void refresh();
   }, [refresh]);
 
-  // Clear new command test result when command changes
+  // Clear new-server test result when transport/value/headers change
   useEffect(() => {
     setNewTestResult(null);
-  }, [newServer.command]);
+  }, [newServer.transport, newServer.value, newServer.headersJson]);
 
   const handleRemove = useCallback(
     async (name: string) => {
@@ -314,15 +333,66 @@ export const ProjectSettingsSection: React.FC = () => {
     [api, selectedProject, cacheTestResult]
   );
 
-  const handleTestNewCommand = useCallback(async () => {
-    if (!api || !selectedProject || !newServer.command.trim()) return;
+  const parseHeadersJson = (headersJson: string): Record<string, MCPHeaderValue> | undefined => {
+    const trimmed = headersJson.trim();
+    if (!trimmed) {
+      return undefined;
+    }
+
+    const parsed: unknown = JSON.parse(trimmed);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("Headers must be a JSON object");
+    }
+
+    const out: Record<string, MCPHeaderValue> = {};
+    for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
+      if (typeof value === "string") {
+        out[key] = value;
+        continue;
+      }
+      if (value && typeof value === "object" && !Array.isArray(value)) {
+        const secret = (value as Record<string, unknown>).secret;
+        if (typeof secret === "string") {
+          out[key] = { secret };
+          continue;
+        }
+      }
+      throw new Error(`Invalid header value for ${key}`);
+    }
+
+    return out;
+  };
+
+  const serverDisplayValue = (entry: MCPServerInfo): string =>
+    entry.transport === "stdio" ? entry.command : entry.url;
+
+  const serverHeadersJson = (entry: MCPServerInfo): string => {
+    if (entry.transport === "stdio") {
+      return "";
+    }
+    return entry.headers ? JSON.stringify(entry.headers, null, 2) : "";
+  };
+
+  const handleTestNewServer = useCallback(async () => {
+    if (!api || !selectedProject || !newServer.value.trim()) return;
     setTestingNew(true);
     setNewTestResult(null);
+
     try {
+      const headers =
+        newServer.transport === "stdio" ? undefined : parseHeadersJson(newServer.headersJson);
+
       const result = await api.projects.mcp.test({
         projectPath: selectedProject,
-        command: newServer.command.trim(),
+        ...(newServer.transport === "stdio"
+          ? { command: newServer.value.trim() }
+          : {
+              transport: newServer.transport,
+              url: newServer.value.trim(),
+              headers,
+            }),
       });
+
       setNewTestResult({ result, testedAt: Date.now() });
     } catch (err) {
       setNewTestResult({
@@ -332,18 +402,29 @@ export const ProjectSettingsSection: React.FC = () => {
     } finally {
       setTestingNew(false);
     }
-  }, [api, selectedProject, newServer.command]);
+  }, [api, selectedProject, newServer.transport, newServer.value, newServer.headersJson]);
 
   const handleAddServer = useCallback(async () => {
-    if (!api || !selectedProject || !newServer.name.trim() || !newServer.command.trim()) return;
+    if (!api || !selectedProject || !newServer.name.trim() || !newServer.value.trim()) return;
     setAddingServer(true);
     setError(null);
+
     try {
+      const headers =
+        newServer.transport === "stdio" ? undefined : parseHeadersJson(newServer.headersJson);
+
       const result = await api.projects.mcp.add({
         projectPath: selectedProject,
         name: newServer.name.trim(),
-        command: newServer.command.trim(),
+        ...(newServer.transport === "stdio"
+          ? { transport: "stdio", command: newServer.value.trim() }
+          : {
+              transport: newServer.transport,
+              url: newServer.value.trim(),
+              headers,
+            }),
       });
+
       if (!result.success) {
         setError(result.error ?? "Failed to add MCP server");
       } else {
@@ -351,7 +432,7 @@ export const ProjectSettingsSection: React.FC = () => {
         if (newTestResult?.result.success) {
           cacheTestResult(newServer.name.trim(), newTestResult.result);
         }
-        setNewServer({ name: "", command: "" });
+        setNewServer({ name: "", transport: "stdio", value: "", headersJson: "" });
         setNewTestResult(null);
         await refresh();
       }
@@ -362,8 +443,13 @@ export const ProjectSettingsSection: React.FC = () => {
     }
   }, [api, selectedProject, newServer, newTestResult, refresh, cacheTestResult]);
 
-  const handleStartEdit = useCallback((name: string, command: string) => {
-    setEditing({ name, command });
+  const handleStartEdit = useCallback((name: string, entry: MCPServerInfo) => {
+    setEditing({
+      name,
+      transport: entry.transport,
+      value: serverDisplayValue(entry),
+      headersJson: serverHeadersJson(entry),
+    });
   }, []);
 
   const handleCancelEdit = useCallback(() => {
@@ -371,19 +457,30 @@ export const ProjectSettingsSection: React.FC = () => {
   }, []);
 
   const handleSaveEdit = useCallback(async () => {
-    if (!api || !selectedProject || !editing?.command.trim()) return;
+    if (!api || !selectedProject || !editing?.value.trim()) return;
     setSavingEdit(true);
     setError(null);
+
     try {
+      const headers =
+        editing.transport === "stdio" ? undefined : parseHeadersJson(editing.headersJson);
+
       const result = await api.projects.mcp.add({
         projectPath: selectedProject,
         name: editing.name,
-        command: editing.command.trim(),
+        ...(editing.transport === "stdio"
+          ? { transport: "stdio", command: editing.value.trim() }
+          : {
+              transport: editing.transport,
+              url: editing.value.trim(),
+              headers,
+            }),
       });
+
       if (!result.success) {
         setError(result.error ?? "Failed to update MCP server");
       } else {
-        // Clear cached test result since command changed
+        // Clear cached test result since config changed
         clearTestResult(editing.name);
         setEditing(null);
         await refresh();
@@ -430,8 +527,8 @@ export const ProjectSettingsSection: React.FC = () => {
   }
 
   const projectName = (path: string) => path.split(/[\\/]/).pop() ?? path;
-  const canAdd = newServer.name.trim() && newServer.command.trim();
-  const canTest = newServer.command.trim();
+  const canAdd = newServer.name.trim() && newServer.value.trim();
+  const canTest = newServer.value.trim();
 
   return (
     <div className="space-y-6">
@@ -564,21 +661,37 @@ export const ProjectSettingsSection: React.FC = () => {
                       )}
                     </div>
                     {isEditing ? (
-                      <input
-                        type="text"
-                        value={editing.command}
-                        onChange={(e) => setEditing({ ...editing, command: e.target.value })}
-                        className="border-border-medium bg-secondary/30 text-foreground placeholder:text-muted-foreground focus:ring-accent mt-1 w-full rounded-md border px-2 py-1 font-mono text-xs focus:ring-1 focus:outline-none"
-                        autoFocus
-                        spellCheck={false}
-                        onKeyDown={createEditKeyHandler({
-                          onSave: () => void handleSaveEdit(),
-                          onCancel: handleCancelEdit,
-                        })}
-                      />
+                      <div className="mt-1 space-y-2">
+                        <p className="text-muted-foreground text-xs">
+                          transport: {editing.transport}
+                        </p>
+                        <input
+                          type="text"
+                          value={editing.value}
+                          onChange={(e) => setEditing({ ...editing, value: e.target.value })}
+                          className="border-border-medium bg-secondary/30 text-foreground placeholder:text-muted-foreground focus:ring-accent w-full rounded-md border px-2 py-1 font-mono text-xs focus:ring-1 focus:outline-none"
+                          autoFocus
+                          spellCheck={false}
+                          onKeyDown={createEditKeyHandler({
+                            onSave: () => void handleSaveEdit(),
+                            onCancel: handleCancelEdit,
+                          })}
+                        />
+                        {editing.transport !== "stdio" && (
+                          <textarea
+                            value={editing.headersJson}
+                            onChange={(e) =>
+                              setEditing({ ...editing, headersJson: e.target.value })
+                            }
+                            rows={4}
+                            spellCheck={false}
+                            className="border-border-medium bg-secondary/30 text-foreground placeholder:text-muted-foreground focus:ring-accent w-full rounded-md border px-2 py-1 font-mono text-xs focus:ring-1 focus:outline-none"
+                          />
+                        )}
+                      </div>
                     ) : (
                       <p className="text-muted-foreground mt-0.5 font-mono text-xs break-all">
-                        {entry.command}
+                        {serverDisplayValue(entry)}
                       </p>
                     )}
                   </div>
@@ -589,7 +702,7 @@ export const ProjectSettingsSection: React.FC = () => {
                           variant="ghost"
                           size="icon"
                           onClick={() => void handleSaveEdit()}
-                          disabled={savingEdit || !editing.command.trim()}
+                          disabled={savingEdit || !editing.value.trim()}
                           className="h-7 w-7 text-green-500 hover:text-green-400"
                           title="Save (Enter)"
                         >
@@ -629,9 +742,9 @@ export const ProjectSettingsSection: React.FC = () => {
                         <Button
                           variant="ghost"
                           size="icon"
-                          onClick={() => handleStartEdit(name, entry.command)}
+                          onClick={() => handleStartEdit(name, entry)}
                           className="text-muted hover:text-accent h-7 w-7"
-                          title="Edit command"
+                          title="Edit server"
                         >
                           <Pencil className="h-4 w-4" />
                         </Button>
@@ -688,20 +801,66 @@ export const ProjectSettingsSection: React.FC = () => {
             />
           </div>
           <div className="space-y-1.5">
-            <label htmlFor="server-command" className="text-muted-foreground text-xs">
-              Command
+            <label className="text-muted-foreground text-xs">Transport</label>
+            <Select
+              value={newServer.transport}
+              onValueChange={(value) =>
+                setNewServer((prev) => ({
+                  ...prev,
+                  transport: value as MCPServerTransport,
+                  value: "",
+                  headersJson: "",
+                }))
+              }
+            >
+              <SelectTrigger className="w-full">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="stdio">Stdio</SelectItem>
+                <SelectItem value="http">HTTP (Streamable)</SelectItem>
+                <SelectItem value="sse">SSE (Legacy)</SelectItem>
+                <SelectItem value="auto">Auto (HTTP → SSE)</SelectItem>
+              </SelectContent>
+            </Select>
+          </div>
+
+          <div className="space-y-1.5">
+            <label htmlFor="server-value" className="text-muted-foreground text-xs">
+              {newServer.transport === "stdio" ? "Command" : "URL"}
             </label>
             <input
-              id="server-command"
+              id="server-value"
               type="text"
-              placeholder="e.g., npx -y @modelcontextprotocol/server-memory"
-              value={newServer.command}
-              onChange={(e) => setNewServer((prev) => ({ ...prev, command: e.target.value }))}
+              placeholder={
+                newServer.transport === "stdio"
+                  ? "e.g., npx -y @modelcontextprotocol/server-memory"
+                  : "e.g., http://localhost:3333/mcp"
+              }
+              value={newServer.value}
+              onChange={(e) => setNewServer((prev) => ({ ...prev, value: e.target.value }))}
               spellCheck={false}
               className="border-border-medium bg-secondary/30 text-foreground placeholder:text-muted-foreground focus:ring-accent w-full rounded-md border px-3 py-2 font-mono text-sm focus:ring-1 focus:outline-none"
             />
           </div>
 
+          {newServer.transport !== "stdio" && (
+            <div className="space-y-1.5">
+              <label htmlFor="server-headers" className="text-muted-foreground text-xs">
+                Headers (JSON)
+              </label>
+              <textarea
+                id="server-headers"
+                placeholder='e.g., {"Authorization": {"secret": "MCP_TOKEN"}}'
+                value={newServer.headersJson}
+                onChange={(e) => setNewServer((prev) => ({ ...prev, headersJson: e.target.value }))}
+                spellCheck={false}
+                rows={4}
+                className="border-border-medium bg-secondary/30 text-foreground placeholder:text-muted-foreground focus:ring-accent w-full rounded-md border px-3 py-2 font-mono text-xs focus:ring-1 focus:outline-none"
+              />
+            </div>
+          )}
+
           {/* Test result for new command */}
           {newTestResult && (
             <div
@@ -737,7 +896,7 @@ export const ProjectSettingsSection: React.FC = () => {
           <div className="flex gap-2">
             <Button
               variant="outline"
-              onClick={() => void handleTestNewCommand()}
+              onClick={() => void handleTestNewServer()}
               disabled={!canTest || testingNew}
               className="h-auto px-3 py-1.5"
             >
diff --git a/src/common/orpc/schemas/mcp.ts b/src/common/orpc/schemas/mcp.ts
index b49d5cd05..506693297 100644
--- a/src/common/orpc/schemas/mcp.ts
+++ b/src/common/orpc/schemas/mcp.ts
@@ -24,11 +24,69 @@ export const WorkspaceMCPOverridesSchema = z.object({
   toolAllowlist: z.record(z.string(), z.array(z.string())).optional(),
 });
 
-export const MCPAddParamsSchema = z.object({
-  projectPath: z.string(),
-  name: z.string(),
-  command: z.string(),
-});
+export const MCPTransportSchema = z.enum(["stdio", "http", "sse", "auto"]);
+
+export const MCPHeaderValueSchema = z.union([z.string(), z.object({ secret: z.string() })]);
+export const MCPHeadersSchema = z.record(z.string(), MCPHeaderValueSchema);
+
+export const MCPServerInfoSchema = z.discriminatedUnion("transport", [
+  z.object({
+    transport: z.literal("stdio"),
+    command: z.string(),
+    disabled: z.boolean(),
+    toolAllowlist: z.array(z.string()).optional(),
+  }),
+  z.object({
+    transport: z.literal("http"),
+    url: z.string(),
+    headers: MCPHeadersSchema.optional(),
+    disabled: z.boolean(),
+    toolAllowlist: z.array(z.string()).optional(),
+  }),
+  z.object({
+    transport: z.literal("sse"),
+    url: z.string(),
+    headers: MCPHeadersSchema.optional(),
+    disabled: z.boolean(),
+    toolAllowlist: z.array(z.string()).optional(),
+  }),
+  z.object({
+    transport: z.literal("auto"),
+    url: z.string(),
+    headers: MCPHeadersSchema.optional(),
+    disabled: z.boolean(),
+    toolAllowlist: z.array(z.string()).optional(),
+  }),
+]);
+
+export const MCPServerMapSchema = z.record(z.string(), MCPServerInfoSchema);
+
+export const MCPAddParamsSchema = z
+  .object({
+    projectPath: z.string(),
+    name: z.string(),
+
+    // Backward-compatible: if transport omitted, interpret as stdio.
+    transport: MCPTransportSchema.optional(),
+
+    command: z.string().optional(),
+    url: z.string().optional(),
+    headers: MCPHeadersSchema.optional(),
+  })
+  .superRefine((input, ctx) => {
+    const transport = input.transport ?? "stdio";
+
+    if (transport === "stdio") {
+      if (!input.command?.trim()) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "command is required for stdio" });
+      }
+      return;
+    }
+
+    if (!input.url?.trim()) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, message: "url is required for http/sse/auto" });
+    }
+  });
 
 export const MCPRemoveParamsSchema = z.object({
   projectPath: z.string(),
@@ -41,15 +99,6 @@ export const MCPSetEnabledParamsSchema = z.object({
   enabled: z.boolean(),
 });
 
-export const MCPServerMapSchema = z.record(
-  z.string(),
-  z.object({
-    command: z.string(),
-    disabled: z.boolean(),
-    toolAllowlist: z.array(z.string()).optional(),
-  })
-);
-
 export const MCPSetToolAllowlistParamsSchema = z.object({
   projectPath: z.string(),
   name: z.string(),
@@ -58,14 +107,46 @@ export const MCPSetToolAllowlistParamsSchema = z.object({
 });
 
 /**
- * Unified test params - provide either name (to test configured server) or command (to test arbitrary command).
- * At least one of name or command must be provided.
+ * Unified test params - provide either:
+ * - name (to test a configured server), OR
+ * - command (to test arbitrary stdio command), OR
+ * - url+transport (to test arbitrary http/sse/auto endpoint)
  */
-export const MCPTestParamsSchema = z.object({
-  projectPath: z.string(),
-  name: z.string().optional(),
-  command: z.string().optional(),
-});
+export const MCPTestParamsSchema = z
+  .object({
+    projectPath: z.string(),
+    name: z.string().optional(),
+
+    transport: MCPTransportSchema.optional(),
+    command: z.string().optional(),
+    url: z.string().optional(),
+    headers: MCPHeadersSchema.optional(),
+  })
+  .superRefine((input, ctx) => {
+    if (input.name?.trim()) {
+      return;
+    }
+
+    if (input.command?.trim()) {
+      return;
+    }
+
+    if (input.url?.trim()) {
+      const transport = input.transport;
+      if (transport !== "http" && transport !== "sse" && transport !== "auto") {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "transport must be http|sse|auto when testing by url",
+        });
+      }
+      return;
+    }
+
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "Either name, command, or url is required",
+    });
+  });
 
 export const MCPTestResultSchema = z.discriminatedUnion("success", [
   z.object({ success: z.literal(true), tools: z.array(z.string()) }),
diff --git a/src/common/orpc/schemas/telemetry.ts b/src/common/orpc/schemas/telemetry.ts
index 2865f2a48..1522ec0e0 100644
--- a/src/common/orpc/schemas/telemetry.ts
+++ b/src/common/orpc/schemas/telemetry.ts
@@ -71,6 +71,70 @@ const MessageSentPropertiesSchema = z.object({
   thinkingLevel: TelemetryThinkingLevelSchema,
 });
 
+// MCP transport mode enum (matches payload.ts TelemetryMCPTransportMode)
+const TelemetryMCPTransportModeSchema = z.enum([
+  "none",
+  "stdio_only",
+  "http_only",
+  "sse_only",
+  "mixed",
+]);
+
+const MCPContextInjectedPropertiesSchema = z.object({
+  workspaceId: z.string(),
+  model: z.string(),
+  mode: z.string(),
+  runtimeType: TelemetryRuntimeTypeSchema,
+
+  mcp_server_enabled_count: z.number(),
+  mcp_server_started_count: z.number(),
+  mcp_server_failed_count: z.number(),
+
+  mcp_tool_count: z.number(),
+  total_tool_count: z.number(),
+  builtin_tool_count: z.number(),
+
+  mcp_transport_mode: TelemetryMCPTransportModeSchema,
+  mcp_has_http: z.boolean(),
+  mcp_has_sse: z.boolean(),
+  mcp_has_stdio: z.boolean(),
+  mcp_auto_fallback_count: z.number(),
+  mcp_setup_duration_ms_b2: z.number(),
+});
+
+const TelemetryMCPServerTransportSchema = z.enum(["stdio", "http", "sse", "auto"]);
+const TelemetryMCPTestErrorCategorySchema = z.enum([
+  "timeout",
+  "connect",
+  "http_status",
+  "unknown",
+]);
+
+const MCPServerTestedPropertiesSchema = z.object({
+  transport: TelemetryMCPServerTransportSchema,
+  success: z.boolean(),
+  duration_ms_b2: z.number(),
+  error_category: TelemetryMCPTestErrorCategorySchema.optional(),
+});
+
+const TelemetryMCPServerConfigActionSchema = z.enum([
+  "add",
+  "edit",
+  "remove",
+  "enable",
+  "disable",
+  "set_tool_allowlist",
+  "set_headers",
+]);
+
+const MCPServerConfigChangedPropertiesSchema = z.object({
+  action: TelemetryMCPServerConfigActionSchema,
+  transport: TelemetryMCPServerTransportSchema,
+  has_headers: z.boolean(),
+  uses_secret_headers: z.boolean(),
+  tool_allowlist_size_b2: z.number().optional(),
+});
+
 const StreamCompletedPropertiesSchema = z.object({
   model: z.string(),
   wasInterrupted: z.boolean(),
@@ -125,6 +189,18 @@ export const TelemetryEventSchema = z.discriminatedUnion("event", [
     event: z.literal("workspace_switched"),
     properties: WorkspaceSwitchedPropertiesSchema,
   }),
+  z.object({
+    event: z.literal("mcp_context_injected"),
+    properties: MCPContextInjectedPropertiesSchema,
+  }),
+  z.object({
+    event: z.literal("mcp_server_tested"),
+    properties: MCPServerTestedPropertiesSchema,
+  }),
+  z.object({
+    event: z.literal("mcp_server_config_changed"),
+    properties: MCPServerConfigChangedPropertiesSchema,
+  }),
   z.object({
     event: z.literal("message_sent"),
     properties: MessageSentPropertiesSchema,
diff --git a/src/common/telemetry/payload.ts b/src/common/telemetry/payload.ts
index 3fe6e2260..0d4e36e55 100644
--- a/src/common/telemetry/payload.ts
+++ b/src/common/telemetry/payload.ts
@@ -108,6 +108,79 @@ export interface MessageSentPayload {
   thinkingLevel: TelemetryThinkingLevel;
 }
 
+/**
+ * MCP usage events
+ */
+export type TelemetryMCPTransportMode = "none" | "stdio_only" | "http_only" | "sse_only" | "mixed";
+
+export interface MCPContextInjectedPayload {
+  /** Workspace ID (randomly generated, safe to send) */
+  workspaceId: string;
+  /** Full model identifier */
+  model: string;
+  /** UI mode */
+  mode: string;
+  /** Runtime type for the workspace */
+  runtimeType: TelemetryRuntimeType;
+
+  /** How many servers are enabled for this workspace message */
+  mcp_server_enabled_count: number;
+  /** How many servers successfully started (client created + tools fetched) */
+  mcp_server_started_count: number;
+  /** How many enabled servers failed to start */
+  mcp_server_failed_count: number;
+
+  /** MCP tools injected into the model request */
+  mcp_tool_count: number;
+  /** Total tools injected into the model request (built-in + MCP) */
+  total_tool_count: number;
+  /** Built-in tool count injected into the model request */
+  builtin_tool_count: number;
+
+  /** Effective transport mix for enabled servers */
+  mcp_transport_mode: TelemetryMCPTransportMode;
+  /** Whether any enabled server uses HTTP (includes auto transport) */
+  mcp_has_http: boolean;
+  /** Whether any enabled server uses legacy SSE */
+  mcp_has_sse: boolean;
+  /** Whether any enabled server uses stdio */
+  mcp_has_stdio: boolean;
+
+  /** Number of servers that required auto-fallback from HTTP to SSE */
+  mcp_auto_fallback_count: number;
+
+  /** Time spent preparing MCP servers/tools (ms, rounded to nearest power of 2) */
+  mcp_setup_duration_ms_b2: number;
+}
+
+export type TelemetryMCPServerTransport = "stdio" | "http" | "sse" | "auto";
+export type TelemetryMCPTestErrorCategory = "timeout" | "connect" | "http_status" | "unknown";
+
+export interface MCPServerTestedPayload {
+  transport: TelemetryMCPServerTransport;
+  success: boolean;
+  duration_ms_b2: number;
+  /** Error category when success=false (no raw error messages for privacy) */
+  error_category?: TelemetryMCPTestErrorCategory;
+}
+
+export type TelemetryMCPServerConfigAction =
+  | "add"
+  | "edit"
+  | "remove"
+  | "enable"
+  | "disable"
+  | "set_tool_allowlist"
+  | "set_headers";
+
+export interface MCPServerConfigChangedPayload {
+  action: TelemetryMCPServerConfigAction;
+  transport: TelemetryMCPServerTransport;
+  has_headers: boolean;
+  uses_secret_headers: boolean;
+  /** Only set when action=set_tool_allowlist */
+  tool_allowlist_size_b2?: number;
+}
 /**
  * Stream completion event - tracks when AI responses finish
  */
@@ -226,6 +299,9 @@ export type TelemetryEventPayload =
   | { event: "workspace_created"; properties: WorkspaceCreatedPayload }
   | { event: "workspace_switched"; properties: WorkspaceSwitchedPayload }
   | { event: "message_sent"; properties: MessageSentPayload }
+  | { event: "mcp_context_injected"; properties: MCPContextInjectedPayload }
+  | { event: "mcp_server_tested"; properties: MCPServerTestedPayload }
+  | { event: "mcp_server_config_changed"; properties: MCPServerConfigChangedPayload }
   | { event: "stream_completed"; properties: StreamCompletedPayload }
   | { event: "compaction_completed"; properties: CompactionCompletedPayload }
   | { event: "provider_configured"; properties: ProviderConfiguredPayload }
diff --git a/src/common/types/mcp.ts b/src/common/types/mcp.ts
index 07ad64be5..2b16192ba 100644
--- a/src/common/types/mcp.ts
+++ b/src/common/types/mcp.ts
@@ -1,6 +1,10 @@
-/** Normalized server info (always has disabled field) */
-export interface MCPServerInfo {
-  command: string;
+/** Supported MCP server transports. */
+export type MCPServerTransport = "stdio" | "http" | "sse" | "auto";
+
+export type MCPHeaderValue = string | { secret: string };
+
+export interface MCPServerBaseInfo {
+  transport: MCPServerTransport;
   disabled: boolean;
   /**
    * Optional tool allowlist at project level.
@@ -10,12 +14,32 @@ export interface MCPServerInfo {
   toolAllowlist?: string[];
 }
 
+/** stdio server definition (local process). */
+export interface MCPStdioServerInfo extends MCPServerBaseInfo {
+  transport: "stdio";
+  command: string;
+}
+
+/** HTTP-based server definition. */
+export interface MCPHttpServerInfo extends MCPServerBaseInfo {
+  transport: "http" | "sse" | "auto";
+  url: string;
+  /** Optional headers (string literal or reference to a project secret key). */
+  headers?: Record<string, MCPHeaderValue>;
+}
+
+/** Normalized server info (always has disabled field). */
+export type MCPServerInfo = MCPStdioServerInfo | MCPHttpServerInfo;
+
 export interface MCPConfig {
   servers: Record<string, MCPServerInfo>;
 }
 
-/** Internal map of server name → command string (used after filtering disabled) */
-export type MCPServerMap = Record<string, string>;
+/**
+ * Internal map of server name → server info (used after filtering disabled).
+ * Values are not shown to the model; only server names are exposed.
+ */
+export type MCPServerMap = Record<string, MCPServerInfo>;
 
 /** Result of testing an MCP server connection */
 export type MCPTestResult = { success: true; tools: string[] } | { success: false; error: string };
diff --git a/src/node/orpc/router.ts b/src/node/orpc/router.ts
index 60082c367..936130f78 100644
--- a/src/node/orpc/router.ts
+++ b/src/node/orpc/router.ts
@@ -16,6 +16,8 @@ import { createAsyncMessageQueue } from "@/common/utils/asyncMessageQueue";
 
 import { createRuntime } from "@/node/runtime/runtimeFactory";
 import { readPlanFile } from "@/node/utils/runtime/helpers";
+import { secretsToRecord } from "@/common/types/secrets";
+import { roundToBase2 } from "@/common/telemetry/utils";
 import { createAsyncEventQueue } from "@/common/utils/asyncEventIterator";
 
 export const router = (authToken?: string) => {
@@ -244,37 +246,235 @@ export const router = (authToken?: string) => {
         add: t
           .input(schemas.projects.mcp.add.input)
           .output(schemas.projects.mcp.add.output)
-          .handler(({ context, input }) =>
-            context.mcpConfigService.addServer(input.projectPath, input.name, input.command)
-          ),
+          .handler(async ({ context, input }) => {
+            const existing = await context.mcpConfigService.listServers(input.projectPath);
+            const existingServer = existing[input.name];
+
+            const transport = input.transport ?? "stdio";
+            const hasHeaders = Boolean(input.headers && Object.keys(input.headers).length > 0);
+            const usesSecretHeaders = Boolean(
+              input.headers &&
+              Object.values(input.headers).some(
+                (v) => typeof v === "object" && v !== null && "secret" in v
+              )
+            );
+
+            const action = (() => {
+              if (!existingServer) {
+                return "add";
+              }
+
+              if (
+                existingServer.transport !== "stdio" &&
+                transport !== "stdio" &&
+                existingServer.transport === transport &&
+                existingServer.url === input.url &&
+                JSON.stringify(existingServer.headers ?? {}) !== JSON.stringify(input.headers ?? {})
+              ) {
+                return "set_headers";
+              }
+
+              return "edit";
+            })();
+
+            const result = await context.mcpConfigService.addServer(input.projectPath, input.name, {
+              transport,
+              command: input.command,
+              url: input.url,
+              headers: input.headers,
+            });
+
+            if (result.success) {
+              context.telemetryService.capture({
+                event: "mcp_server_config_changed",
+                properties: {
+                  action,
+                  transport,
+                  has_headers: hasHeaders,
+                  uses_secret_headers: usesSecretHeaders,
+                },
+              });
+            }
+
+            return result;
+          }),
         remove: t
           .input(schemas.projects.mcp.remove.input)
           .output(schemas.projects.mcp.remove.output)
-          .handler(({ context, input }) =>
-            context.mcpConfigService.removeServer(input.projectPath, input.name)
-          ),
+          .handler(async ({ context, input }) => {
+            const existing = await context.mcpConfigService.listServers(input.projectPath);
+            const server = existing[input.name];
+
+            const result = await context.mcpConfigService.removeServer(
+              input.projectPath,
+              input.name
+            );
+
+            if (result.success && server) {
+              const hasHeaders =
+                server.transport !== "stdio" &&
+                Boolean(server.headers && Object.keys(server.headers).length > 0);
+              const usesSecretHeaders =
+                server.transport !== "stdio" &&
+                Boolean(
+                  server.headers &&
+                  Object.values(server.headers).some(
+                    (v) => typeof v === "object" && v !== null && "secret" in v
+                  )
+                );
+
+              context.telemetryService.capture({
+                event: "mcp_server_config_changed",
+                properties: {
+                  action: "remove",
+                  transport: server.transport,
+                  has_headers: hasHeaders,
+                  uses_secret_headers: usesSecretHeaders,
+                },
+              });
+            }
+
+            return result;
+          }),
         test: t
           .input(schemas.projects.mcp.test.input)
           .output(schemas.projects.mcp.test.output)
-          .handler(({ context, input }) =>
-            context.mcpServerManager.test(input.projectPath, input.name, input.command)
-          ),
+          .handler(async ({ context, input }) => {
+            const start = Date.now();
+            const secrets = secretsToRecord(context.projectService.getSecrets(input.projectPath));
+
+            const configuredTransport = input.name
+              ? (await context.mcpConfigService.listServers(input.projectPath))[input.name]
+                  ?.transport
+              : undefined;
+
+            const transport =
+              configuredTransport ?? (input.command ? "stdio" : (input.transport ?? "auto"));
+
+            const result = await context.mcpServerManager.test({
+              projectPath: input.projectPath,
+              name: input.name,
+              command: input.command,
+              transport: input.transport,
+              url: input.url,
+              headers: input.headers,
+              projectSecrets: secrets,
+            });
+
+            const durationMs = Date.now() - start;
+
+            const categorizeError = (
+              error: string
+            ): "timeout" | "connect" | "http_status" | "unknown" => {
+              const lower = error.toLowerCase();
+              if (lower.includes("timed out")) {
+                return "timeout";
+              }
+              if (
+                lower.includes("econnrefused") ||
+                lower.includes("econnreset") ||
+                lower.includes("enotfound") ||
+                lower.includes("ehostunreach")
+              ) {
+                return "connect";
+              }
+              if (/\b(400|401|403|404|405|500|502|503)\b/.test(lower)) {
+                return "http_status";
+              }
+              return "unknown";
+            };
+
+            context.telemetryService.capture({
+              event: "mcp_server_tested",
+              properties: {
+                transport,
+                success: result.success,
+                duration_ms_b2: roundToBase2(durationMs),
+                ...(result.success ? {} : { error_category: categorizeError(result.error) }),
+              },
+            });
+
+            return result;
+          }),
         setEnabled: t
           .input(schemas.projects.mcp.setEnabled.input)
           .output(schemas.projects.mcp.setEnabled.output)
-          .handler(({ context, input }) =>
-            context.mcpConfigService.setServerEnabled(input.projectPath, input.name, input.enabled)
-          ),
+          .handler(async ({ context, input }) => {
+            const existing = await context.mcpConfigService.listServers(input.projectPath);
+            const server = existing[input.name];
+
+            const result = await context.mcpConfigService.setServerEnabled(
+              input.projectPath,
+              input.name,
+              input.enabled
+            );
+
+            if (result.success && server) {
+              const hasHeaders =
+                server.transport !== "stdio" &&
+                Boolean(server.headers && Object.keys(server.headers).length > 0);
+              const usesSecretHeaders =
+                server.transport !== "stdio" &&
+                Boolean(
+                  server.headers &&
+                  Object.values(server.headers).some(
+                    (v) => typeof v === "object" && v !== null && "secret" in v
+                  )
+                );
+
+              context.telemetryService.capture({
+                event: "mcp_server_config_changed",
+                properties: {
+                  action: input.enabled ? "enable" : "disable",
+                  transport: server.transport,
+                  has_headers: hasHeaders,
+                  uses_secret_headers: usesSecretHeaders,
+                },
+              });
+            }
+
+            return result;
+          }),
         setToolAllowlist: t
           .input(schemas.projects.mcp.setToolAllowlist.input)
           .output(schemas.projects.mcp.setToolAllowlist.output)
-          .handler(({ context, input }) =>
-            context.mcpConfigService.setToolAllowlist(
+          .handler(async ({ context, input }) => {
+            const existing = await context.mcpConfigService.listServers(input.projectPath);
+            const server = existing[input.name];
+
+            const result = await context.mcpConfigService.setToolAllowlist(
               input.projectPath,
               input.name,
               input.toolAllowlist
-            )
-          ),
+            );
+
+            if (result.success && server) {
+              const hasHeaders =
+                server.transport !== "stdio" &&
+                Boolean(server.headers && Object.keys(server.headers).length > 0);
+              const usesSecretHeaders =
+                server.transport !== "stdio" &&
+                Boolean(
+                  server.headers &&
+                  Object.values(server.headers).some(
+                    (v) => typeof v === "object" && v !== null && "secret" in v
+                  )
+                );
+
+              context.telemetryService.capture({
+                event: "mcp_server_config_changed",
+                properties: {
+                  action: "set_tool_allowlist",
+                  transport: server.transport,
+                  has_headers: hasHeaders,
+                  uses_secret_headers: usesSecretHeaders,
+                  tool_allowlist_size_b2: roundToBase2(input.toolAllowlist.length),
+                },
+              });
+            }
+
+            return result;
+          }),
       },
       idleCompaction: {
         get: t
diff --git a/src/node/services/aiService.ts b/src/node/services/aiService.ts
index 1504013d6..9c9560ab4 100644
--- a/src/node/services/aiService.ts
+++ b/src/node/services/aiService.ts
@@ -45,7 +45,9 @@ import type { PartialService } from "./partialService";
 import type { SessionUsageService } from "./sessionUsageService";
 import { buildSystemMessage, readToolInstructions } from "./systemMessage";
 import { getTokenizerForModel } from "@/node/utils/main/tokenizer";
-import type { MCPServerManager } from "@/node/services/mcpServerManager";
+import type { TelemetryService } from "@/node/services/telemetryService";
+import { getRuntimeTypeForTelemetry, roundToBase2 } from "@/common/telemetry/utils";
+import type { MCPServerManager, MCPWorkspaceStats } from "@/node/services/mcpServerManager";
 import { buildProviderOptions } from "@/common/utils/ai/providerOptions";
 import type { ThinkingLevel } from "@/common/types/thinking";
 import type {
@@ -305,6 +307,7 @@ export class AIService extends EventEmitter {
   private readonly partialService: PartialService;
   private readonly config: Config;
   private mcpServerManager?: MCPServerManager;
+  private telemetryService?: TelemetryService;
   private readonly initStateManager: InitStateManager;
   private readonly mockModeEnabled: boolean;
   private readonly mockScenarioPlayer?: MockScenarioPlayer;
@@ -340,6 +343,9 @@ export class AIService extends EventEmitter {
     }
   }
 
+  setTelemetryService(service: TelemetryService): void {
+    this.telemetryService = service;
+  }
   setMCPServerManager(manager: MCPServerManager): void {
     this.mcpServerManager = manager;
   }
@@ -1160,18 +1166,29 @@ export class AIService extends EventEmitter {
 
       // Generate stream token and create temp directory for tools
       const streamToken = this.streamManager.generateStreamToken();
+
       let mcpTools: Record<string, Tool> | undefined;
+      let mcpStats: MCPWorkspaceStats | undefined;
+      let mcpSetupDurationMs = 0;
+
       if (this.mcpServerManager) {
+        const start = Date.now();
         try {
-          mcpTools = await this.mcpServerManager.getToolsForWorkspace({
+          const result = await this.mcpServerManager.getToolsForWorkspace({
             workspaceId,
             projectPath: metadata.projectPath,
             runtime,
             workspacePath,
             overrides: mcpOverrides,
+            projectSecrets: secretsToRecord(projectSecrets),
           });
+
+          mcpTools = result.tools;
+          mcpStats = result.stats;
         } catch (error) {
           log.error("Failed to start MCP servers", { workspaceId, error });
+        } finally {
+          mcpSetupDurationMs = Date.now() - start;
         }
       }
 
@@ -1223,6 +1240,50 @@ export class AIService extends EventEmitter {
       // Apply tool policy to filter tools (if policy provided)
       const tools = applyToolPolicy(allTools, toolPolicy);
 
+      const effectiveMcpStats: MCPWorkspaceStats =
+        mcpStats ??
+        ({
+          enabledServerCount: 0,
+          startedServerCount: 0,
+          failedServerCount: 0,
+          autoFallbackCount: 0,
+          hasStdio: false,
+          hasHttp: false,
+          hasSse: false,
+          transportMode: "none",
+        } satisfies MCPWorkspaceStats);
+
+      const mcpToolNames = new Set(Object.keys(mcpTools ?? {}));
+      const toolNames = Object.keys(tools);
+      const mcpToolCount = toolNames.filter((name) => mcpToolNames.has(name)).length;
+      const totalToolCount = toolNames.length;
+      const builtinToolCount = Math.max(0, totalToolCount - mcpToolCount);
+
+      this.telemetryService?.capture({
+        event: "mcp_context_injected",
+        properties: {
+          workspaceId,
+          model: modelString,
+          mode: mode ?? uiMode ?? "unknown",
+          runtimeType: getRuntimeTypeForTelemetry(metadata.runtimeConfig),
+
+          mcp_server_enabled_count: effectiveMcpStats.enabledServerCount,
+          mcp_server_started_count: effectiveMcpStats.startedServerCount,
+          mcp_server_failed_count: effectiveMcpStats.failedServerCount,
+
+          mcp_tool_count: mcpToolCount,
+          total_tool_count: totalToolCount,
+          builtin_tool_count: builtinToolCount,
+
+          mcp_transport_mode: effectiveMcpStats.transportMode,
+          mcp_has_http: effectiveMcpStats.hasHttp,
+          mcp_has_sse: effectiveMcpStats.hasSse,
+          mcp_has_stdio: effectiveMcpStats.hasStdio,
+          mcp_auto_fallback_count: effectiveMcpStats.autoFallbackCount,
+          mcp_setup_duration_ms_b2: roundToBase2(mcpSetupDurationMs),
+        },
+      });
+
       log.info("AIService.streamMessage: tool configuration", {
         workspaceId,
         model: modelString,
diff --git a/src/node/services/mcpConfigService.test.ts b/src/node/services/mcpConfigService.test.ts
index b53a9776c..64fb082a5 100644
--- a/src/node/services/mcpConfigService.test.ts
+++ b/src/node/services/mcpConfigService.test.ts
@@ -24,8 +24,14 @@ describe("MCP server disable filtering", () => {
 
   test("disabled servers are filtered from manager.listServers", async () => {
     // Add two servers
-    await configService.addServer(tempDir, "enabled-server", "cmd1");
-    await configService.addServer(tempDir, "disabled-server", "cmd2");
+    await configService.addServer(tempDir, "enabled-server", {
+      transport: "stdio",
+      command: "cmd1",
+    });
+    await configService.addServer(tempDir, "disabled-server", {
+      transport: "stdio",
+      command: "cmd2",
+    });
 
     // Disable one
     await configService.setServerEnabled(tempDir, "disabled-server", false);
@@ -33,13 +39,15 @@ describe("MCP server disable filtering", () => {
     // Config service returns both (with disabled flag)
     const allServers = await configService.listServers(tempDir);
     expect(allServers).toEqual({
-      "enabled-server": { command: "cmd1", disabled: false },
-      "disabled-server": { command: "cmd2", disabled: true },
+      "enabled-server": { transport: "stdio", command: "cmd1", disabled: false },
+      "disabled-server": { transport: "stdio", command: "cmd2", disabled: true },
     });
 
     // Server manager filters to enabled only
     const enabledServers = await serverManager.listServers(tempDir);
-    expect(enabledServers).toEqual({ "enabled-server": "cmd1" });
+    expect(enabledServers).toEqual({
+      "enabled-server": { transport: "stdio", command: "cmd1", disabled: false },
+    });
   });
 });
 
@@ -54,9 +62,9 @@ describe("Workspace MCP overrides filtering", () => {
     serverManager = new MCPServerManager(configService);
 
     // Set up multiple servers for testing
-    await configService.addServer(tempDir, "server-a", "cmd-a");
-    await configService.addServer(tempDir, "server-b", "cmd-b");
-    await configService.addServer(tempDir, "server-c", "cmd-c");
+    await configService.addServer(tempDir, "server-a", { transport: "stdio", command: "cmd-a" });
+    await configService.addServer(tempDir, "server-b", { transport: "stdio", command: "cmd-b" });
+    await configService.addServer(tempDir, "server-c", { transport: "stdio", command: "cmd-c" });
   });
 
   afterEach(async () => {
@@ -67,9 +75,9 @@ describe("Workspace MCP overrides filtering", () => {
   test("listServers with no overrides returns all enabled servers", async () => {
     const servers = await serverManager.listServers(tempDir);
     expect(servers).toEqual({
-      "server-a": "cmd-a",
-      "server-b": "cmd-b",
-      "server-c": "cmd-c",
+      "server-a": { transport: "stdio", command: "cmd-a", disabled: false },
+      "server-b": { transport: "stdio", command: "cmd-b", disabled: false },
+      "server-c": { transport: "stdio", command: "cmd-c", disabled: false },
     });
   });
 
@@ -77,9 +85,9 @@ describe("Workspace MCP overrides filtering", () => {
     const overrides: WorkspaceMCPOverrides = {};
     const servers = await serverManager.listServers(tempDir, overrides);
     expect(servers).toEqual({
-      "server-a": "cmd-a",
-      "server-b": "cmd-b",
-      "server-c": "cmd-c",
+      "server-a": { transport: "stdio", command: "cmd-a", disabled: false },
+      "server-b": { transport: "stdio", command: "cmd-b", disabled: false },
+      "server-c": { transport: "stdio", command: "cmd-c", disabled: false },
     });
   });
 
@@ -88,7 +96,9 @@ describe("Workspace MCP overrides filtering", () => {
       disabledServers: ["server-a", "server-c"],
     };
     const servers = await serverManager.listServers(tempDir, overrides);
-    expect(servers).toEqual({ "server-b": "cmd-b" });
+    expect(servers).toEqual({
+      "server-b": { transport: "stdio", command: "cmd-b", disabled: false },
+    });
   });
 
   test("listServers with disabledServers removes servers not in config (no error)", async () => {
@@ -97,9 +107,9 @@ describe("Workspace MCP overrides filtering", () => {
     };
     const servers = await serverManager.listServers(tempDir, overrides);
     expect(servers).toEqual({
-      "server-a": "cmd-a",
-      "server-b": "cmd-b",
-      "server-c": "cmd-c",
+      "server-a": { transport: "stdio", command: "cmd-a", disabled: false },
+      "server-b": { transport: "stdio", command: "cmd-b", disabled: false },
+      "server-c": { transport: "stdio", command: "cmd-c", disabled: false },
     });
   });
 
@@ -110,8 +120,8 @@ describe("Workspace MCP overrides filtering", () => {
     // Without override, server-a should be disabled
     const serversWithoutOverride = await serverManager.listServers(tempDir);
     expect(serversWithoutOverride).toEqual({
-      "server-b": "cmd-b",
-      "server-c": "cmd-c",
+      "server-b": { transport: "stdio", command: "cmd-b", disabled: false },
+      "server-c": { transport: "stdio", command: "cmd-c", disabled: false },
     });
 
     // With enabledServers override, server-a should be re-enabled
@@ -120,9 +130,9 @@ describe("Workspace MCP overrides filtering", () => {
     };
     const serversWithOverride = await serverManager.listServers(tempDir, overrides);
     expect(serversWithOverride).toEqual({
-      "server-a": "cmd-a",
-      "server-b": "cmd-b",
-      "server-c": "cmd-c",
+      "server-a": { transport: "stdio", command: "cmd-a", disabled: false },
+      "server-b": { transport: "stdio", command: "cmd-b", disabled: false },
+      "server-c": { transport: "stdio", command: "cmd-c", disabled: false },
     });
   });
 
@@ -137,6 +147,8 @@ describe("Workspace MCP overrides filtering", () => {
 
     const servers = await serverManager.listServers(tempDir, overrides);
     // Only server-c should remain
-    expect(servers).toEqual({ "server-c": "cmd-c" });
+    expect(servers).toEqual({
+      "server-c": { transport: "stdio", command: "cmd-c", disabled: false },
+    });
   });
 });
diff --git a/src/node/services/mcpConfigService.ts b/src/node/services/mcpConfigService.ts
index 75bbbb76e..0fc5c1cc5 100644
--- a/src/node/services/mcpConfigService.ts
+++ b/src/node/services/mcpConfigService.ts
@@ -2,7 +2,12 @@ import * as fs from "fs";
 import * as path from "path";
 import * as jsonc from "jsonc-parser";
 import writeFileAtomic from "write-file-atomic";
-import type { MCPConfig, MCPServerInfo } from "@/common/types/mcp";
+import type {
+  MCPConfig,
+  MCPHeaderValue,
+  MCPServerInfo,
+  MCPServerTransport,
+} from "@/common/types/mcp";
 import { log } from "@/node/services/log";
 import { Ok, Err } from "@/common/types/result";
 import type { Result } from "@/common/types/result";
@@ -28,17 +33,81 @@ export class MCPConfigService {
     }
   }
 
-  /** Raw config file format - string (legacy) or object */
-  private normalizeEntry(
-    entry: string | { command: string; disabled?: boolean; toolAllowlist?: string[] }
-  ): MCPServerInfo {
+  /**
+   * Normalize a raw config entry into a strongly-typed server definition.
+   *
+   * Supported raw formats:
+   * - string: stdio command
+   * - object w/ command: stdio
+   * - object w/ url: http/sse/auto (defaults to auto)
+   */
+  private normalizeEntry(entry: unknown): MCPServerInfo {
     if (typeof entry === "string") {
-      return { command: entry, disabled: false };
+      return { transport: "stdio", command: entry, disabled: false };
     }
+
+    if (!entry || typeof entry !== "object") {
+      // Fail closed for invalid shapes.
+      return { transport: "stdio", command: "", disabled: true };
+    }
+
+    const obj = entry as Record<string, unknown>;
+    const disabled = typeof obj.disabled === "boolean" ? obj.disabled : false;
+    const toolAllowlist = Array.isArray(obj.toolAllowlist)
+      ? obj.toolAllowlist.filter((v): v is string => typeof v === "string")
+      : undefined;
+
+    const transport =
+      obj.transport === "stdio" ||
+      obj.transport === "http" ||
+      obj.transport === "sse" ||
+      obj.transport === "auto"
+        ? obj.transport
+        : undefined;
+
+    const command = typeof obj.command === "string" ? obj.command : undefined;
+    const url = typeof obj.url === "string" ? obj.url : undefined;
+
+    const headersRaw = obj.headers;
+    let headers: Record<string, string | { secret: string }> | undefined;
+
+    if (headersRaw && typeof headersRaw === "object" && !Array.isArray(headersRaw)) {
+      const next: Record<string, string | { secret: string }> = {};
+      for (const [k, v] of Object.entries(headersRaw as Record<string, unknown>)) {
+        if (typeof v === "string") {
+          next[k] = v;
+          continue;
+        }
+        if (v && typeof v === "object" && !Array.isArray(v)) {
+          const secret = (v as Record<string, unknown>).secret;
+          if (typeof secret === "string") {
+            next[k] = { secret };
+          }
+        }
+      }
+      if (Object.keys(next).length > 0) {
+        headers = next;
+      }
+    }
+
+    // If it has a url, prefer HTTP-based transports (default to auto).
+    if (url) {
+      const httpTransport = transport && transport !== "stdio" ? transport : "auto";
+      return {
+        transport: httpTransport,
+        url,
+        headers,
+        disabled,
+        toolAllowlist,
+      };
+    }
+
+    // Otherwise, treat it as stdio.
     return {
-      command: entry.command,
-      disabled: entry.disabled ?? false,
-      toolAllowlist: entry.toolAllowlist,
+      transport: "stdio",
+      command: command ?? "",
+      disabled,
+      toolAllowlist,
     };
   }
 
@@ -57,9 +126,7 @@ export class MCPConfigService {
       // Normalize all entries on read
       const servers: Record<string, MCPServerInfo> = {};
       for (const [name, entry] of Object.entries(parsed.servers)) {
-        servers[name] = this.normalizeEntry(
-          entry as string | { command: string; disabled?: boolean }
-        );
+        servers[name] = this.normalizeEntry(entry);
       }
       return { servers };
     } catch (error) {
@@ -71,27 +138,46 @@ export class MCPConfigService {
   private async saveConfig(projectPath: string, config: MCPConfig): Promise<void> {
     await this.ensureProjectDir(projectPath);
     const filePath = this.getConfigPath(projectPath);
-    // Write minimal format: string for simple enabled servers, object when has settings
+
+    // Write minimal format:
+    // - string for stdio servers without extra settings
+    // - object when:
+    //   - disabled/toolAllowlist set, or
+    //   - non-stdio transport, or
+    //   - headers present
+    //
     // toolAllowlist: undefined = all tools (omit), [] = no tools, [...] = those tools
-    const output: Record<
-      string,
-      string | { command: string; disabled?: true; toolAllowlist?: string[] }
-    > = {};
+    const output: Record<string, unknown> = {};
+
     for (const [name, entry] of Object.entries(config.servers)) {
       const hasSettings = entry.disabled || entry.toolAllowlist !== undefined;
-      if (hasSettings) {
-        const obj: { command: string; disabled?: true; toolAllowlist?: string[] } = {
+
+      if (entry.transport === "stdio") {
+        if (!hasSettings) {
+          output[name] = entry.command;
+          continue;
+        }
+
+        const obj: Record<string, unknown> = {
           command: entry.command,
         };
         if (entry.disabled) obj.disabled = true;
-        if (entry.toolAllowlist !== undefined) {
-          obj.toolAllowlist = entry.toolAllowlist;
-        }
+        if (entry.toolAllowlist !== undefined) obj.toolAllowlist = entry.toolAllowlist;
         output[name] = obj;
-      } else {
-        output[name] = entry.command;
+        continue;
       }
+
+      const obj: Record<string, unknown> = {
+        transport: entry.transport,
+        url: entry.url,
+      };
+      if (entry.headers) obj.headers = entry.headers;
+      if (entry.disabled) obj.disabled = true;
+      if (entry.toolAllowlist !== undefined) obj.toolAllowlist = entry.toolAllowlist;
+
+      output[name] = obj;
     }
+
     await writeFileAtomic(filePath, JSON.stringify({ servers: output }, null, 2), "utf-8");
   }
 
@@ -101,23 +187,56 @@ export class MCPConfigService {
     return cfg.servers;
   }
 
-  async addServer(projectPath: string, name: string, command: string): Promise<Result<void>> {
+  async addServer(
+    projectPath: string,
+    name: string,
+    input: {
+      transport?: MCPServerTransport;
+      command?: string;
+      url?: string;
+      headers?: Record<string, MCPHeaderValue>;
+    }
+  ): Promise<Result<void>> {
     if (!name.trim()) {
       return Err("Server name is required");
     }
-    if (!command.trim()) {
-      return Err("Command is required");
+
+    const transport: MCPServerTransport = input.transport ?? "stdio";
+
+    if (transport === "stdio") {
+      if (!input.command?.trim()) {
+        return Err("Command is required");
+      }
+    } else {
+      if (!input.url?.trim()) {
+        return Err("URL is required");
+      }
     }
 
     const cfg = await this.getConfig(projectPath);
     const existing = cfg.servers[name];
-    // Preserve disabled state and toolAllowlist if updating existing server
-    cfg.servers[name] = {
-      command,
+
+    const base = {
       disabled: existing?.disabled ?? false,
       toolAllowlist: existing?.toolAllowlist,
     };
 
+    const next: MCPServerInfo =
+      transport === "stdio"
+        ? {
+            transport: "stdio",
+            command: input.command!,
+            ...base,
+          }
+        : {
+            transport,
+            url: input.url!,
+            headers: input.headers,
+            ...base,
+          };
+
+    cfg.servers[name] = next;
+
     try {
       await this.saveConfig(projectPath, cfg);
       return Ok(undefined);
diff --git a/src/node/services/mcpServerManager.ts b/src/node/services/mcpServerManager.ts
index 2e7b30616..f0e0e2456 100644
--- a/src/node/services/mcpServerManager.ts
+++ b/src/node/services/mcpServerManager.ts
@@ -1,10 +1,12 @@
-import { experimental_createMCPClient, type MCPTransport } from "@ai-sdk/mcp";
+import { experimental_createMCPClient } from "@ai-sdk/mcp";
 import type { Tool } from "ai";
 import { log } from "@/node/services/log";
 import { MCPStdioTransport } from "@/node/services/mcpStdioTransport";
 import type {
+  MCPHeaderValue,
   MCPServerInfo,
   MCPServerMap,
+  MCPServerTransport,
   MCPTestResult,
   WorkspaceMCPOverrides,
 } from "@/common/types/mcp";
@@ -41,50 +43,199 @@ function wrapMCPTools(tools: Record<string, Tool>): Record<string, Tool> {
   return wrapped;
 }
 
+type ResolvedHeaders = Record<string, string> | undefined;
+
+type ResolvedTransport = "stdio" | "http" | "sse";
+
+function resolveHeaders(
+  headers: Record<string, MCPHeaderValue> | undefined,
+  projectSecrets: Record<string, string> | undefined
+): { headers: ResolvedHeaders; usesSecretHeaders: boolean } {
+  if (!headers) {
+    return { headers: undefined, usesSecretHeaders: false };
+  }
+
+  const resolved: Record<string, string> = {};
+  let usesSecretHeaders = false;
+
+  for (const [key, value] of Object.entries(headers)) {
+    if (typeof value === "string") {
+      resolved[key] = value;
+      continue;
+    }
+
+    usesSecretHeaders = true;
+    const secretKey = value.secret;
+    const secretValue = projectSecrets?.[secretKey];
+    if (typeof secretValue !== "string") {
+      throw new Error(`Missing project secret: ${secretKey}`);
+    }
+    resolved[key] = secretValue;
+  }
+
+  return { headers: resolved, usesSecretHeaders };
+}
+
+function extractHttpStatusCode(error: unknown): number | null {
+  if (!error || typeof error !== "object") {
+    return null;
+  }
+
+  const obj = error as Record<string, unknown>;
+
+  // A few common shapes across fetch libraries / AI SDK.
+  const statusCode = obj.statusCode;
+  if (typeof statusCode === "number") {
+    return statusCode;
+  }
+
+  const status = obj.status;
+  if (typeof status === "number") {
+    return status;
+  }
+
+  const response = obj.response;
+  if (response && typeof response === "object") {
+    const responseStatus = (response as Record<string, unknown>).status;
+    if (typeof responseStatus === "number") {
+      return responseStatus;
+    }
+  }
+
+  const cause = obj.cause;
+  if (cause && typeof cause === "object") {
+    const causeStatus = (cause as Record<string, unknown>).statusCode;
+    if (typeof causeStatus === "number") {
+      return causeStatus;
+    }
+  }
+
+  // Best-effort fallback on message contents.
+  const message = obj.message;
+  if (typeof message === "string") {
+    const re = /\b(400|404|405)\b/;
+    const match = re.exec(message);
+    if (match) {
+      return Number(match[1]);
+    }
+  }
+
+  return null;
+}
+
+function shouldAutoFallbackToSse(error: unknown): boolean {
+  const status = extractHttpStatusCode(error);
+  return status === 400 || status === 404 || status === 405;
+}
+
 export type { MCPTestResult } from "@/common/types/mcp";
 
 /**
- * Run a test connection to an MCP server command.
- * Spawns the process, connects, fetches tools, then closes.
+ * Run a test connection to an MCP server.
+ * Connects, fetches tools, then closes.
  */
 async function runServerTest(
-  command: string,
+  server:
+    | { transport: "stdio"; command: string }
+    | { transport: "http" | "sse" | "auto"; url: string; headers?: ResolvedHeaders },
   projectPath: string,
   logContext: string
 ): Promise<MCPTestResult> {
-  const runtime = createRuntime({ type: "local", srcBaseDir: projectPath });
   const timeoutPromise = new Promise<MCPTestResult>((resolve) =>
     setTimeout(() => resolve({ success: false, error: "Connection timed out" }), TEST_TIMEOUT_MS)
   );
 
   const testPromise = (async (): Promise<MCPTestResult> => {
-    let transport: MCPStdioTransport | null = null;
+    let stdioTransport: MCPStdioTransport | null = null;
+    let client: Awaited<ReturnType<typeof experimental_createMCPClient>> | null = null;
+
     try {
-      log.debug(`[MCP] Testing ${logContext}`, { command });
-      const execStream = await runtime.exec(command, {
-        cwd: projectPath,
-        timeout: TEST_TIMEOUT_MS / 1000,
-      });
+      if (server.transport === "stdio") {
+        const runtime = createRuntime({ type: "local", srcBaseDir: projectPath });
+        log.debug(`[MCP] Testing ${logContext}`, { transport: "stdio" });
+
+        const execStream = await runtime.exec(server.command, {
+          cwd: projectPath,
+          timeout: TEST_TIMEOUT_MS / 1000,
+        });
+
+        stdioTransport = new MCPStdioTransport(execStream);
+        await stdioTransport.start();
+        client = await experimental_createMCPClient({ transport: stdioTransport });
+      } else {
+        log.debug(`[MCP] Testing ${logContext}`, { transport: server.transport });
+
+        const tryHttp = async () =>
+          experimental_createMCPClient({
+            transport: {
+              type: "http",
+              url: server.url,
+              headers: server.headers,
+            },
+          });
+
+        const trySse = async () =>
+          experimental_createMCPClient({
+            transport: {
+              type: "sse",
+              url: server.url,
+              headers: server.headers,
+            },
+          });
+
+        if (server.transport === "http") {
+          client = await tryHttp();
+        } else if (server.transport === "sse") {
+          client = await trySse();
+        } else {
+          // auto
+          try {
+            client = await tryHttp();
+          } catch (error) {
+            if (!shouldAutoFallbackToSse(error)) {
+              throw error;
+            }
+            log.debug(`[MCP] ${logContext} auto-fallback http→sse`, {
+              status: extractHttpStatusCode(error),
+            });
+            client = await trySse();
+          }
+        }
+      }
 
-      transport = new MCPStdioTransport(execStream);
-      await transport.start();
-      const client = await experimental_createMCPClient({ transport });
       const tools = await client.tools();
       const toolNames = Object.keys(tools);
+
       await client.close();
-      await transport.close();
-      log.info(`[MCP] ${logContext} test successful`, { tools: toolNames });
+      client = null;
+
+      if (stdioTransport) {
+        await stdioTransport.close();
+        stdioTransport = null;
+      }
+
+      log.info(`[MCP] ${logContext} test successful`, { toolCount: toolNames.length });
       return { success: true, tools: toolNames };
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       log.warn(`[MCP] ${logContext} test failed`, { error: message });
-      if (transport) {
+
+      if (client) {
         try {
-          await transport.close();
+          await client.close();
+        } catch {
+          // ignore cleanup errors
+        }
+      }
+
+      if (stdioTransport) {
+        try {
+          await stdioTransport.close();
         } catch {
           // ignore cleanup errors
         }
       }
+
       return { success: false, error: message };
     }
   })();
@@ -94,20 +245,41 @@ async function runServerTest(
 
 interface MCPServerInstance {
   name: string;
-  transport: MCPTransport;
+  /** Resolved transport actually used (auto may fall back to sse). */
+  resolvedTransport: ResolvedTransport;
+  autoFallbackUsed: boolean;
   tools: Record<string, Tool>;
   close: () => Promise<void>;
 }
 
+export type MCPTransportMode = "none" | "stdio_only" | "http_only" | "sse_only" | "mixed";
+
+export interface MCPWorkspaceStats {
+  enabledServerCount: number;
+  startedServerCount: number;
+  failedServerCount: number;
+  autoFallbackCount: number;
+
+  hasStdio: boolean;
+  hasHttp: boolean;
+  hasSse: boolean;
+  transportMode: MCPTransportMode;
+}
+
+export interface MCPToolsForWorkspaceResult {
+  tools: Record<string, Tool>;
+  stats: MCPWorkspaceStats;
+}
 interface WorkspaceServers {
   configSignature: string;
   instances: Map<string, MCPServerInstance>;
+  stats: MCPWorkspaceStats;
   lastActivity: number;
 }
 
 export interface MCPServerManagerOptions {
-  /** Inline servers to use (merged with config file servers by default) */
-  inlineServers?: MCPServerMap;
+  /** Inline stdio servers to use (merged with config file servers by default) */
+  inlineServers?: Record<string, string>;
   /** If true, ignore config file servers and use only inline servers */
   ignoreConfigFile?: boolean;
 }
@@ -115,7 +287,7 @@ export interface MCPServerManagerOptions {
 export class MCPServerManager {
   private readonly workspaceServers = new Map<string, WorkspaceServers>();
   private readonly idleCheckInterval: ReturnType<typeof setInterval>;
-  private inlineServers: MCPServerMap = {};
+  private inlineServers: Record<string, string> = {};
   private ignoreConfigFile = false;
 
   constructor(
@@ -164,7 +336,7 @@ export class MCPServerManager {
     // Inline servers override config file servers (always enabled)
     const inlineAsInfo: Record<string, MCPServerInfo> = {};
     for (const [name, command] of Object.entries(this.inlineServers)) {
-      inlineAsInfo[name] = { command, disabled: false };
+      inlineAsInfo[name] = { transport: "stdio", command, disabled: false };
     }
     return { ...configServers, ...inlineAsInfo };
   }
@@ -205,15 +377,23 @@ export class MCPServerManager {
     for (const [name, info] of Object.entries(servers)) {
       // Workspace overrides take precedence
       if (enabledSet.has(name)) {
-        result[name] = info.command; // Explicitly enabled at workspace level
-      } else if (disabledSet.has(name)) {
+        // Explicitly enabled at workspace level (overrides project disabled)
+        result[name] = { ...info, disabled: false };
+        continue;
+      }
+
+      if (disabledSet.has(name)) {
         // Explicitly disabled at workspace level - skip
         continue;
-      } else if (!info.disabled) {
-        result[name] = info.command; // Enabled at project level, no workspace override
+      }
+
+      if (!info.disabled) {
+        // Enabled at project level, no workspace override
+        result[name] = info;
       }
       // If disabled at project level with no workspace override, skip
     }
+
     return result;
   }
 
@@ -284,38 +464,116 @@ export class MCPServerManager {
     workspacePath: string;
     /** Per-workspace MCP overrides (disabled servers, tool allowlists) */
     overrides?: WorkspaceMCPOverrides;
-  }): Promise<Record<string, Tool>> {
-    const { workspaceId, projectPath, runtime, workspacePath, overrides } = options;
+    /** Project secrets, used for resolving {secret: "KEY"} header references. */
+    projectSecrets?: Record<string, string>;
+  }): Promise<MCPToolsForWorkspaceResult> {
+    const { workspaceId, projectPath, runtime, workspacePath, overrides, projectSecrets } = options;
 
     // Fetch full server info for project-level allowlists and server filtering
     const fullServerInfo = await this.getAllServers(projectPath);
 
     // Apply server-level overrides (enabled/disabled) before caching
-    const servers = this.applyServerOverrides(fullServerInfo, overrides);
-    const signature = JSON.stringify(servers);
-    const serverNames = Object.keys(servers);
+    const enabledServers = this.applyServerOverrides(fullServerInfo, overrides);
+    const enabledEntries = Object.entries(enabledServers).sort(([a], [b]) => a.localeCompare(b));
+
+    // Signature is based on *start config* only (not tool allowlists), so changing allowlists
+    // does not force a server restart.
+    const signatureEntries: Record<string, unknown> = {};
+    for (const [name, info] of enabledEntries) {
+      if (info.transport === "stdio") {
+        signatureEntries[name] = { transport: "stdio", command: info.command };
+        continue;
+      }
+
+      try {
+        const { headers } = resolveHeaders(info.headers, projectSecrets);
+        signatureEntries[name] = { transport: info.transport, url: info.url, headers };
+      } catch {
+        // Missing secrets or invalid header config. Keep signature stable but avoid leaking details.
+        signatureEntries[name] = { transport: info.transport, url: info.url, headers: null };
+      }
+    }
+
+    const signature = JSON.stringify(signatureEntries);
 
     const existing = this.workspaceServers.get(workspaceId);
     if (existing?.configSignature === signature) {
-      // Update activity timestamp to prevent idle cleanup
       existing.lastActivity = Date.now();
-      log.debug("[MCP] Using cached servers", { workspaceId, serverCount: serverNames.length });
-      // Apply tool-level filtering (allowlists) each time - they can change without server restart
-      return this.collectTools(existing.instances, fullServerInfo, overrides);
+      log.debug("[MCP] Using cached servers", {
+        workspaceId,
+        serverCount: enabledEntries.length,
+      });
+
+      return {
+        tools: this.collectTools(existing.instances, fullServerInfo, overrides),
+        stats: existing.stats,
+      };
     }
 
     // Config changed or not started yet -> restart
-    if (serverNames.length > 0) {
-      log.info("[MCP] Starting servers", { workspaceId, servers: serverNames });
+    if (enabledEntries.length > 0) {
+      log.info("[MCP] Starting servers", {
+        workspaceId,
+        servers: enabledEntries.map(([name]) => name),
+      });
     }
+
     await this.stopServers(workspaceId);
-    const instances = await this.startServers(servers, runtime, workspacePath);
+
+    const instances = await this.startServers(
+      enabledServers,
+      runtime,
+      workspacePath,
+      projectSecrets
+    );
+
+    const configuredTransports = new Set<ResolvedTransport>();
+    for (const [, info] of enabledEntries) {
+      if (info.transport === "stdio") {
+        configuredTransports.add("stdio");
+        continue;
+      }
+      // Treat auto as http for transport-mode purposes.
+      configuredTransports.add(info.transport === "sse" ? "sse" : "http");
+    }
+
+    const hasStdio = configuredTransports.has("stdio");
+    const hasHttp = configuredTransports.has("http");
+    const hasSse = configuredTransports.has("sse");
+
+    const transportMode: MCPTransportMode =
+      enabledEntries.length === 0
+        ? "none"
+        : configuredTransports.size === 1 && hasStdio
+          ? "stdio_only"
+          : configuredTransports.size === 1 && hasHttp
+            ? "http_only"
+            : configuredTransports.size === 1 && hasSse
+              ? "sse_only"
+              : "mixed";
+
+    const stats: MCPWorkspaceStats = {
+      enabledServerCount: enabledEntries.length,
+      startedServerCount: instances.size,
+      failedServerCount: Math.max(0, enabledEntries.length - instances.size),
+      autoFallbackCount: [...instances.values()].filter((i) => i.autoFallbackUsed).length,
+      hasStdio,
+      hasHttp,
+      hasSse,
+      transportMode,
+    };
+
     this.workspaceServers.set(workspaceId, {
       configSignature: signature,
       instances,
+      stats,
       lastActivity: Date.now(),
     });
-    return this.collectTools(instances, fullServerInfo, overrides);
+
+    return {
+      tools: this.collectTools(instances, fullServerInfo, overrides),
+      stats,
+    };
   }
 
   async stopServers(workspaceId: string): Promise<void> {
@@ -334,23 +592,71 @@ export class MCPServerManager {
   }
 
   /**
-   * Test an MCP server. Provide either:
-   * - `name` to test a configured server by looking up its command
-   * - `command` to test an arbitrary command directly
+   * Test an MCP server.
+   *
+   * Provide either:
+   * - `name` to test a configured server by looking up its config, OR
+   * - `command` to test an arbitrary stdio command, OR
+   * - `url`+`transport` to test an arbitrary HTTP/SSE endpoint.
    */
-  async test(projectPath: string, name?: string, command?: string): Promise<MCPTestResult> {
-    if (name) {
+  async test(options: {
+    projectPath: string;
+    name?: string;
+    command?: string;
+    transport?: MCPServerTransport;
+    url?: string;
+    headers?: Record<string, MCPHeaderValue>;
+    projectSecrets?: Record<string, string>;
+  }): Promise<MCPTestResult> {
+    const { projectPath, name, command, transport, url, headers, projectSecrets } = options;
+
+    if (name?.trim()) {
       const servers = await this.configService.listServers(projectPath);
       const server = servers[name];
       if (!server) {
         return { success: false, error: `Server "${name}" not found in configuration` };
       }
-      return runServerTest(server.command, projectPath, `server "${name}"`);
+
+      if (server.transport === "stdio") {
+        return runServerTest(
+          { transport: "stdio", command: server.command },
+          projectPath,
+          `server "${name}"`
+        );
+      }
+
+      try {
+        const resolved = resolveHeaders(server.headers, projectSecrets);
+        return runServerTest(
+          { transport: server.transport, url: server.url, headers: resolved.headers },
+          projectPath,
+          `server "${name}"`
+        );
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { success: false, error: message };
+      }
     }
+
     if (command?.trim()) {
-      return runServerTest(command, projectPath, "command");
+      return runServerTest({ transport: "stdio", command }, projectPath, "command");
     }
-    return { success: false, error: "Either name or command is required" };
+
+    if (url?.trim()) {
+      if (transport !== "http" && transport !== "sse" && transport !== "auto") {
+        return { success: false, error: "transport must be http|sse|auto when testing by url" };
+      }
+
+      try {
+        const resolved = resolveHeaders(headers, projectSecrets);
+        return runServerTest({ transport, url, headers: resolved.headers }, projectPath, "url");
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { success: false, error: message };
+      }
+    }
+
+    return { success: false, error: "Either name, command, or url is required" };
   }
 
   /**
@@ -389,46 +695,140 @@ export class MCPServerManager {
   private async startServers(
     servers: MCPServerMap,
     runtime: Runtime,
-    workspacePath: string
+    workspacePath: string,
+    projectSecrets: Record<string, string> | undefined
   ): Promise<Map<string, MCPServerInstance>> {
     const result = new Map<string, MCPServerInstance>();
     const entries = Object.entries(servers);
-    for (const [name, command] of entries) {
+
+    for (const [name, info] of entries) {
       try {
-        const instance = await this.startSingleServer(name, command, runtime, workspacePath);
+        const instance = await this.startSingleServer(
+          name,
+          info,
+          runtime,
+          workspacePath,
+          projectSecrets
+        );
         if (instance) {
           result.set(name, instance);
         }
       } catch (error) {
-        log.error("Failed to start MCP server", { name, error });
+        const message = error instanceof Error ? error.message : String(error);
+        log.error("Failed to start MCP server", { name, error: message });
       }
     }
+
     return result;
   }
 
   private async startSingleServer(
     name: string,
-    command: string,
+    info: MCPServerInfo,
     runtime: Runtime,
-    workspacePath: string
+    workspacePath: string,
+    projectSecrets: Record<string, string> | undefined
   ): Promise<MCPServerInstance | null> {
-    log.debug("[MCP] Spawning server", { name, command });
-    const execStream = await runtime.exec(command, {
-      cwd: workspacePath,
-      timeout: 60 * 60 * 24, // 24 hours
-    });
+    if (info.transport === "stdio") {
+      log.debug("[MCP] Spawning stdio server", { name });
+      const execStream = await runtime.exec(info.command, {
+        cwd: workspacePath,
+        timeout: 60 * 60 * 24, // 24 hours
+      });
 
-    const transport = new MCPStdioTransport(execStream);
-    transport.onerror = (error) => {
-      log.error("[MCP] Transport error", { name, error });
-    };
+      const transport = new MCPStdioTransport(execStream);
+      transport.onerror = (error) => {
+        log.error("[MCP] Transport error", { name, error });
+      };
+
+      await transport.start();
+      const client = await experimental_createMCPClient({ transport });
+      const rawTools = await client.tools();
+      const tools = wrapMCPTools(rawTools);
+
+      log.info("[MCP] Server ready", {
+        name,
+        transport: "stdio",
+        toolCount: Object.keys(tools).length,
+      });
+
+      const close = async () => {
+        try {
+          await client.close();
+        } catch (error) {
+          log.debug("[MCP] Error closing client", { name, error });
+        }
+        try {
+          await transport.close();
+        } catch (error) {
+          log.debug("[MCP] Error closing transport", { name, error });
+        }
+      };
+
+      return {
+        name,
+        resolvedTransport: "stdio",
+        autoFallbackUsed: false,
+        tools,
+        close,
+      };
+    }
+
+    const { headers } = resolveHeaders(info.headers, projectSecrets);
+
+    const tryHttp = async () =>
+      experimental_createMCPClient({
+        transport: {
+          type: "http",
+          url: info.url,
+          headers,
+        },
+      });
+
+    const trySse = async () =>
+      experimental_createMCPClient({
+        transport: {
+          type: "sse",
+          url: info.url,
+          headers,
+        },
+      });
+
+    let client: Awaited<ReturnType<typeof experimental_createMCPClient>>;
+    let resolvedTransport: ResolvedTransport;
+    let autoFallbackUsed = false;
+
+    if (info.transport === "http") {
+      resolvedTransport = "http";
+      client = await tryHttp();
+    } else if (info.transport === "sse") {
+      resolvedTransport = "sse";
+      client = await trySse();
+    } else {
+      // auto
+      try {
+        resolvedTransport = "http";
+        client = await tryHttp();
+      } catch (error) {
+        if (!shouldAutoFallbackToSse(error)) {
+          throw error;
+        }
+        autoFallbackUsed = true;
+        resolvedTransport = "sse";
+        log.debug("[MCP] Auto-fallback http→sse", { name, status: extractHttpStatusCode(error) });
+        client = await trySse();
+      }
+    }
 
-    await transport.start();
-    const client = await experimental_createMCPClient({ transport });
     const rawTools = await client.tools();
     const tools = wrapMCPTools(rawTools);
-    const toolNames = Object.keys(tools);
-    log.info("[MCP] Server ready", { name, tools: toolNames });
+
+    log.info("[MCP] Server ready", {
+      name,
+      transport: resolvedTransport,
+      toolCount: Object.keys(tools).length,
+      autoFallbackUsed,
+    });
 
     const close = async () => {
       try {
@@ -436,13 +836,14 @@ export class MCPServerManager {
       } catch (error) {
         log.debug("[MCP] Error closing client", { name, error });
       }
-      try {
-        await transport.close();
-      } catch (error) {
-        log.debug("[MCP] Error closing transport", { name, error });
-      }
     };
 
-    return { name, transport, tools, close };
+    return {
+      name,
+      resolvedTransport,
+      autoFallbackUsed,
+      tools,
+      close,
+    };
   }
 }
diff --git a/src/node/services/serviceContainer.ts b/src/node/services/serviceContainer.ts
index e7e476eb9..7ae56b9d7 100644
--- a/src/node/services/serviceContainer.ts
+++ b/src/node/services/serviceContainer.ts
@@ -116,6 +116,7 @@ export class ServiceContainer {
     this.menuEventService = new MenuEventService();
     this.voiceService = new VoiceService(config);
     this.telemetryService = new TelemetryService(config.rootDir);
+    this.aiService.setTelemetryService(this.telemetryService);
     this.workspaceService.setTelemetryService(this.telemetryService);
     this.experimentsService = new ExperimentsService({
       telemetryService: this.telemetryService,

From 4f4449a86bbb4b1e5365f0bcf560b3438d973f8f Mon Sep 17 00:00:00 2001
From: Thomas Kosiewski <tk@coder.com>
Date: Wed, 17 Dec 2025 17:28:05 +0100
Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=A4=96=20fix:=20update=20integration?=
 =?UTF-8?q?=20test=20expectations=20for=20MCPServerInfo=20transport=20fiel?=
 =?UTF-8?q?d?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Change-Id: I7271e9951ede4d7f9963aad8daeaeea7ead1086c
Signed-off-by: Thomas Kosiewski <tk@coder.com>
---
 tests/ipc/mcpConfig.test.ts | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/tests/ipc/mcpConfig.test.ts b/tests/ipc/mcpConfig.test.ts
index 28a93b3dd..f51941323 100644
--- a/tests/ipc/mcpConfig.test.ts
+++ b/tests/ipc/mcpConfig.test.ts
@@ -156,7 +156,11 @@ describeIntegration("MCP project configuration", () => {
       // Should list the added server
       const listed = await client.projects.mcp.list({ projectPath: repoPath });
       expect(listed).toEqual({
-        "chrome-devtools": { command: CHROME_DEVTOOLS_MCP_NPX, disabled: false },
+        "chrome-devtools": {
+          transport: "stdio",
+          command: CHROME_DEVTOOLS_MCP_NPX,
+          disabled: false,
+        },
       });
 
       // Config file should be written
@@ -177,7 +181,7 @@ describeIntegration("MCP project configuration", () => {
       // Should still be listed but disabled
       const disabledList = await client.projects.mcp.list({ projectPath: repoPath });
       expect(disabledList).toEqual({
-        "chrome-devtools": { command: CHROME_DEVTOOLS_MCP_NPX, disabled: true },
+        "chrome-devtools": { transport: "stdio", command: CHROME_DEVTOOLS_MCP_NPX, disabled: true },
       });
 
       // Config file should have disabled format
@@ -199,7 +203,11 @@ describeIntegration("MCP project configuration", () => {
       // Should be enabled again, config file back to string format
       const enabledList = await client.projects.mcp.list({ projectPath: repoPath });
       expect(enabledList).toEqual({
-        "chrome-devtools": { command: CHROME_DEVTOOLS_MCP_NPX, disabled: false },
+        "chrome-devtools": {
+          transport: "stdio",
+          command: CHROME_DEVTOOLS_MCP_NPX,
+          disabled: false,
+        },
       });
       const enabledConfig = await fs.readFile(configPath, "utf-8");
       expect(JSON.parse(enabledConfig)).toEqual({

From 73988d375f2a1f4834d83d0b2196c2839ef786ec Mon Sep 17 00:00:00 2001
From: Thomas Kosiewski <tk@coder.com>
Date: Wed, 17 Dec 2025 17:58:09 +0100
Subject: [PATCH 3/4] =?UTF-8?q?=F0=9F=A4=96=20fix:=20derive=20MCP=20transp?=
 =?UTF-8?q?ort=20telemetry=20from=20resolved=20transports?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Change-Id: I
Signed-off-by: Thomas Kosiewski <tk@coder.com>
---
 src/node/services/mcpServerManager.ts | 25 ++++++++++---------------
 1 file changed, 10 insertions(+), 15 deletions(-)

diff --git a/src/node/services/mcpServerManager.ts b/src/node/services/mcpServerManager.ts
index f0e0e2456..714e87b2f 100644
--- a/src/node/services/mcpServerManager.ts
+++ b/src/node/services/mcpServerManager.ts
@@ -527,28 +527,23 @@ export class MCPServerManager {
       projectSecrets
     );
 
-    const configuredTransports = new Set<ResolvedTransport>();
-    for (const [, info] of enabledEntries) {
-      if (info.transport === "stdio") {
-        configuredTransports.add("stdio");
-        continue;
-      }
-      // Treat auto as http for transport-mode purposes.
-      configuredTransports.add(info.transport === "sse" ? "sse" : "http");
+    const resolvedTransports = new Set<ResolvedTransport>();
+    for (const instance of instances.values()) {
+      resolvedTransports.add(instance.resolvedTransport);
     }
 
-    const hasStdio = configuredTransports.has("stdio");
-    const hasHttp = configuredTransports.has("http");
-    const hasSse = configuredTransports.has("sse");
+    const hasStdio = resolvedTransports.has("stdio");
+    const hasHttp = resolvedTransports.has("http");
+    const hasSse = resolvedTransports.has("sse");
 
     const transportMode: MCPTransportMode =
-      enabledEntries.length === 0
+      instances.size === 0
         ? "none"
-        : configuredTransports.size === 1 && hasStdio
+        : resolvedTransports.size === 1 && hasStdio
           ? "stdio_only"
-          : configuredTransports.size === 1 && hasHttp
+          : resolvedTransports.size === 1 && hasHttp
             ? "http_only"
-            : configuredTransports.size === 1 && hasSse
+            : resolvedTransports.size === 1 && hasSse
               ? "sse_only"
               : "mixed";
 

From 570c2ce8385cbb4577a0a8b595a181adaf639065 Mon Sep 17 00:00:00 2001
From: Thomas Kosiewski <tk@coder.com>
Date: Wed, 17 Dec 2025 18:39:06 +0100
Subject: [PATCH 4/4] =?UTF-8?q?=F0=9F=A4=96=20docs:=20clarify=20MCP=20tran?=
 =?UTF-8?q?sport=20telemetry=20reflects=20started=20servers?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Change-Id: I95d4d351bdc317416d876df0c5111dad3210d8ba
Signed-off-by: Thomas Kosiewski <tk@coder.com>
---
 src/common/telemetry/payload.ts | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/common/telemetry/payload.ts b/src/common/telemetry/payload.ts
index 0d4e36e55..ba44dc73a 100644
--- a/src/common/telemetry/payload.ts
+++ b/src/common/telemetry/payload.ts
@@ -137,13 +137,13 @@ export interface MCPContextInjectedPayload {
   /** Built-in tool count injected into the model request */
   builtin_tool_count: number;
 
-  /** Effective transport mix for enabled servers */
+  /** Effective transport mix for *started* servers (auto transport is resolved to http/sse) */
   mcp_transport_mode: TelemetryMCPTransportMode;
-  /** Whether any enabled server uses HTTP (includes auto transport) */
+  /** Whether any started server uses HTTP (auto transport resolves to http/sse at runtime) */
   mcp_has_http: boolean;
-  /** Whether any enabled server uses legacy SSE */
+  /** Whether any started server uses legacy SSE */
   mcp_has_sse: boolean;
-  /** Whether any enabled server uses stdio */
+  /** Whether any started server uses stdio */
   mcp_has_stdio: boolean;
 
   /** Number of servers that required auto-fallback from HTTP to SSE */