Support adding and removing MCP servers at runtime

Lets clients (eca-desktop webview, remote web UI) create and delete
MCP server definitions without hand-editing config files. Writes go
through rewrite-json so user comments and formatting are preserved.

- JSON-RPC: mcp/addServer and mcp/removeServer requests; new
  tool/serverRemoved notification emitted on successful removal
- mcp/updateServer now accepts :env and :headers, and its persistence
  path is migrated off the cheshire round-trip that stripped comments
- REST mirror: POST /api/v1/mcp and DELETE /api/v1/mcp/:name
- Validation returns {:error {:code "invalid_request" ...}} for
  duplicate name, missing transport, command+url conflict, blank name,
  and unknown server on remove

🤖 Generated with [eca](https://eca.dev)

Co-Authored-By: eca-agent <git@eca.dev>

Author: ericdallo

src/eca/features/tools.clj

@@ -279,6 +279,11 @@
                                                                     (fn [t] (assoc t :server {:name (:name server)})))
                                                               %)))))
 
+(defn ^:private notify-server-removed [metrics messenger params]
+  (metrics/count-up! "mcp-server-status" {:name (:name params)
+                                          :status "removed"} metrics)
+  (messenger/tool-server-removed messenger params))
+
 (defn init-servers! [db* messenger config metrics]
   (let [default-agent (get config :defaultAgent)
         tool-status-fn (make-tool-status-fn config default-agent)]
@@ -356,6 +361,26 @@
      metrics
      {:on-server-updated (partial notify-server-updated metrics messenger tool-status-fn)})))
 
+(defn add-server! [name server-config opts db* messenger config metrics]
+  (let [tool-status-fn (make-tool-status-fn config nil)]
+    (f.mcp/add-server!
+     name
+     server-config
+     opts
+     db*
+     config
+     metrics
+     {:on-server-updated (partial notify-server-updated metrics messenger tool-status-fn)})))
+
+(defn remove-server! [name db* messenger config metrics]
+  (let [tool-status-fn (make-tool-status-fn config nil)]
+    (f.mcp/remove-server!
+     name
+     db*
+     config
+     {:on-server-updated (partial notify-server-updated metrics messenger tool-status-fn)
+      :on-server-removed (partial notify-server-removed metrics messenger)})))
+
 (defn tool-call-summary [all-tools full-name args config db]
   (when-let [summary-fn (:summary-fn (first (filter #(= full-name (:full-name %))
                                                     all-tools)))]

src/eca/features/tools/mcp.clj

@@ -443,20 +443,26 @@
         (swap! db* assoc-in [:mcp-clients name :status] :failed)
         (on-server-updated (->server name server-config :failed @db*))))))
 
+(defn ^:private start-single-server-async!
+  "Spawn a daemon init thread for a single MCP server. Used by both initial
+   startup and runtime add-server!."
+  [server-name db* config metrics on-server-updated]
+  (let [t (Thread.
+           (fn []
+             (with-init-thread server-name
+               (initialize-server! server-name db* config metrics on-server-updated))))]
+    (.setName t (str "mcp-init-" server-name))
+    (.setDaemon t true)
+    (.start t)))
+
 (defn initialize-servers-async! [{:keys [on-server-updated]} db* config metrics]
   (let [db @db*]
     (doseq [[name-kwd server-config] (:mcpServers config)]
       (let [server-name (name name-kwd)]
         (when-not (get-in db [:mcp-clients server-name])
           (if (get server-config :disabled false)
             (on-server-updated (->server server-name server-config :disabled db))
-            (let [t (Thread.
-                     (fn []
-                       (with-init-thread server-name
-                         (initialize-server! server-name db* config metrics on-server-updated))))]
-              (.setName t (str "mcp-init-" server-name))
-              (.setDaemon t true)
-              (.start t))))))))
+            (start-single-server-async! server-name db* config metrics on-server-updated)))))))
 
 (def ^:private disconnect-timeout-ms 3000)
 
@@ -570,37 +576,6 @@
                 {:source :global}))))
         {:source :global})))
 
