feat: make agent context paths configurable via env vars (#23878)

Replace hardcoded paths for instruction files, skills, and MCP config
with
values read from `CODER_AGENT_EXP_*` environment variables. Template
authors
configure paths via the existing `coder_agent` `env` block. The agent
resolves `~`, relative, and absolute paths locally, then serves the
resolved config over `GET /api/v0/context-config`. `chatd` fetches this
once per workspace attach and falls back to today's defaults for older
agents.

All path env vars are comma-separated, allowing multiple directories:

| Env Var | Default | Controls |
|---|---|---|
| `CODER_AGENT_EXP_INSTRUCTIONS_DIRS` | `~/.coder` | Dirs containing the
instruction file |
| `CODER_AGENT_EXP_INSTRUCTIONS_FILE` | `AGENTS.md` | Instruction file
name |
| `CODER_AGENT_EXP_SKILLS_DIRS` | `.agents/skills` | Skills directories
|
| `CODER_AGENT_EXP_SKILL_META_FILE` | `SKILL.md` | Skill metadata file
name |
| `CODER_AGENT_EXP_MCP_CONFIG_FILES` | `.mcp.json` | MCP config files |

### Example

```hcl
resource "coder_agent" "main" {
  os   = "linux"
  arch = "amd64"
  env = {
    CODER_AGENT_EXP_INSTRUCTIONS_DIRS  = "/opt/company/agent-config,~/.coder"
    CODER_AGENT_EXP_INSTRUCTIONS_FILE  = "CLAUDE.md"
    CODER_AGENT_EXP_SKILLS_DIRS        = "/opt/company/ai-skills,.agents/skills"
    CODER_AGENT_EXP_MCP_CONFIG_FILES   = "/opt/company/mcp.json,.mcp.json"
  }
}
```

<details>
<summary>Implementation Details</summary>

### Architecture

Follows the same pattern as MCP tool discovery:
agent resolves locally → exposes via HTTP → chatd consumes.

**Agent-side** (`agent/agentcontextconfig/`):
- `ResolvePath` / `ResolvePaths` handle `~`, relative, and absolute path
forms; returns `""` for relative paths when baseDir is empty
- `Config` reads env vars, falls back to defaults, resolves all paths
- `GET /api/v0/context-config` serves the resolved config as JSON

**chatd-side** (`coderd/x/chatd/`):
- Calls `conn.ContextConfig()` once on first workspace attach
- Falls back to hardcoded defaults on 404 (older agents)
- Iterates instruction dirs, skills dirs using resolved absolute paths
- `LSRelativityRoot` everywhere — no more home/root juggling

### Key design decisions

- **`EXP_` prefix**: env vars use `CODER_AGENT_EXP_*` to indicate
experimental status
- **Plural names**: comma-separated vars use plural names (`DIRS`,
`FILES`); single-value vars use singular (`FILE`)
- **Defaults in `workspacesdk`**: default constants live in
`codersdk/workspacesdk/` so both agent and server reference them without
cross-layer imports
- **`skillMetaFile` persistence**: stored on context-file parts via
`ContextFileSkillMetaFile` and restored on subsequent chat turns so
custom values survive across turns
- **Working dir dedup**: `slices.Contains` guard prevents reading the
same instruction file from both `InstructionsDirs` and the working
directory
- **MCP server dedup**: first-occurrence-wins dedup prevents leaking
duplicate connections from overlapping config files
- **ResolvePath safety**: returns `""` for relative paths when `baseDir`
is empty, so `ResolvePaths` filters them out

### Files changed

| File | Change |
|---|---|
| `agent/agentcontextconfig/` | New package — path resolution + HTTP
endpoint |
| `codersdk/workspacesdk/agentconn.go` | `ContextConfigResponse` type,
default constants, client method |
| `agent/agent.go` + `agent/api.go` | Wire up endpoint, pass config to
MCP |
| `agent/x/agentmcp/manager.go` | Accept `[]string` MCP config paths,
dedup by name |
| `coderd/x/chatd/chatd.go` | Fetch config, thread through, named
returns |
| `coderd/x/chatd/instruction.go` | Accept configurable dir + file name,
`skillMetaFileFromParts` |
| `coderd/x/chatd/chattool/skill.go` | Accept configurable dirs + meta
file |
| `codersdk/chats.go` | `ContextFileSkillMetaFile` field for persistence
|

### Test coverage

- `TestConfig` (4 cases): defaults, custom env vars, whitespace
trimming, comma-separated dirs
- `TestResolvePath` / `TestResolvePaths`: including empty baseDir edge
case
- `TestPersistInstructionFilesFallbackOnOlderAgent`: backward-compat
path when `ContextConfig` returns 404
- `TestChatMessagePartVariantTags`: updated exclusion list for new
internal field

### Backward compatibility

Older agents return 404 for the new endpoint. `chatd` catches this and
falls back to today's defaults via `readHomeInstructionFile` (using
`LSRelativityHome`). Existing workspaces work with no changes.

