pi-mcp-adapter 2.12.1 → 2.14.0

package/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.14.0] - 2026-07-25
+
+### Added
+- Added the global `settings.showStatusIcon` opt-out for plain `MCP: ...` status and connection text while keeping the plug icon enabled by default. Thanks @vaultboy001 for issue #216.
+
+### Fixed
+- Deferred implicit OAuth credential-store access until an HTTP server actually challenges for authentication, so unauthenticated remote Streamable HTTP servers work in headless environments. Thanks @vdom-1 for issue #218.
+- Accepted draft-07 tool output schemas alongside JSON Schema 2020-12 while preserving structured-content validation. Thanks Daniel Marbach (@danielmarbach) for issue #217.
+
+## [2.13.0] - 2026-07-25
+
+### Added
+- Added a versioned, sanitized MCP runtime status snapshot on Pi's shared event bus for extensions, without connecting lazy servers or exposing SDK internals. Thanks Ludev (@ludevdot) for issue #110.
+- Added opt-in host-specific MCP config discovery with source/provenance and conflict reporting. Standard shared and Pi-owned config precedence remains unchanged, and external host files are never written or silently executed. Thanks @lsmir2 for issue #169.
+- Added opt-in metadata-only JSONL MCP protocol tracing with bounded per-session files and redaction. Thanks @66-firebat for issue #45.
+- Added per-server `includeTools` allowlists with exact-name and glob matching for proxy, direct-tool, and `/mcp` panel surfaces. Thanks Finn (@finnvyrn) for issue #136.
+- Made `mcp({ connect: "server" })` refresh an already connected server instead of reusing stale tool metadata. Thanks Sebastiano Poggi (@rock3r) for issue #28 and @theflysurfer for the refresh analysis.
+- Added a plug icon prefix to MCP footer status text. Thanks Felipe Cadal (@cadal-cw) for issue #145.
+- Discovered user-global MCP configs from `~/.agents/mcp.json` and `~/.agents/mcp/mcp.json`. Thanks David Jadczyk (@davidjadczyk) for issue #117.
+- Accepted JSONC-style comments and trailing commas in MCP JSON config files. Thanks @GoCoder7 for issue #124.
+
+### Changed
+- Measured and spilled oversized raw MCP result details as compact JSON instead of pretty-printed JSON, reducing hot-path allocation and event-loop work. Thanks José Maia (@glitch-ux) for issue #214 and PR #215.
+- Renamed generated MCP resource tools from `get_<resource>` to `read_<resource>` to match the MCP `resources/read` operation. Thanks @vdom-1 for issue #185.
+
+### Security
+- Moved persistent OAuth credentials from plaintext `tokens.json` files into the operating system credential store, with one-way legacy import and fail-closed behavior when secure storage is unavailable. Thanks Sam Atkins (@atkinsam) for issue #180.
+
+### Fixed
+- Skipped `resources/list` for MCP servers that do not advertise the `resources` capability, matching the existing prompt discovery gate and silencing the SDK v2 debug line that tools-only servers printed on every connect. Thanks Aleksandr Davydenko (@kotuke) for PR #213.
+- Made the MCP footer show enabled configured servers as the primary count, with active connections as secondary state, so lazy servers no longer look broken before first use or after idle shutdown. Thanks blumlaut (@Blumlaut) for issue #93.
+- Show the actual proxied MCP server/tool name in `mcp` tool results. Thanks Finn (@finnvyrn) and @dillontkh for issue #68.
+- Removed the remaining TypeScript import cycles reported by `madge`. Thanks @av1155 for issue #101.
+
 ## [2.12.1] - 2026-07-24
 
 ### Fixed

package/README.md