-(defn ^:private replace-server-in-config-file!
-  "Replace a single MCP server entry in a JSON config file using assoc-in
-   instead of deep-merge, so old keys (e.g. :command when switching to :url)
-   are removed. Note: comments in the original file are stripped since JSON
-   output cannot preserve them."
-  [^java.io.File config-file server-name new-server-config]
-  (let [raw (when (.exists config-file)
-              (parse-json-with-comments (slurp config-file)))
-        updated (assoc-in (or raw {}) ["mcpServers" server-name]
-                          (json/parse-string (json/generate-string new-server-config)))]
-    (io/make-parents config-file)
-    (spit config-file (json/generate-string updated {:pretty true}))))
-
-(defn update-server!
-  "Update an MCP server's connection config (command/args/url), persist to the
-   correct config file (local or global), clear the config cache, then restart."
-  [server-name server-fields db* config metrics {:keys [on-server-updated]}]
-  (let [db @db*
-        {:keys [source workspace-root-uri]} (find-server-config-source server-name db)
-        current-server-config (get-in config [:mcpServers server-name])
-        ;; Build clean server entry: preserve env/disabled/headers, replace connection fields
-        preserved-keys (select-keys current-server-config [:env :disabled :headers])
-        new-server-config (merge preserved-keys server-fields)
-        config-file (if (= source :local)
-                      (io/file (shared/uri->filename workspace-root-uri) ".eca" "config.json")
-                      (config/global-config-file))]
-    (replace-server-in-config-file! config-file server-name new-server-config)
-    (memoize/memo-clear! config/all)
-    (let [fresh-config (config/all @db*)]
-      (restart-server! server-name db* fresh-config metrics on-server-updated))))
-
 (defn ^:private update-config-file!
   "Apply rewrite-json edits to a config file, preserving comments and formatting.
    `edit-fn` receives a parsed rj root node and returns the modified root."
@@ -610,12 +585,82 @@
     (io/make-parents config-file)
     (spit config-file (rj/to-string root))))
 
+(defn ^:private walk-server-leaves
+  "Walks an MCP server-config map and returns a seq of [string-path-vec value] pairs,
+   stringifying keyword keys. Vectors (e.g. :args) are treated as leaves so they
+   serialize as JSON arrays."
+  ([m] (walk-server-leaves [] m))
+  ([prefix m]
+   (reduce-kv
+    (fn [acc k v]
+      (let [path (conj prefix (if (keyword? k) (name k) (str k)))]
+        (if (and (map? v) (seq v))
+          (into acc (walk-server-leaves path v))
+          (conj acc [path v]))))
+    []
+    m)))
+
+(defn ^:private rj-assoc-server-entry
+  "Replace the `mcpServers[server-name]` subtree in a rewrite-json root with
+   the contents of `server-config`. Dissocs the existing entry first so stale
+   keys (e.g. :url after switching to stdio) do not leak in."
+  [root server-name server-config]
+  (reduce (fn [r [leaf-path v]]
+            (rj/assoc-in r (into ["mcpServers" server-name] leaf-path) v))
+          (rj/dissoc-in root ["mcpServers" server-name])
+          (walk-server-leaves server-config)))
+
 (defn ^:private resolve-config-file [server-name db]
   (let [{:keys [source workspace-root-uri]} (find-server-config-source server-name db)]
     (if (= source :local)
       (io/file (shared/uri->filename workspace-root-uri) ".eca" "config.json")
       (config/global-config-file))))
 