</details>

agent/agent.go

@@ -38,6 +38,7 @@ import (
 	"cdr.dev/slog/v3"
 	"github.com/coder/clistat"
 	"github.com/coder/coder/v2/agent/agentcontainers"
+	"github.com/coder/coder/v2/agent/agentcontextconfig"
 	"github.com/coder/coder/v2/agent/agentexec"
 	"github.com/coder/coder/v2/agent/agentfiles"
 	"github.com/coder/coder/v2/agent/agentgit"
@@ -308,12 +309,13 @@ type agent struct {
 	containerAPI        *agentcontainers.API
 	gitAPIOptions       []agentgit.Option
 
-	filesAPI   *agentfiles.API
-	gitAPI     *agentgit.API
-	processAPI *agentproc.API
-	desktopAPI *agentdesktop.API
-	mcpManager *agentmcp.Manager
-	mcpAPI     *agentmcp.API
+	filesAPI         *agentfiles.API
+	gitAPI           *agentgit.API
+	processAPI       *agentproc.API
+	desktopAPI       *agentdesktop.API
+	mcpManager       *agentmcp.Manager
+	mcpAPI           *agentmcp.API
+	contextConfigAPI *agentcontextconfig.API
 
 	socketServerEnabled bool
 	socketPath          string
@@ -1263,6 +1265,12 @@ func (a *agent) handleManifest(manifestOK *checkpoint) func(ctx context.Context,
 			return xerrors.Errorf("update workspace agent startup: %w", err)
 		}
 
+		// Initialize the context config API with the expanded
+		// working directory so that it is ready before the HTTP
+		// handler is created (which happens after manifestOK).
+		a.contextConfigAPI = agentcontextconfig.NewAPI(
+			manifest.Directory,
+		)
 		oldManifest := a.manifest.Swap(&manifest)
 		manifestOK.complete(nil)
 		sentResult = true
@@ -1358,7 +1366,7 @@ func (a *agent) handleManifest(manifestOK *checkpoint) func(ctx context.Context,
 				// lifecycle transition to avoid delaying Ready.
 				// This runs inside the tracked goroutine so it
 				// is properly awaited on shutdown.
-				if mcpErr := a.mcpManager.Connect(a.gracefulCtx, manifest.Directory); mcpErr != nil {
+				if mcpErr := a.mcpManager.Connect(a.gracefulCtx, a.contextConfigAPI.Config().MCPConfigFiles); mcpErr != nil {
 					a.logger.Warn(ctx, "failed to connect to workspace MCP servers", slog.Error(mcpErr))
 				}
 			})

agent/agentcontextconfig/api.go

@@ -0,0 +1,83 @@
+package agentcontextconfig
+
+import (
+	"cmp"
+	"net/http"
+	"os"
+	"strings"
+
+	"github.com/go-chi/chi/v5"
+
+	"github.com/coder/coder/v2/coderd/httpapi"
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
+)
+
+// Env var names for context configuration. Prefixed with EXP_
+// to indicate these are experimental and may change.
+const (
+	EnvInstructionsDirs = "CODER_AGENT_EXP_INSTRUCTIONS_DIRS"
+	EnvInstructionsFile = "CODER_AGENT_EXP_INSTRUCTIONS_FILE"
+	EnvSkillsDirs       = "CODER_AGENT_EXP_SKILLS_DIRS"
+	EnvSkillMetaFile    = "CODER_AGENT_EXP_SKILL_META_FILE"
+	EnvMCPConfigFiles   = "CODER_AGENT_EXP_MCP_CONFIG_FILES"
+)
+
+// Defaults are defined in codersdk/workspacesdk so both
+// the agent and server can reference them without a
+// cross-layer import.
+
+// API exposes the resolved context configuration through the
+// agent's HTTP API.
+type API struct {
+	config workspacesdk.ContextConfigResponse
+}
+
+// NewAPI reads context configuration from environment variables,
+// resolves all paths relative to workingDir, and returns an API
+// handler that serves the result.
+func NewAPI(workingDir string) *API {
+	return &API{
+		config: Config(workingDir),
+	}
+}
+
+// Config reads env vars and resolves paths. Exported for use
+// by the MCP manager and tests.
+func Config(workingDir string) workspacesdk.ContextConfigResponse {
+	// TrimSpace all env vars before cmp.Or so that a
+	// whitespace-only value falls through to the default
+	// consistently. ResolvePaths also trims each comma-
+	// separated entry, but without pre-trimming here a
+	// bare " " would bypass cmp.Or and produce nil.
+	instructionsDir := cmp.Or(strings.TrimSpace(os.Getenv(EnvInstructionsDirs)), workspacesdk.DefaultInstructionsDir)
+	instructionsFile := cmp.Or(strings.TrimSpace(os.Getenv(EnvInstructionsFile)), workspacesdk.DefaultInstructionsFile)
+	skillsDir := cmp.Or(strings.TrimSpace(os.Getenv(EnvSkillsDirs)), workspacesdk.DefaultSkillsDir)
+	skillMetaFile := cmp.Or(strings.TrimSpace(os.Getenv(EnvSkillMetaFile)), workspacesdk.DefaultSkillMetaFile)
+	mcpConfigFile := cmp.Or(strings.TrimSpace(os.Getenv(EnvMCPConfigFiles)), workspacesdk.DefaultMCPConfigFile)
+
+	return workspacesdk.ContextConfigResponse{
+		InstructionsDirs: ResolvePaths(instructionsDir, workingDir),
+		InstructionsFile: instructionsFile,
+		SkillsDirs:       ResolvePaths(skillsDir, workingDir),
+		SkillMetaFile:    skillMetaFile,
+		MCPConfigFiles:   ResolvePaths(mcpConfigFile, workingDir),
+	}
+}
+
+// Config returns the resolved config for use by other agent
+// components (e.g. MCP manager).
+func (api *API) Config() workspacesdk.ContextConfigResponse {
+	return api.config
+}
+
+// Routes returns the HTTP handler for the context config
+// endpoint.
+func (api *API) Routes() http.Handler {
+	r := chi.NewRouter()
+	r.Get("/", api.handleGet)
+	return r
+}
+
+func (api *API) handleGet(rw http.ResponseWriter, r *http.Request) {
+	httpapi.Write(r.Context(), rw, http.StatusOK, api.config)
+}

agent/agentcontextconfig/api_test.go

@@ -0,0 +1,95 @@
+package agentcontextconfig_test
+
+import (
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/v2/agent/agentcontextconfig"
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
+)
+
+func TestConfig(t *testing.T) {
+	t.Run("Defaults", func(t *testing.T) {
+		fakeHome := t.TempDir()
+		t.Setenv("HOME", fakeHome)
+		t.Setenv("USERPROFILE", fakeHome)
+
+		// Clear all env vars so defaults are used.
+		t.Setenv(agentcontextconfig.EnvInstructionsDirs, "")
+		t.Setenv(agentcontextconfig.EnvInstructionsFile, "")
+		t.Setenv(agentcontextconfig.EnvSkillsDirs, "")
+		t.Setenv(agentcontextconfig.EnvSkillMetaFile, "")
+		t.Setenv(agentcontextconfig.EnvMCPConfigFiles, "")
+
+		workDir := platformAbsPath("work")
+		cfg := agentcontextconfig.Config(workDir)
+
+		require.Equal(t, workspacesdk.DefaultInstructionsFile, cfg.InstructionsFile)
+		require.Equal(t, workspacesdk.DefaultSkillMetaFile, cfg.SkillMetaFile)
+		// Default instructions dir is "~/.coder" which resolves
+		// to the home directory.
+		require.Equal(t, []string{filepath.Join(fakeHome, ".coder")}, cfg.InstructionsDirs)
+		// Default skills dir is ".agents/skills" (relative),
+		// resolved against the working directory.
+		require.Equal(t, []string{filepath.Join(workDir, ".agents", "skills")}, cfg.SkillsDirs)
+		// Default MCP config file is ".mcp.json" (relative),
+		// resolved against the working directory.
+		require.Equal(t, []string{filepath.Join(workDir, ".mcp.json")}, cfg.MCPConfigFiles)
+	})
+
+	t.Run("CustomEnvVars", func(t *testing.T) {
+		fakeHome := t.TempDir()
+		t.Setenv("HOME", fakeHome)
+		t.Setenv("USERPROFILE", fakeHome)
+
+		optInstructions := platformAbsPath("opt", "instructions")
+		optSkills := platformAbsPath("opt", "skills")
+		optMCP := platformAbsPath("opt", "mcp.json")
+
+		t.Setenv(agentcontextconfig.EnvInstructionsDirs, optInstructions)
+		t.Setenv(agentcontextconfig.EnvInstructionsFile, "CUSTOM.md")
+		t.Setenv(agentcontextconfig.EnvSkillsDirs, optSkills)
+		t.Setenv(agentcontextconfig.EnvSkillMetaFile, "META.yaml")
+		t.Setenv(agentcontextconfig.EnvMCPConfigFiles, optMCP)
+
+		workDir := platformAbsPath("work")
+		cfg := agentcontextconfig.Config(workDir)
+
+		require.Equal(t, "CUSTOM.md", cfg.InstructionsFile)
+		require.Equal(t, "META.yaml", cfg.SkillMetaFile)
+		require.Equal(t, []string{optInstructions}, cfg.InstructionsDirs)
+		require.Equal(t, []string{optSkills}, cfg.SkillsDirs)
+		require.Equal(t, []string{optMCP}, cfg.MCPConfigFiles)
+	})
+
+	t.Run("WhitespaceInFileNames", func(t *testing.T) {
+		t.Setenv(agentcontextconfig.EnvInstructionsDirs, "")
+		t.Setenv(agentcontextconfig.EnvInstructionsFile, "  CLAUDE.md  ")
+		t.Setenv(agentcontextconfig.EnvSkillsDirs, "")
+		t.Setenv(agentcontextconfig.EnvSkillMetaFile, "")
+		t.Setenv(agentcontextconfig.EnvMCPConfigFiles, "")
+
+		workDir := platformAbsPath("work")
+		cfg := agentcontextconfig.Config(workDir)
+
+		require.Equal(t, "CLAUDE.md", cfg.InstructionsFile)
+	})
+
+	t.Run("CommaSeparatedDirs", func(t *testing.T) {
+		a := platformAbsPath("opt", "a")
+		b := platformAbsPath("opt", "b")
+
+		t.Setenv(agentcontextconfig.EnvInstructionsDirs, a+","+b)
+		t.Setenv(agentcontextconfig.EnvInstructionsFile, "")
+		t.Setenv(agentcontextconfig.EnvSkillsDirs, "")
+		t.Setenv(agentcontextconfig.EnvSkillMetaFile, "")
+		t.Setenv(agentcontextconfig.EnvMCPConfigFiles, "")
+
+		workDir := platformAbsPath("work")
+		cfg := agentcontextconfig.Config(workDir)
+
+		require.Equal(t, []string{a, b}, cfg.InstructionsDirs)
+	})
+}

agent/agentcontextconfig/resolve.go

@@ -0,0 +1,55 @@
+package agentcontextconfig
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// ResolvePath resolves a single path that may be absolute,
+// home-relative (~/ or ~), or relative to the given base
+// directory. Returns an absolute path. Empty input returns empty.
+func ResolvePath(raw, baseDir string) string {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return ""
+	}
+	switch {
+	case raw == "~":
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return ""
+		}
+		return home
+	case strings.HasPrefix(raw, "~/"):
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return ""
+		}
+		return filepath.Join(home, raw[2:])
+	case filepath.IsAbs(raw):
+		return raw
+	default:
+		if baseDir == "" {
+			return ""
+		}
+		return filepath.Join(baseDir, raw)
+	}
+}
+
+// ResolvePaths splits a comma-separated list of paths and
+// resolves each entry independently. Empty entries and entries
+// that resolve to empty strings are skipped.
+func ResolvePaths(raw, baseDir string) []string {
+	if strings.TrimSpace(raw) == "" {
+		return nil
+	}
+	parts := strings.Split(raw, ",")
+	out := make([]string, 0, len(parts))
+	for _, p := range parts {
+		if resolved := ResolvePath(p, baseDir); resolved != "" {
+			out = append(out, resolved)
+		}
+	}
+	return out
+}