@@ -51,19 +51,23 @@ Preferred project config: `.mcp.json`
 }
 ```
 
-Preferred user-global shared config: `~/.config/mcp/mcp.json`
+Preferred user-global shared config: `~/.config/mcp/mcp.json`. Pi also reads the tool-agnostic global paths `~/.agents/mcp.json` and `~/.agents/mcp/mcp.json`.
 
 Pi also reads Pi-owned override files for settings and host-specific compatibility:
 
 - `<Pi agent dir>/mcp.json` — Pi global override (`~/.pi/agent/mcp.json` by default)
 - `.pi/mcp.json` — Pi project override
 
+Host-specific configs are detected and shown by `/mcp setup` and `pi-mcp-adapter init`, but they are not loaded automatically. To explicitly opt in to host-config fallback discovery, set `settings.hostConfigDiscovery` to `"on"` or run `pi-mcp-adapter init --discover-host-configs`. The default is `"off"`; `"prompt"` is available for integrations that want detection without activation. Host configs are lower precedence than every shared and Pi-owned source, and `/mcp setup` continues to offer explicit import adoption. Discovery reports source paths, provenance, and same-name conflicts; it never writes to external host files or silently launches commands from them.
+
 Precedence is:
 
 1. `~/.config/mcp/mcp.json`
-2. `<Pi agent dir>/mcp.json`
-3. `.mcp.json`
-4. `.pi/mcp.json`
+2. `~/.agents/mcp.json`
+3. `~/.agents/mcp/mcp.json`
+4. `<Pi agent dir>/mcp.json`
+5. `.mcp.json`
+6. `.pi/mcp.json`
 
 `/mcp disable <server>` and `/mcp enable <server>` persist only the `disabled` field in the project-local `.pi/mcp.json`, which is the highest-precedence Pi layer. Enabling removes the project flag when lower layers are enabled, or writes `false` when needed to override a disabled lower source. This applies even when the effective server came from a shared global/project file, an imported host config, or `configPath`; the source file is never rewritten and credentials are never copied. Run `/reload` after changing the flag so registered tool surfaces are refreshed. The manual equivalent is to add `{ "disabled": true }` to a server in any normal MCP config. Supplied in-memory `createMcpAdapter({ config })` configurations are isolated and do not read or write this project override; the commands are unavailable in that mode.
 
@@ -97,6 +101,8 @@ Use the shared MCP files when you want one setup to work across hosts, and Pi-ow
 | File | Purpose |
 |------|---------|
 | `~/.config/mcp/mcp.json` | User-global shared MCP config |
+| `~/.agents/mcp.json` | User-global tool-agnostic MCP config |
+| `~/.agents/mcp/mcp.json` | User-global tool-agnostic MCP config |
 | `.mcp.json` | Project-local shared MCP config |
 | `<Pi agent dir>/mcp.json` | Pi global override and compatibility imports (`~/.pi/agent/mcp.json` by default) |
 | `.pi/mcp.json` | Pi project override |
@@ -128,7 +134,23 @@ The package ships TypeScript source for Pi's source-loader and SDK integrations.
 
 A supplied `config` is a complete, isolated snapshot. It is not merged with files, imports, global config, project config, or `--mcp-config`, and it is never mutated. Each adapter factory and session receives its own clone, so separate integrations can use different servers and settings safely. In this mode, server status, reconnect, explicit `/mcp-auth <server>`, proxy calls, and direct tools continue to work; setup and no-argument auth/status panels report the limitation instead of discovering or writing ambient config.
 
-With `configPath` and no `config`, the adapter keeps normal file merge behavior, and that path takes precedence over argv and `--mcp-config`. The default export keeps the normal file-based behavior. OAuth credentials remain persistent and are shared by the configured server name by default; callers requiring strict same-name credential-file isolation should set distinct `settings.oauthDir` values. URL binding prevents credentials from being accepted for a different server URL. CSRF state and PKCE verifiers are flow-local, so concurrent authorization flows do not share transient secrets.
+With `configPath` and no `config`, the adapter keeps normal file merge behavior, and that path takes precedence over argv and `--mcp-config`. The default export keeps the normal file-based behavior. OAuth credentials are stored in the operating system credential store and keyed by the configured server name; URL binding prevents credentials from being accepted for a different server URL. `settings.oauthDir` and `MCP_OAUTH_DIR` are used only as legacy plaintext import locations for older `tokens.json` files, not as credential namespaces. CSRF state and PKCE verifiers are flow-local, so concurrent authorization flows do not share transient secrets.
+
+### Runtime status snapshots
+
+Extensions can subscribe to the adapter's versioned shared event-bus channel instead of parsing `/mcp` or `mcp({})` output:
+
+```ts
+import { MCP_STATUS_EVENT, type McpStatusSnapshot } from "pi-mcp-adapter";
+
+pi.events.on(MCP_STATUS_EVENT, (snapshot) => {
+  const status = snapshot as McpStatusSnapshot;
+  // status.servers contains connected, cached, failed, needs-auth,
+  // not-connected, or disabled entries.
+});
+```
+
+The snapshot is read-only machine-readable data with copied per-server entries. It includes `totalTools`, `totalResources`, `connectedCount`, and `disabledCount`; each server includes `name`, `status`, `toolCount`, and `disabled`, with `resourceCount` when known and `failedAgoSeconds` only for an active failure. Reading status never connects a lazy server, starts authentication, or exposes SDK clients, transports, credentials, or server definitions. An initial snapshot is emitted after initialization, updates are emitted for status and metadata changes, and an empty snapshot is emitted when the session shuts down.
 
 In the configuration examples below, `30000` is illustrative only. If `requestTimeoutMs` is omitted or set to `<= 0`, the MCP SDK default timeout is used.
 
@@ -170,15 +192,17 @@ In the configuration examples below, `30000` is illustrative only. If `requestTi
 | `requestTimeoutMs` | Request timeout in milliseconds for live MCP calls (overrides global; if omitted or `<= 0`, the MCP SDK default timeout is used) |
 | `exposeResources` | Expose MCP resources as tools (default: true) |
 | `directTools` | `true`, `string[]`, or `false` — register tools individually instead of through proxy |