+(defn ^:private resolve-target-config-file
+  "Resolve the config file for a NEW server (no existing source to look up).
+   scope is :global (default) or :workspace (workspace-uri required)."
+  [scope workspace-uri db]
+  (case scope
+    :workspace (if workspace-uri
+                 (let [roots (:workspace-folders db)
+                       uris (into #{} (map :uri) roots)]
+                   (when-not (contains? uris workspace-uri)
+                     (throw (ex-info (format "workspaceUri '%s' is not an open workspace root" workspace-uri)
+                                     {:workspace-uri workspace-uri
+                                      :workspace-roots (vec uris)})))
+                   (io/file (shared/uri->filename workspace-uri) ".eca" "config.json"))
+                 (throw (ex-info ":workspace scope requires :workspace-uri"
+                                 {:scope scope})))
+    (config/global-config-file)))
+
+(defn update-server!
+  "Update an MCP server's config fields (command/args/env/url/headers), persist
+   to the correct config file preserving comments and formatting, clear the
+   config cache, then restart.
+
+   `server-fields` is a partial map of fields to override. Fields not present
+   are preserved from the existing entry EXCEPT when the transport flips:
+   switching to HTTP (by supplying :url) strips :command/:args/:env, and
+   switching to stdio (by supplying :command or :args) strips :url/:headers."
+  [server-name server-fields db* config metrics {:keys [on-server-updated]}]
+  (let [db @db*
+        current-server-config (get-in config [:mcpServers server-name])
+        switching-to-http?  (some? (:url server-fields))
+        switching-to-stdio? (or (some? (:command server-fields))
+                                (some? (:args server-fields)))
+        stripped-keys (cond
+                        switching-to-http?  [:command :args :env]
+                        switching-to-stdio? [:url :headers]
+                        :else [])
+        new-server-config (-> (apply dissoc current-server-config stripped-keys)
+                              (merge server-fields))
+        config-file (resolve-config-file server-name db)]
+    (update-config-file! config-file
+                         #(rj-assoc-server-entry % server-name new-server-config))
+    (memoize/memo-clear! config/all)
+    (let [fresh-config (config/all @db*)]
+      (restart-server! server-name db* fresh-config metrics on-server-updated))))
+
 (defn disable-server!
   "Disable an MCP server: persist disabled=true in config, stop if running, notify."
   [server-name db* config {:keys [on-server-updated]}]
@@ -640,6 +685,77 @@
     (let [fresh-config (config/all @db*)]
       (start-server! server-name db* fresh-config metrics {:on-server-updated on-server-updated}))))
 
+(defn ^:private normalize-new-server-config
+  "Coerce incoming map (from JSON-RPC) into the shape stored in :mcpServers.
+   Keyword-izes top-level keys and nested :env/:headers keys so internal
+   code paths (->transport, start-server!) work uniformly after config/all
+   is re-read."
+  [server-config]
+  (letfn [(kw-map [m] (into {} (map (fn [[k v]] [(keyword (name k)) v])) m))]
+    (cond-> (kw-map server-config)
+      (:env server-config)     (update :env kw-map)
+      (:headers server-config) (update :headers kw-map))))
+
+(defn add-server!
+  "Add a new MCP server definition: validate, persist to the chosen config file
+   preserving comments, clear the config cache, then start the server async
+   (unless :disabled true, in which case only emit the disabled status).
+
+   `server-config` is the wire-shape entry map. Accepted fields:
+     stdio:  :command, :args, :env, :disabled
+     HTTP:   :url, :headers, :clientId, :clientSecret, :oauthPort, :disabled
+
+   `opts`:
+     :scope         :global (default) or :workspace
+     :workspace-uri required when :scope = :workspace"
+  [server-name server-config {:keys [scope workspace-uri]} db* config metrics
+   {:keys [on-server-updated]}]
+  (when (string/blank? server-name)
+    (throw (ex-info "MCP server name must be non-blank" {})))
+  (when (get-in config [:mcpServers server-name])
+    (throw (ex-info (format "MCP server '%s' already exists" server-name)
+                    {:server-name server-name})))
+  (let [normalized (normalize-new-server-config server-config)
+        has-command? (some? (:command normalized))
+        has-url?     (some? (:url normalized))]
+    (when (and has-command? has-url?)
+      (throw (ex-info "MCP server entry must not specify both :command and :url"
+                      {:server-name server-name})))
+    (when-not (or has-command? has-url?)
+      (throw (ex-info "MCP server entry must specify :command (stdio) or :url (HTTP)"
+                      {:server-name server-name})))
+    (let [scope (or scope :global)
+          config-file (resolve-target-config-file scope workspace-uri @db*)]
+      (update-config-file! config-file
+                           #(rj-assoc-server-entry % server-name normalized))
+      (memoize/memo-clear! config/all)
+      (let [fresh-config (config/all @db*)
+            fresh-server-config (get-in fresh-config [:mcpServers server-name])]
+        (if (get fresh-server-config :disabled false)
+          (do (on-server-updated (->server server-name fresh-server-config :disabled @db*))
+              (->server server-name fresh-server-config :disabled @db*))
+          (do (start-single-server-async! server-name db* fresh-config metrics on-server-updated)
+              (->server server-name fresh-server-config :starting @db*)))))))
+
+(defn remove-server!
+  "Remove an MCP server: stop if running, dissoc from the config file
+   preserving comments, clear cache, clear any stored OAuth tokens, and
+   fire on-server-removed."
+  [server-name db* config {:keys [on-server-updated on-server-removed]}]
+  (when-not (get-in config [:mcpServers server-name])
+    (throw (ex-info (format "MCP server '%s' does not exist" server-name)
+                    {:server-name server-name})))
+  (let [db @db*
+        config-file (resolve-config-file server-name db)]
+    (when (get-in db [:mcp-clients server-name :client])
+      (stop-server! server-name db* config {:on-server-updated on-server-updated}))
+    (swap! db* update :mcp-auth dissoc server-name)
+    (update-config-file! config-file
+                         #(rj/dissoc-in % ["mcpServers" server-name]))
+    (memoize/memo-clear! config/all)
+    (on-server-removed {:name server-name})
+    {:name server-name :removed true}))
+
 (defn all-tools [db]
   (into []
         (mapcat (fn [[name {:keys [tools version]}]]

src/eca/handlers.clj

@@ -281,7 +281,9 @@
           server-fields (cond-> {}
                           (:command params) (assoc :command (:command params))
                           (:args params) (assoc :args (:args params))
-                          (:url params) (assoc :url (:url params)))]
+                          (:url params) (assoc :url (:url params))
+                          (:env params) (assoc :env (:env params))
+                          (:headers params) (assoc :headers (:headers params)))]
       (f.tools/update-server! server-name server-fields db* messenger config metrics)
       {})))
 
@@ -293,6 +295,64 @@
   (metrics/task metrics :eca/mcp-enable-server
     (f.tools/enable-server! (:name params) db* messenger config metrics)))
 
+(defn ^:private ->scope-keyword [scope]
+  (cond
+    (nil? scope) :global
+    (keyword? scope) scope
+    (string? scope) (keyword scope)
+    :else :global))
+
+(defn mcp-add-server
+  "Add a new MCP server definition at runtime.
+
+   Params:
+     :name           (required) server identifier.
+     :command :args :env           for stdio servers.
+     :url :headers :clientId :clientSecret :oauthPort  for HTTP servers.
+     :disabled       optional boolean.
+     :scope          \"global\" (default) or \"workspace\".
+     :workspaceUri   required when :scope = \"workspace\".
+
+   Returns the canonical server map (as sent over tool/serverUpdated) with
+   status :starting, :disabled, or :failed."
+  [{:keys [db* messenger metrics config]} params]
+  (metrics/task metrics :eca/mcp-add-server
+    (let [server-name (:name params)
+          server-config (cond-> {}
+                          (:command params)       (assoc :command (:command params))
+                          (:args params)          (assoc :args (:args params))
+                          (:env params)           (assoc :env (:env params))
+                          (:url params)           (assoc :url (:url params))
+                          (:headers params)       (assoc :headers (:headers params))
+                          (:clientId params)      (assoc :clientId (:clientId params))
+                          (:clientSecret params)  (assoc :clientSecret (:clientSecret params))
+                          (:oauthPort params)     (assoc :oauthPort (:oauthPort params))
+                          (contains? params :disabled) (assoc :disabled (boolean (:disabled params))))
+          opts {:scope (->scope-keyword (or (:scope params) (:workspaceScope params)))
+                :workspace-uri (or (:workspaceUri params) (:workspace-uri params))}]
+      (try
+        (let [server (f.tools/add-server! server-name server-config opts db* messenger config metrics)]
+          {:server server})
+        (catch clojure.lang.ExceptionInfo e
+          {:error {:code "invalid_request"
+                   :message (.getMessage e)
+                   :data (ex-data e)}})))))
+
+(defn mcp-remove-server
+  "Remove an MCP server definition at runtime. Stops the server if running,
+   removes the entry from the owning config file, and emits tool/serverRemoved.
+
+   Params:
+     :name  (required)"
+  [{:keys [db* messenger metrics config]} params]
+  (metrics/task metrics :eca/mcp-remove-server
+    (try
+      (f.tools/remove-server! (:name params) db* messenger config metrics)
+      (catch clojure.lang.ExceptionInfo e
+        {:error {:code "invalid_request"
+                 :message (.getMessage e)
+                 :data (ex-data e)}}))))
+
 (defn ^:private update-agent-model-and-variants!
   "Updates the selected model and variants based on agent configuration."
   [agent-config config messenger db*]

src/eca/messenger.clj

@@ -12,6 +12,7 @@
   (chat-opened [this params])
   (rewrite-content-received [this data])
   (tool-server-updated [this params])
+  (tool-server-removed [this params])
   (config-updated [this params])
   (provider-updated [this params])
   (jobs-updated [this params])

src/eca/remote/handlers.clj

@@ -291,6 +291,23 @@
     (handlers/mcp-enable-server (assoc components :config config) {:name server-name})
     (no-content)))
 
