fix: Show MCP connection errors in the UI (#11495)

* fix(mcp): surface configured server failures

Keep model-configured MCP servers visible when discovery or connection setup fails, propagate status through distributed discovery, and let the Chat UI show actionable errors while retrying unavailable servers.

Add model-editor metadata for remote and stdio configuration and document the expected format, deployment networking boundary, and alternate MCP scopes.

Assisted-by: Codex:gpt-5 Ordino golangci-lint
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* build(compose): match CUDA development image

Configure the API image with the cublas, CUDA 13, auth-tagged build settings used by the local development Makefile invocation, including the 24-way Docker build.

Assisted-by: Codex:gpt-5 Ordino
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* revert: keep host build settings out of compose

The CUDA development deployment is managed from ~/docker/localai, not the repository example Compose file. Restore the generic example and keep machine-specific build settings in the host deployment.

Assisted-by: Codex:gpt-5 Ordino
Signed-off-by: Richard Palethorpe <io@richiejp.com>

* fix(docker): exclude local agent artifacts

Keep Claude worktrees and locally installed verification tools out of the Docker build context. These host-only directories added roughly 1.9 GB to every root image build.

Assisted-by: Codex:gpt-5 Ordino
Signed-off-by: Richard Palethorpe <io@richiejp.com>

---------

Signed-off-by: Richard Palethorpe <io@richiejp.com>

Author: richiejp

.dockerignore

@@ -59,7 +59,9 @@ backend/rust/*/target
 backend-images
 local-backends
 local-ai
+.claude
 .crush
+.tools
 protoc
 tests
 

core/cli/agent_worker.go

@@ -351,6 +351,7 @@ func handleMCPDiscoveryRequest(data []byte, reply func([]byte)) {
 			Tools:     s.Tools,
 			Prompts:   s.Prompts,
 			Resources: s.Resources,
+			Error:     s.Error,
 		})
 	}
 

core/config/meta/registry.go

@@ -752,6 +752,24 @@ func DefaultRegistry() map[string]FieldMetaOverride {
 			Order:       72,
 		},
 
+		// --- MCP ---
+		"mcp.remote": {
+			Section:     "mcp",
+			Label:       "Remote MCP Servers",
+			Description: "YAML or JSON string containing an mcpServers map of named remote Streamable HTTP endpoints. Each entry requires url; token optionally enables Bearer authentication.",
+			Component:   "code-editor",
+			Language:    "yaml",
+			Order:       130,
+		},
+		"mcp.stdio": {
+			Section:     "mcp",
+			Label:       "MCP STDIO Servers",
+			Description: "YAML or JSON string containing an mcpServers map of named local commands. Each entry requires command and may include args and env.",
+			Component:   "code-editor",
+			Language:    "yaml",
+			Order:       131,
+		},
+
 		// --- TTS ---
 		"tts.voice_cloning": {
 			Section:     "tts",

core/config/meta/registry_coverage_test.go

@@ -185,8 +185,6 @@ var grandfatheredUnregistered = []string{
 	"lora_scales",
 	"main_gpu",
 	"max_model_len",
-	"mcp.remote",
-	"mcp.stdio",
 	"mirostat",
 	"mirostat_eta",
 	"mirostat_tau",

core/config/meta/registry_test.go

@@ -1,6 +1,9 @@
 package meta_test
 
 import (
+	"reflect"
+
+	"github.com/mudler/LocalAI/core/config"
 	"github.com/mudler/LocalAI/core/config/meta"
 
 	. "github.com/onsi/ginkgo/v2"
@@ -26,3 +29,30 @@ var _ = Describe("alias field metadata", func() {
 		Expect(found).To(BeTrue(), "DefaultSections should include an alias section")
 	})
 })
+
+var _ = Describe("MCP field metadata", func() {
+	var fields map[string]meta.FieldMeta
+
+	BeforeEach(func() {
+		md := meta.BuildForTest(reflect.TypeOf(config.ModelConfig{}), meta.DefaultRegistry())
+		fields = make(map[string]meta.FieldMeta, len(md.Fields))
+		for _, field := range md.Fields {
+			fields[field.Path] = field
+		}
+	})
+
+	DescribeTable("registers embedded MCP configuration as YAML code",
+		func(path, label, transportDetail string) {
+			f, ok := fields[path]
+			Expect(ok).To(BeTrue(), "%s should be present in generated metadata", path)
+			Expect(f.Section).To(Equal("mcp"))
+			Expect(f.Label).To(Equal(label))
+			Expect(f.Description).To(ContainSubstring("mcpServers"))
+			Expect(f.Description).To(ContainSubstring(transportDetail))
+			Expect(f.Component).To(Equal("code-editor"))
+			Expect(f.Language).To(Equal("yaml"))
+		},
+		Entry("remote servers", "mcp.remote", "Remote MCP Servers", "Streamable HTTP"),
+		Entry("stdio servers", "mcp.stdio", "MCP STDIO Servers", "local commands"),
+	)
+})

core/http/endpoints/localai/mcp_tools.go

@@ -3,6 +3,7 @@ package localai
 import (
 	"fmt"
 	"net/http"
+	"sort"
 
 	"github.com/labstack/echo/v4"
 	"github.com/mudler/LocalAI/core/config"
@@ -37,15 +38,22 @@ func MCPServersEndpoint(cl *config.ModelConfigLoader, appConfig *config.Applicat
 
 		remote, stdio, err := cfg.MCP.MCPConfigFromYAML()
 		if err != nil {
-			return fmt.Errorf("failed to parse MCP config: %w", err)
+			return c.JSON(http.StatusUnprocessableEntity, map[string]any{
+				"model":   modelName,
+				"servers": []any{},
+				"error":   fmt.Sprintf("failed to parse MCP config: %v", err),
+			})
 		}
 
 		// In distributed mode, route discovery through NATS to an agent worker
 		// that can actually connect to the MCP servers.
 		if natsClient != nil {
 			resp, err := mcpTools.DiscoverMCPToolsRemote(c.Request().Context(), natsClient, cfg.Name, remote, stdio)
 			if err != nil {
-				return fmt.Errorf("remote MCP discovery failed: %w", err)
+				return c.JSON(http.StatusOK, map[string]any{
+					"model":   modelName,
+					"servers": unavailableMCPServers(remote, stdio, fmt.Sprintf("remote discovery failed: %v", err)),
+				})
 			}
 			return c.JSON(200, map[string]any{
 				"model":   modelName,
@@ -88,14 +96,21 @@ func MCPServersEndpointFromMiddleware(natsClient mcpTools.MCPNATSClient) echo.Ha
 
 		remote, stdio, err := cfg.MCP.MCPConfigFromYAML()
 		if err != nil {
-			return fmt.Errorf("failed to parse MCP config: %w", err)
+			return c.JSON(http.StatusUnprocessableEntity, map[string]any{
+				"model":   cfg.Name,
+				"servers": []any{},
+				"error":   fmt.Sprintf("failed to parse MCP config: %v", err),
+			})
 		}
 
 		// In distributed mode, route discovery through NATS to an agent worker.
 		if natsClient != nil {
 			resp, err := mcpTools.DiscoverMCPToolsRemote(c.Request().Context(), natsClient, cfg.Name, remote, stdio)
 			if err != nil {
-				return fmt.Errorf("remote MCP discovery failed: %w", err)
+				return c.JSON(http.StatusOK, map[string]any{
+					"model":   cfg.Name,
+					"servers": unavailableMCPServers(remote, stdio, fmt.Sprintf("remote discovery failed: %v", err)),
+				})
 			}
 			return c.JSON(200, map[string]any{
 				"model":   cfg.Name,
@@ -119,3 +134,24 @@ func MCPServersEndpointFromMiddleware(natsClient mcpTools.MCPNATSClient) echo.Ha
 		})
 	}
 }
+
+func unavailableMCPServers(
+	remote config.MCPGenericConfig[config.MCPRemoteServers],
+	stdio config.MCPGenericConfig[config.MCPSTDIOServers],
+	errMessage string,
+) []mcpTools.MCPServerInfo {
+	servers := make([]mcpTools.MCPServerInfo, 0, len(remote.Servers)+len(stdio.Servers))
+	for name := range remote.Servers {
+		servers = append(servers, mcpTools.MCPServerInfo{Name: name, Type: "remote", Tools: []string{}, Error: errMessage})
+	}
+	for name := range stdio.Servers {
+		servers = append(servers, mcpTools.MCPServerInfo{Name: name, Type: "stdio", Tools: []string{}, Error: errMessage})
+	}
+	sort.Slice(servers, func(i, j int) bool {
+		if servers[i].Type != servers[j].Type {
+			return servers[i].Type < servers[j].Type
+		}
+		return servers[i].Name < servers[j].Name
+	})
+	return servers
+}

core/http/endpoints/localai/mcp_tools_internal_test.go

@@ -0,0 +1,34 @@
+package localai
+
+import (
+	"testing"
+
+	"github.com/mudler/LocalAI/core/config"
+	"github.com/onsi/gomega"
+)
+
+func TestUnavailableMCPServersIncludesEveryConfiguredServer(t *testing.T) {
+	g := gomega.NewWithT(t)
+	remote := config.MCPGenericConfig[config.MCPRemoteServers]{
+		Servers: config.MCPRemoteServers{
+			"zeta":  {URL: "http://zeta/mcp"},
+			"alpha": {URL: "http://alpha/mcp"},
+		},
+	}
+	stdio := config.MCPGenericConfig[config.MCPSTDIOServers]{
+		Servers: config.MCPSTDIOServers{
+			"worker": {Command: "mcp-worker"},
+		},
+	}
+
+	servers := unavailableMCPServers(remote, stdio, "remote discovery failed: timeout")
+	g.Expect(servers).To(gomega.HaveLen(3))
+	g.Expect([]string{
+		servers[0].Type + ":" + servers[0].Name,
+		servers[1].Type + ":" + servers[1].Name,
+		servers[2].Type + ":" + servers[2].Name,
+	}).To(gomega.Equal([]string{"remote:alpha", "remote:zeta", "stdio:worker"}))
+	for _, server := range servers {
+		g.Expect(server.Error).To(gomega.Equal("remote discovery failed: timeout"))
+	}
+}

core/http/endpoints/mcp/server_status_test.go

@@ -0,0 +1,54 @@
+package mcp
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+
+	"github.com/mudler/LocalAI/core/config"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("MCP server status discovery", func() {
+	It("keeps configured servers visible when connection fails and retries them", func() {
+		var requests atomic.Int32
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			requests.Add(1)
+			http.Error(w, "temporarily unavailable", http.StatusServiceUnavailable)
+		}))
+		DeferCleanup(server.Close)
+
+		modelName := "unavailable-mcp-status-test"
+		DeferCleanup(func() { CloseMCPSessions(modelName) })
+		remote := config.MCPGenericConfig[config.MCPRemoteServers]{
+			Servers: config.MCPRemoteServers{
+				"ordino": {URL: server.URL},
+			},
+		}
+
+		sessions, err := NamedSessionsFromMCPConfig(modelName, remote, config.MCPGenericConfig[config.MCPSTDIOServers]{}, nil)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(sessions).To(HaveLen(1))
+		Expect(sessions[0].Name).To(Equal("ordino"))
+		Expect(sessions[0].Type).To(Equal("remote"))
+		Expect(sessions[0].Session).To(BeNil())
+		Expect(sessions[0].Error).To(ContainSubstring("connection failed"))
+
+		servers, err := ListMCPServers(context.Background(), sessions)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(servers).To(HaveLen(1))
+		Expect(servers[0].Name).To(Equal("ordino"))
+		Expect(servers[0].Error).To(ContainSubstring("connection failed"))
+
+		tools, err := DiscoverMCPTools(context.Background(), sessions)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(tools).To(BeEmpty())
+
+		_, err = NamedSessionsFromMCPConfig(modelName, remote, config.MCPGenericConfig[config.MCPSTDIOServers]{}, nil)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(requests.Load()).To(BeNumerically(">=", 2), "failed sessions should be retried instead of cached forever")
+	})
+})