-| `excludeTools` | `string[]` of tool names to hide (matches original names like `get_screenshot` and prefixed names like `figma_get_screenshot`) |
+| `includeTools` | `string[]` of tool names or glob patterns to expose (matches original names like `get_screenshot`, generated resource names like `read_figjam`, and prefixed names like `figma_get_screenshot`) |
+| `excludeTools` | `string[]` of tool names or glob patterns to hide (applied after `includeTools`) |
 | `debug` | Show server stderr (default: false) |
+| `trace` | Enable metadata-only JSONL protocol tracing for this server; payloads, prompts, tool arguments/results, authorization data, and URLs are never persisted |
 | `disabled` | Keep the server visible in config and status, but prevent connections, authentication, tools, and resource calls (only literal `true` disables it) |
 
 For pre-registered browser OAuth clients, set `oauth.redirectUri` to the exact callback registered with the provider, for example `"http://localhost:3118/callback"`. Dynamic clients normally omit it and use a lazy OS-assigned localhost callback port.
 
 ### Remote/headless OAuth
 
-If Pi is running on a remote server and cannot open a local browser, start OAuth through the proxy tool:
+If Pi is running on a remote server and cannot open a local browser, start OAuth through the proxy tool. Persistent OAuth still requires an available OS credential store; on headless Linux that usually means an unlocked Secret Service/libsecret keyring. The adapter fails closed instead of falling back to plaintext credentials when the secure store is unavailable:
 
 ```js
 mcp({ action: "auth-start", server: "linear-server" })
@@ -213,7 +237,15 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
     "toolPrefix": "server",
     "idleTimeout": 10,
     "requestTimeoutMs": 30000,
-    "oauthDir": ".pi/mcp-oauth"
+    "showStatusIcon": true,
+    "hostConfigDiscovery": "off",
+    "oauthDir": ".pi/mcp-oauth",
+    "trace": {
+      "enabled": true,
+      "file": ".pi/mcp-traces/mcp.jsonl",
+      "maxBytes": 262144,
+      "maxEvents": 10000
+    }
   },
   "mcpServers": { }
 }
@@ -224,7 +256,9 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
 | `toolPrefix` | `"server"` (default), `"short"` (strips `-mcp` suffix), `"none"`, or `"mcp"` (prefixes with `mcp__`, using server-mode normalization) |
 | `idleTimeout` | Global idle timeout in minutes (default: 10, 0 to disable) |
 | `requestTimeoutMs` | Global request timeout in milliseconds for live MCP calls (if omitted or `<= 0`, the MCP SDK default timeout is used) |
-| `oauthDir` | OAuth credential directory for this MCP config. Relative paths resolve from the active project cwd. `MCP_OAUTH_DIR` still wins when set. |
+| `showStatusIcon` | Show the plug icon in MCP status and connection text (default: `true`). Set to `false` for plain `MCP: ...` text. |
+| `hostConfigDiscovery` | Host-specific config policy: `"off"` (default), `"prompt"` (detect/report only), or `"on"` (explicitly load detected host configs as the lowest-precedence fallback) |
+| `oauthDir` | Legacy OAuth `tokens.json` import directory for this MCP config. Relative paths resolve from the active project cwd. `MCP_OAUTH_DIR` still wins when set. Persistent OAuth credentials are stored in the OS credential store, not this directory. |
 | `directTools` | Global default for all servers (default: false). Per-server overrides this. |
 | `disableProxyTool` | Hide the `mcp` proxy tool once configured direct tools are fully available from cache. |
 | `autoAuth` | Auto-run OAuth on `connect`/tool calls when a server needs auth, then retry once (default: false). |
@@ -232,8 +266,9 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
 | `samplingAutoApprove` | Skip sampling confirmation prompts. Required for sampling in non-UI sessions (default: false). |
 | `elicitation` | Allow MCP servers to request user input through Pi dialogs (default: true when Pi UI is available). |
 | `outputGuard` | Guard oversized MCP output: `true` (default), `false`, or `{ maxBytes, maxLines, detailsMaxBytes }`. See [Output Guard](#output-guard). |
+| `trace` | Opt-in metadata-only protocol tracing. Set `{ enabled: true }` globally or `trace: true` on a server. The per-session JSONL file defaults to `.pi/mcp-traces/`; `file`, `maxBytes` (default 262144), and `maxEvents` (default 10000) can be set. Raw MCP payloads, prompts, tool arguments/results, auth data, and URLs are never persisted. |
 
-Per-server `idleTimeout` and `requestTimeoutMs` override the global settings.
+Per-server `idleTimeout` and `requestTimeoutMs` override the global settings. `debug` remains stderr display and is unrelated to protocol tracing.
 
 ### Output Guard
 
@@ -323,7 +358,21 @@ To set a global default for all servers:
 
 Per-server `directTools` overrides the global setting. The example above registers direct tools for every server except `huge-server`.
 
-To exclude specific tools while still using `directTools: true`, add `excludeTools` on the server:
+To expose only a subset of a noisy server, add `includeTools` on the server. Values can be exact original names, generated resource names such as `read_<resource>`, prefixed names, or simple glob patterns:
+
+```json
+{
+  "mcpServers": {
+    "dokploy": {
+      "url": "http://localhost:3845/mcp",
+      "directTools": true,
+      "includeTools": ["get_*", "dokploy_list_apps"]
+    }
+  }
+}
+```
+
+To hide specific tools while still using `directTools: true`, add `excludeTools` on the server. `excludeTools` is applied after `includeTools`:
 
 ```json
 {
@@ -331,13 +380,13 @@ To exclude specific tools while still using `directTools: true`, add `excludeToo
     "figma": {
       "url": "http://localhost:3845/mcp",
       "directTools": true,
-      "excludeTools": ["get_figjam", "figma_get_code_connect_map"]
+      "excludeTools": ["read_figjam", "figma_get_code_connect_map"]
     }
   }
 }
 ```
 
-`excludeTools` filters direct tools, proxy search/list/describe, and the `/mcp` panel view.
+`includeTools` and `excludeTools` filter direct tools, proxy search/list/describe, and the `/mcp` panel view.
 
 Each direct tool costs ~150-300 tokens in the system prompt (name + description + schema). Good for targeted sets of 5-20 tools. For servers with 75+ tools, stick with the proxy or pick specific tools with a `string[]`.
 
@@ -445,6 +494,8 @@ Prefer `.mcp.json` for project-local shared MCP config. Use `.pi/mcp.json` only
 | Auth start | `mcp({ action: "auth-start", server: "name" })` |
 | Auth complete | `mcp({ action: "auth-complete", server: "name", args: { redirectUrl: "..." } })` |
 
+`mcp({ connect: "server-name" })` refreshes an already connected server, so new tools, resources, prompts, and instructions can load without restarting Pi.
+
 MCP proxy and direct-tool results render compactly by default: long text shows the first three terminal-wrapped lines plus a `Ctrl+O to expand` hint, while the full result remains available when expanded and is still returned unchanged to the model.
 
 Search includes both MCP tools and Pi tools (from extensions). Pi tools appear first with `[pi tool]` prefix. Space-separated words are OR'd.
@@ -473,6 +524,10 @@ If `settings.autoAuth` is `true`, `mcp({ connect: ... })`, `mcp({ tool: ... })`,
 
 In interactive sessions, you can also authenticate from `/mcp` with `ctrl+a` or Enter on a server that needs auth. In remote/headless sessions, use the proxy tool's `auth-start` and `auth-complete` actions to copy the authorization URL locally and paste the redirect URL back into Pi. `/mcp-auth` without a server only opens a picker in the interactive UI.
 
+### MCP output schemas
+
+Advertised tool `outputSchema` values support JSON Schema draft-07 and 2020-12. Unstamped schemas use the SDK's 2020-12 default. Returned `structuredContent` is validated against the advertised schema for both proxy and direct-tool calls.
+
 ## How It Works
 
 - One `mcp` tool in context (~200 tokens) instead of hundreds

package/cli.js

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { pathToFileURL } from "node:url";
+import stripJsonComments from "strip-json-comments";
 
 const HOME = os.homedir();
 
@@ -18,6 +19,8 @@ const AGENT_DIR = process.env.PI_CODING_AGENT_DIR?.trim()
   : path.join(HOME, ".pi", "agent");
 const PI_CONFIG_PATH = path.join(AGENT_DIR, "mcp.json");
 const GENERIC_GLOBAL_CONFIG_PATH = path.join(HOME, ".config", "mcp", "mcp.json");
+const AGENTS_GLOBAL_CONFIG_PATH = path.join(HOME, ".agents", "mcp.json");
+const AGENTS_NESTED_GLOBAL_CONFIG_PATH = path.join(HOME, ".agents", "mcp", "mcp.json");
 const PROJECT_CONFIG_PATH = path.resolve(process.cwd(), ".mcp.json");
 const PROJECT_PI_CONFIG_PATH = path.resolve(process.cwd(), ".pi", "mcp.json");
 
@@ -33,6 +36,10 @@ const IMPORT_PATHS = {
     path.join(HOME, ".codex", "config.toml"),
     path.join(HOME, ".codex", "config.json"),
   ],
+  opencode: [
+    path.join(HOME, ".config", "opencode", "opencode.json"),
+    path.resolve(process.cwd(), "opencode.json"),
+  ],
   windsurf: [path.join(HOME, ".windsurf", "mcp.json")],
   vscode: [path.resolve(process.cwd(), ".vscode", "mcp.json")],
 };