agent/agentcontextconfig/resolve_test.go

@@ -0,0 +1,152 @@
+package agentcontextconfig_test
+
+import (
+	"path/filepath"
+	"runtime"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/v2/agent/agentcontextconfig"
+)
+
+// platformAbsPath constructs an absolute path that is valid
+// on the current platform. On Windows paths must include a
+// drive letter to be considered absolute.
+func platformAbsPath(parts ...string) string {
+	if runtime.GOOS == "windows" {
+		return `C:\` + filepath.Join(parts...)
+	}
+	return "/" + filepath.Join(parts...)
+}
+
+func TestResolvePath(t *testing.T) { //nolint:tparallel // subtests using t.Setenv cannot be parallel
+	t.Run("EmptyInput", func(t *testing.T) {
+		t.Parallel()
+		require.Equal(t, "", agentcontextconfig.ResolvePath("", platformAbsPath("base")))
+	})
+
+	t.Run("WhitespaceOnly", func(t *testing.T) {
+		t.Parallel()
+		require.Equal(t, "", agentcontextconfig.ResolvePath("   ", platformAbsPath("base")))
+	})
+
+	// Tests that use t.Setenv cannot be parallel.
+	t.Run("TildeAlone", func(t *testing.T) {
+		fakeHome := t.TempDir()
+		t.Setenv("HOME", fakeHome)
+		t.Setenv("USERPROFILE", fakeHome)
+		got := agentcontextconfig.ResolvePath("~", platformAbsPath("base"))
+		require.Equal(t, fakeHome, got)
+	})
+
+	t.Run("TildeSlashPath", func(t *testing.T) {
+		fakeHome := t.TempDir()
+		t.Setenv("HOME", fakeHome)
+		t.Setenv("USERPROFILE", fakeHome)
+		got := agentcontextconfig.ResolvePath("~/docs/readme", platformAbsPath("base"))
+		require.Equal(t, filepath.Join(fakeHome, "docs", "readme"), got)
+	})
+
+	t.Run("AbsolutePath", func(t *testing.T) {
+		t.Parallel()
+		p := platformAbsPath("etc", "coder")
+		got := agentcontextconfig.ResolvePath(p, platformAbsPath("base"))
+		require.Equal(t, p, got)
+	})
+
+	t.Run("RelativePath", func(t *testing.T) {
+		t.Parallel()
+		base := platformAbsPath("work")
+		got := agentcontextconfig.ResolvePath("foo/bar", base)
+		require.Equal(t, filepath.Join(base, "foo", "bar"), got)
+	})
+
+	t.Run("RelativePathWithWhitespace", func(t *testing.T) {
+		t.Parallel()
+		base := platformAbsPath("work")
+		got := agentcontextconfig.ResolvePath("  foo/bar  ", base)
+		require.Equal(t, filepath.Join(base, "foo", "bar"), got)
+	})
+
+	t.Run("RelativePathWithEmptyBaseDir", func(t *testing.T) {
+		t.Parallel()
+		got := agentcontextconfig.ResolvePath(".agents/skills", "")
+		require.Equal(t, "", got)
+	})
+}
+
+func TestResolvePath_HomeUnset(t *testing.T) {
+	// Cannot be parallel — modifies HOME env var.
+	t.Setenv("HOME", "")
+	// Also clear USERPROFILE for Windows compatibility.
+	t.Setenv("USERPROFILE", "")
+
+	require.Equal(t, "", agentcontextconfig.ResolvePath("~", platformAbsPath("base")))
+	require.Equal(t, "", agentcontextconfig.ResolvePath("~/docs", platformAbsPath("base")))
+}
+
+func TestResolvePaths(t *testing.T) { //nolint:tparallel // subtests using t.Setenv cannot be parallel
+	t.Run("EmptyString", func(t *testing.T) {
+		t.Parallel()
+		require.Nil(t, agentcontextconfig.ResolvePaths("", platformAbsPath("base")))
+	})
+
+	t.Run("WhitespaceOnly", func(t *testing.T) {
+		t.Parallel()
+		require.Nil(t, agentcontextconfig.ResolvePaths("   ", platformAbsPath("base")))
+	})
+
+	t.Run("SingleEntry", func(t *testing.T) {
+		t.Parallel()
+		p := platformAbsPath("abs", "path")
+		got := agentcontextconfig.ResolvePaths(p, platformAbsPath("base"))
+		require.Equal(t, []string{p}, got)
+	})
+
+	// Tests that use t.Setenv cannot be parallel.
+	t.Run("MultipleEntries", func(t *testing.T) {
+		fakeHome := t.TempDir()
+		t.Setenv("HOME", fakeHome)
+		t.Setenv("USERPROFILE", fakeHome)
+		b := platformAbsPath("b")
+		base := platformAbsPath("base")
+		got := agentcontextconfig.ResolvePaths("~/a,"+b+",rel", base)
+		require.Equal(t, []string{
+			filepath.Join(fakeHome, "a"),
+			b,
+			filepath.Join(base, "rel"),
+		}, got)
+	})
+
+	t.Run("TrimsWhitespace", func(t *testing.T) {
+		t.Parallel()
+		a := platformAbsPath("a")
+		b := platformAbsPath("b")
+		got := agentcontextconfig.ResolvePaths("  "+a+" , "+b+"  ", platformAbsPath("base"))
+		require.Equal(t, []string{a, b}, got)
+	})
+
+	t.Run("SkipsEmptyEntries", func(t *testing.T) {
+		t.Parallel()
+		a := platformAbsPath("a")
+		b := platformAbsPath("b")
+		got := agentcontextconfig.ResolvePaths(a+",,"+b+",", platformAbsPath("base"))
+		require.Equal(t, []string{a, b}, got)
+	})
+
+	t.Run("TrailingComma", func(t *testing.T) {
+		t.Parallel()
+		p := platformAbsPath("only")
+		got := agentcontextconfig.ResolvePaths(p+",", platformAbsPath("base"))
+		require.Equal(t, []string{p}, got)
+	})
+
+	t.Run("RelativePathSkippedWhenBaseDirEmpty", func(t *testing.T) {
+		fakeHome := t.TempDir()
+		t.Setenv("HOME", fakeHome)
+		t.Setenv("USERPROFILE", fakeHome)
+		got := agentcontextconfig.ResolvePaths("~/.coder,.agents/skills", "")
+		require.Equal(t, []string{filepath.Join(fakeHome, ".coder")}, got)
+	})
+}

agent/api.go

@@ -32,6 +32,7 @@ func (a *agent) apiHandler() http.Handler {
 	r.Mount("/api/v0/processes", a.processAPI.Routes())
 	r.Mount("/api/v0/desktop", a.desktopAPI.Routes())
 	r.Mount("/api/v0/mcp", a.mcpAPI.Routes())
+	r.Mount("/api/v0/context-config", a.contextConfigAPI.Routes())
 
 	if a.devcontainers {
 		r.Mount("/api/v0/containers", a.containerAPI.Routes())

agent/x/agentmcp/manager.go

@@ -6,7 +6,6 @@ import (
 	"fmt"
 	"io/fs"
 	"os"
-	"path/filepath"
 	"slices"
 	"strings"
 	"sync"
@@ -70,16 +69,40 @@ func NewManager(logger slog.Logger) *Manager {
 	}
 }
 
-// Connect discovers .mcp.json in dir and connects to all
-// configured servers. Failed servers are logged and skipped.
-func (m *Manager) Connect(ctx context.Context, dir string) error {
-	path := filepath.Join(dir, ".mcp.json")
-	configs, err := ParseConfig(path)
-	if err != nil {
-		if errors.Is(err, fs.ErrNotExist) {
-			return nil
+// Connect reads MCP config files at the given absolute paths and
+// connects to all configured servers. Failed servers are logged
+// and skipped. Missing config files are silently skipped.
+func (m *Manager) Connect(ctx context.Context, mcpConfigFiles []string) error {
+	var allConfigs []ServerConfig
+	for _, configPath := range mcpConfigFiles {
+		configs, err := ParseConfig(configPath)
+		if err != nil {
+			if errors.Is(err, fs.ErrNotExist) {
+				continue
+			}
+			m.logger.Warn(ctx, "failed to parse MCP config",
+				slog.F("path", configPath),
+				slog.Error(err),
+			)
+			continue
 		}
-		return xerrors.Errorf("parse mcp config: %w", err)
+		allConfigs = append(allConfigs, configs...)
+	}
+
+	// Deduplicate by server name; first occurrence wins.
+	seen := make(map[string]struct{})
+	deduped := make([]ServerConfig, 0, len(allConfigs))
+	for _, cfg := range allConfigs {
+		if _, ok := seen[cfg.Name]; ok {
+			continue
+		}
+		seen[cfg.Name] = struct{}{}
+		deduped = append(deduped, cfg)
+	}
+	allConfigs = deduped
+
+	if len(allConfigs) == 0 {
+		return nil
 	}
 
 	// Connect to servers in parallel without holding the
@@ -95,7 +118,7 @@ func (m *Manager) Connect(ctx context.Context, dir string) error {
 		connected []connectedServer
 	)
 	var eg errgroup.Group
-	for _, cfg := range configs {
+	for _, cfg := range allConfigs {
 		eg.Go(func() error {
 			c, err := m.connectServer(ctx, cfg)
 			if err != nil {