+(defn handle-mcp-add [{:keys [db*] :as components} request]
+  (let [body (parse-body request)]
+    (if-not (:name body)
+      (error-response 400 "invalid_request" "Missing required field: name")
+      (let [config (config/all @db*)
+            result (handlers/mcp-add-server (assoc components :config config) body)]
+        (if-let [{:keys [code message]} (:error result)]
+          (error-response 400 (or code "invalid_request") (or message "Failed to add MCP server"))
+          (json-response (camel-keys result)))))))
+
+(defn handle-mcp-remove [{:keys [db*] :as components} _request server-name]
+  (let [config (config/all @db*)
+        result (handlers/mcp-remove-server (assoc components :config config) {:name server-name})]
+    (if-let [{:keys [code message]} (:error result)]
+      (error-response 400 (or code "invalid_request") (or message "Failed to remove MCP server"))
+      (no-content))))
+
 (deftype SSEBody [db* sse-connections*]
   ring.protocols/StreamableResponseBody
   (write-body-to-stream [_ _response os]

src/eca/remote/messenger.clj

@@ -41,6 +41,10 @@
     (messenger/tool-server-updated inner params)
     (sse/broadcast! sse-connections* "tool:server-updated" (->camel params)))
 
+  (tool-server-removed [_this params]
+    (messenger/tool-server-removed inner params)
+    (sse/broadcast! sse-connections* "tool:server-removed" (->camel params)))
+
   (provider-updated [_this params]
     (messenger/provider-updated inner params)
     (sse/broadcast! sse-connections* "providers:updated" (->camel params)))