@@ -44,10 +51,11 @@ function printHelp(log = console.log) {
   log("Then optionally run:");
   log("  pi-mcp-adapter init       Detect host configs and scaffold Pi imports");
   log("  pi-mcp-adapter init --dry-run");
+  log("  pi-mcp-adapter init --discover-host-configs  Opt in to host config fallback discovery");
 }
 
 function readJsonFile(filePath) {
-  return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  return JSON.parse(stripJsonComments(fs.readFileSync(filePath, "utf-8"), { trailingCommas: true }));
 }
 
 function loadPiConfig() {
@@ -90,6 +98,8 @@ function printDiscovery(log, imports) {
 
   const paths = [
     ["User-global standard MCP", GENERIC_GLOBAL_CONFIG_PATH],
+    ["User-global .agents MCP", AGENTS_GLOBAL_CONFIG_PATH],
+    ["User-global .agents nested MCP", AGENTS_NESTED_GLOBAL_CONFIG_PATH],
     ["Pi global override", PI_CONFIG_PATH],
     ["Project standard MCP", PROJECT_CONFIG_PATH],
     ["Project Pi override", PROJECT_PI_CONFIG_PATH],
@@ -118,6 +128,7 @@ function writePiConfig(config) {
 
 async function runInit(argv, log = console.log) {
   const dryRun = argv.includes("--dry-run");
+  const discoverHostConfigs = argv.includes("--discover-host-configs");
   const foundImports = findAvailableImports();
   const existingConfig = loadPiConfig();
   const existingImports = new Set(existingConfig.imports ?? []);
@@ -127,7 +138,8 @@ async function runInit(argv, log = console.log) {
 
   printDiscovery(log, foundImports);
 
-  if (importsToAdd.length === 0) {
+  const discoverySettingChanged = discoverHostConfigs && existingConfig.settings?.hostConfigDiscovery !== "on";
+  if (importsToAdd.length === 0 && !discoverySettingChanged) {
     log("\nNo Pi config changes needed.");
     log("Standard MCP configs are discovered automatically, and host-specific imports are already configured or unavailable.");
     return 0;
@@ -135,11 +147,17 @@ async function runInit(argv, log = console.log) {
 
   const nextConfig = {
     ...existingConfig,
-    imports: [...existingImports, ...importsToAdd],
+    ...(discoverySettingChanged ? { settings: { ...existingConfig.settings, hostConfigDiscovery: "on" } } : {}),
+    ...(importsToAdd.length > 0 ? { imports: [...existingImports, ...importsToAdd] } : {}),
     mcpServers: existingConfig.mcpServers ?? {},
   };
 
-  log(`\nDetected host configs to import into Pi: ${importsToAdd.join(", ")}`);
+  if (importsToAdd.length > 0) {
+    log(`\nDetected host configs to import into Pi: ${importsToAdd.join(", ")}`);
+  }
+  if (discoverySettingChanged) {
+    log("Opting in to host-specific fallback discovery (standard and Pi-owned configs still take precedence).");
+  }
 
   if (dryRun) {
     log(`Dry run: would update ${PI_CONFIG_PATH}`);
@@ -149,6 +167,9 @@ async function runInit(argv, log = console.log) {
   writePiConfig(nextConfig);
   log(`Updated ${PI_CONFIG_PATH}`);
   log("Pi will now keep reading standard MCP configs automatically, while these imports cover host-specific config formats.");
+  if (discoverySettingChanged) {
+    log("Host config discovery is explicit and does not write to or execute commands from external host files.");
+  }
   return 0;
 }
 

package/config.ts

@@ -3,11 +3,16 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { parse as parseToml } from "smol-toml";
+import stripJsonComments from "strip-json-comments";
 import { getAgentPath } from "./agent-dir.ts";
-import { isServerDisabled, type McpConfig, type ServerEntry, type McpSettings, type ImportKind, type ServerProvenance } from "./types.ts";
+import { isServerDisabled, type HostConfigDiscovery, type McpConfig, type ServerEntry, type McpSettings, type ImportKind, type ServerProvenance } from "./types.ts";
 import { toStringRecord } from "./utils.ts";
 
 const GENERIC_GLOBAL_CONFIG_PATH = join(homedir(), ".config", "mcp", "mcp.json");
+const AGENTS_GLOBAL_CONFIG_PATHS = [
+  join(homedir(), ".agents", "mcp.json"),
+  join(homedir(), ".agents", "mcp", "mcp.json"),
+] as const;
 const PROJECT_CONFIG_NAME = ".mcp.json";
 const PROJECT_PI_CONFIG_NAME = ".pi/mcp.json";
 const REPOPROMPT_BINARY_CANDIDATES = [
@@ -36,7 +41,7 @@ const IMPORT_PATHS: Record<ImportKind, string[]> = {
 };
 
 interface ConfigSourceSpec {
-  id: "shared-global" | "pi-global" | "shared-project" | "pi-project";
+  id: "shared-global" | "agents-global" | "agents-nested-global" | "pi-global" | "shared-project" | "pi-project";
   label: string;
   readPath: string;
   writePath: string;
@@ -68,6 +73,16 @@ export interface ImportConfigSummary extends DiscoveredImportConfig {
   serverCount: number;
 }
 
+export interface HostConfigSummary extends ImportConfigSummary {
+  active: boolean;
+}
+
+export interface McpConfigConflict {
+  serverName: string;
+  sources: Array<{ kind: "shared" | "pi" | "host"; path: string }>;
+  winner: { kind: "shared" | "pi" | "host"; path: string };
+}
+
 export interface RepoPromptDiscovery {
   configured: boolean;
   configuredPath?: string;
@@ -80,6 +95,9 @@ export interface RepoPromptDiscovery {
 export interface McpDiscoverySummary {
   sources: ConfigDiscoverySource[];
   imports: ImportConfigSummary[];
+  hostConfigs: HostConfigSummary[];
+  hostConfigDiscovery: HostConfigDiscovery;
+  conflicts: McpConfigConflict[];
   hasAnyConfig: boolean;
   hasAnyDetectedPaths: boolean;
   hasSharedServers: boolean;
@@ -136,7 +154,8 @@ export function findAvailableImportConfigs(cwd = process.cwd()): DiscoveredImpor
 }
 
 export function getMcpDiscoverySummary(overridePath?: string, cwd = process.cwd()): McpDiscoverySummary {
-  const sources = getConfigSources(overridePath, cwd).map((source) => {
+  const sourceSpecs = getConfigSources(overridePath, cwd);
+  const sources = sourceSpecs.map((source) => {
     const loaded = readValidatedConfig(source.readPath, `MCP config from ${source.readPath}`);
     return {
       id: source.id,
@@ -160,7 +179,8 @@ export function getMcpDiscoverySummary(overridePath?: string, cwd = process.cwd(
       } satisfies ImportConfigSummary;
     })
     .filter((value): value is ImportConfigSummary => value !== null);
-
+  const hostConfigDiscovery = getConfiguredHostConfigDiscovery(overridePath, cwd);
+  const hostConfigs = imports.map((entry) => ({ ...entry, active: hostConfigDiscovery === "on" }));
   const totalServerCount = sources.reduce((sum, source) => sum + source.serverCount, 0);
   const hasSharedServers = sources.some((source) => source.kind === "shared" && source.serverCount > 0);
   const hasPiOwnedServers = sources.some((source) => source.kind === "pi" && source.serverCount > 0);
@@ -170,6 +190,9 @@ export function getMcpDiscoverySummary(overridePath?: string, cwd = process.cwd(
   const summaryWithoutRepoPrompt = {
     sources,
     imports,
+    hostConfigs,
+    hostConfigDiscovery,
+    conflicts: getConfigConflicts(sourceSpecs, imports, cwd),
     hasAnyConfig,
     hasAnyDetectedPaths,
     hasSharedServers,
@@ -180,6 +203,8 @@ export function getMcpDiscoverySummary(overridePath?: string, cwd = process.cwd(
   const fingerprint = JSON.stringify({
     sources: sources.map((source) => [source.id, source.exists, source.serverCount]),
     imports: imports.map((entry) => [entry.kind, entry.path, entry.serverCount]),
+    hostConfigDiscovery,
+    conflicts: summaryWithoutRepoPrompt.conflicts,
   });
 
   return {
@@ -194,9 +219,16 @@ export function cloneMcpConfig(config: McpConfig): McpConfig {
 }
 
 export function loadMcpConfig(overridePath?: string, cwd = process.cwd()): McpConfig {
-  let config: McpConfig = { mcpServers: {} };
-
-  for (const source of getConfigSources(overridePath, cwd)) {
+  const sourceSpecs = getConfigSources(overridePath, cwd);
+  const hostConfigDiscovery = getConfiguredHostConfigDiscovery(overridePath, cwd);
+  // Host files are a lower-precedence fallback. This ordering means an opt-in
+  // discovery cannot override a shared or Pi-owned definition, and all normal
+  // URL-bound credential stripping remains in mergeServerMaps.
+  let config: McpConfig = hostConfigDiscovery === "on"
+    ? loadDiscoveredHostConfigs(cwd)
+    : { mcpServers: {} };
+
+  for (const source of sourceSpecs) {
     const loaded = readValidatedConfig(source.readPath, `MCP config from ${source.readPath}`);
     if (!loaded) continue;
     config = mergeConfigs(config, expandImports(loaded, cwd));
@@ -205,6 +237,75 @@ export function loadMcpConfig(overridePath?: string, cwd = process.cwd()): McpCo
   return config;
 }
 
+function getConfiguredHostConfigDiscovery(overridePath?: string, cwd = process.cwd()): HostConfigDiscovery {
+  let configured: HostConfigDiscovery = "off";
+  for (const source of getConfigSources(overridePath, cwd)) {
+    const loaded = readValidatedConfig(source.readPath, `MCP config from ${source.readPath}`);
+    const value = loaded?.settings?.hostConfigDiscovery;
+    if (value === "off" || value === "prompt" || value === "on") configured = value;
+  }
+  return configured;
+}
+
+function loadDiscoveredHostConfigs(cwd: string): McpConfig {
+  let config: McpConfig = { mcpServers: {} };
+  for (const importKind of Object.keys(IMPORT_PATHS) as ImportKind[]) {
+    const imported = loadImportedConfig(importKind, cwd, `Failed to discover imported MCP config from ${importKind}:`);
+    if (!imported) continue;
+    config = mergeConfigs(config, {
+      mcpServers: extractServers(imported.value, importKind),
+    });
+  }
+  return config;
+}
+
+function getConfigConflicts(
+  sourceSpecs: ConfigSourceSpec[],
+  imports: ImportConfigSummary[],
+  cwd: string,
+): McpConfigConflict[] {
+  const seen = new Map<string, Array<{ kind: "shared" | "pi" | "host"; path: string }>>();
+  const record = (name: string, source: { kind: "shared" | "pi" | "host"; path: string }): void => {
+    const entries = seen.get(name) ?? [];
+    if (!entries.some((entry) => entry.kind === source.kind && entry.path === source.path)) entries.push(source);
+    seen.set(name, entries);
+  };
+
+  // Host candidates are listed first because, when enabled, they are the
+  // lowest-precedence fallback. The fixed IMPORT_PATHS order is deterministic.
+  for (const entry of imports) {
+    const imported = loadImportedConfig(entry.kind, cwd, `Failed to inspect imported MCP config from ${entry.kind}:`);
+    if (!imported) continue;
+    for (const name of Object.keys(extractServers(imported.value, entry.kind))) {
+      record(name, { kind: "host", path: imported.path });
+    }
+  }
+  for (const source of sourceSpecs) {
+    const loaded = readValidatedConfig(source.readPath, `MCP config from ${source.readPath}`);
+    if (!loaded) continue;
+    if (loaded.imports?.length) {
+      for (const importKind of loaded.imports) {
+        const imported = loadImportedConfig(importKind, cwd, `Failed to inspect imported MCP config from ${importKind}:`);
+        if (!imported) continue;
+        for (const name of Object.keys(extractServers(imported.value, importKind))) {
+          record(name, { kind: "host", path: imported.path });
+        }
+      }
+    }
+    for (const name of Object.keys(loaded.mcpServers)) {
+      record(name, {
+        kind: source.shared ? "shared" : "pi",
+        path: source.readPath,
+      });
+    }
+  }
+
+  return [...seen.entries()]
+    .filter(([, sources]) => sources.length > 1)
+    .map(([serverName, sources]) => ({ serverName, sources, winner: sources[sources.length - 1]! }))
+    .sort((left, right) => left.serverName.localeCompare(right.serverName));
+}
+
 function getConfigSources(overridePath?: string, cwd = process.cwd()): ConfigSourceSpec[] {
   const userPath = getPiGlobalConfigPath(overridePath);
   const projectPath = getProjectConfigPath(cwd);
@@ -224,6 +325,20 @@ function getConfigSources(overridePath?: string, cwd = process.cwd()): ConfigSou
     });
   }
 
+  for (const [index, agentsPath] of AGENTS_GLOBAL_CONFIG_PATHS.entries()) {
+    if (agentsPath === userPath || agentsPath === GENERIC_GLOBAL_CONFIG_PATH) continue;
+    sources.push({
+      id: index === 0 ? "agents-global" : "agents-nested-global",
+      label: index === 0 ? "user-global .agents MCP" : "user-global .agents nested MCP",
+      readPath: agentsPath,
+      writePath: userPath,
+      kind: "import",
+      importKind: index === 0 ? ".agents MCP config" : ".agents/mcp MCP config",
+      shared: true,
+      scope: "global",
+    });
+  }
+
   sources.push({
     id: "pi-global",
     label: "Pi global override",
@@ -365,9 +480,13 @@ function resolveImportCandidates(importKind: ImportKind, cwd: string): string[]
   });
 }
 
+function parseJsonConfig(raw: string): unknown {
+  return JSON.parse(stripJsonComments(raw, { trailingCommas: true }));
+}
+
 function readImportedConfig(path: string): unknown {
   const raw = readFileSync(path, "utf-8");
-  return path.endsWith(".toml") ? parseToml(raw) : JSON.parse(raw);
+  return path.endsWith(".toml") ? parseToml(raw) : parseJsonConfig(raw);
 }
 
 function loadImportedConfig(
@@ -417,7 +536,7 @@ function readValidatedConfig(path: string, label: string): McpConfig | null {
   if (!existsSync(path)) return null;
 
   try {
-    return validateConfig(JSON.parse(readFileSync(path, "utf-8")));
+    return validateConfig(parseJsonConfig(readFileSync(path, "utf-8")));
   } catch (error) {
     console.warn(`Failed to load ${label}:`, error);
     return null;
@@ -667,7 +786,7 @@ function readRawConfigObject(filePath: string): Record<string, unknown> {
   if (!existsSync(filePath)) return {};
 
   try {
-    const raw = JSON.parse(readFileSync(filePath, "utf-8"));
+    const raw = parseJsonConfig(readFileSync(filePath, "utf-8"));
     return raw && typeof raw === "object" && !Array.isArray(raw) ? raw as Record<string, unknown> : {};
   } catch {
     return {};
@@ -714,7 +833,7 @@ export function writeProjectServerDisabledOverride(
   let raw: Record<string, unknown> = {};
   if (existsSync(filePath)) {
     try {
-      const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+      const parsed = parseJsonConfig(readFileSync(filePath, "utf-8"));
       if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
         throw new Error("root value must be an object");
       }
@@ -903,6 +1022,18 @@ export function getServerProvenance(overridePath?: string, cwd = process.cwd()):
   const provenance = new Map<string, ServerProvenance>();
   const userPath = getPiGlobalConfigPath(overridePath);
 
+  if (getConfiguredHostConfigDiscovery(overridePath, cwd) === "on") {
+    for (const importKind of Object.keys(IMPORT_PATHS) as ImportKind[]) {
+      const imported = loadImportedConfig(importKind, cwd, `Failed to inspect imported MCP config from ${importKind}:`);
+      if (!imported) continue;
+      for (const name of Object.keys(extractServers(imported.value, importKind))) {
+        // Keep writes inside Pi-owned storage even though the source is external.
+        // Later import kinds win in the same deterministic order as loadDiscoveredHostConfigs.
+        provenance.set(name, { path: userPath, kind: "import", importKind });
+      }
+    }
+  }
+
   for (const source of getConfigSources(overridePath, cwd)) {
     const loaded = readValidatedConfig(source.readPath, `MCP config from ${source.readPath}`);
     if (!loaded) continue;