fix(plugin): inline mcpServers in plugin.json, drop repo-root .mcp.json

The repo-root .mcp.json served double duty: plugin MCP config
(plugin.json referenced it as "./.mcp.json") AND — unintentionally —
project-scoped MCP config picked up by Claude Code whenever this repo
was the working directory. Project scope never substitutes
${CLAUDE_PLUGIN_ROOT}, so the spawn ran a literal
'<repo>/${CLAUDE_PLUGIN_ROOT}/scripts/launcher.py' → ENOENT → "MCP
error -32000: Connection closed", shadowing the healthy plugin-scoped
server (plugin:cortex:cortex).

Fix: move the server config inline into .claude-plugin/plugin.json
mcpServers (documented form) and delete the repo-root .mcp.json —
inline plugin config is invisible to project-scope discovery. The
contract test now reads the inline object and pins the absence of a
repo-root .mcp.json as a regression guard. Verified post-restart:
only plugin:cortex:cortex registers; no -32000.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: cdeust

.claude-plugin/plugin.json

@@ -25,7 +25,20 @@
       "default": "postgresql://127.0.0.1:5432/cortex"
     }
   },
-  "mcpServers": "./.mcp.json",
+  "mcpServers": {
+    "cortex": {
+      "command": "python3",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/scripts/launcher.py",
+        "mcp_server"
+      ],
+      "env": {
+        "DATABASE_URL": "${user_config.database_url}",
+        "CORTEX_RUNTIME": "",
+        "CORTEX_MEMORY_AP_ENABLED": "1"
+      }
+    }
+  },
   "postInstall": {
     "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/install-plugin.sh",
     "message": "Installing Cortex (PostgreSQL + pgvector + Python deps + embedding model) and removing any stale older Cortex installs..."

.mcp.json

@@ -6,6 +6,25 @@ adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Fixed
+
+- **`/mcp` showed a failing `cortex` server (-32000) whenever the plugin
+  source repo itself was the working directory.** The repo-root
+  `.mcp.json` served double duty: plugin MCP config (plugin.json
+  referenced it as `"./.mcp.json"`) AND — unintentionally —
+  project-scoped MCP config picked up by Claude Code when working in
+  this repo. In project scope `${CLAUDE_PLUGIN_ROOT}` is never
+  substituted (it is plugin-scope only), so the spawn ran
+  `python3 '<repo>/${CLAUDE_PLUGIN_ROOT}/scripts/launcher.py'` → ENOENT
+  → "MCP error -32000: Connection closed", shadowing the healthy
+  plugin-scoped server (`plugin:cortex:cortex`, which connected in
+  ~1.7s in the same session's logs). Fix: the MCP server config moved
+  inline into `.claude-plugin/plugin.json` `mcpServers` (documented
+  form, plugins-reference) and the repo-root `.mcp.json` was deleted —
+  inline plugin config is invisible to project-scope discovery. The
+  contract test now reads the inline object and pins the absence of a
+  repo-root `.mcp.json`.
+
 ## [3.19.3] - 2026-06-11
 
 ### Fixed

CHANGELOG.md

@@ -8,9 +8,9 @@
 
 Also verifies CLAUDE_PLUGIN_DATA controls deps_dir location.
 
-Source: Discord report 2026-05-09 — `.mcp.json` now uses
-${CLAUDE_PLUGIN_ROOT} substitution; we must confirm the launcher
-honours it correctly.
+Source: Discord report 2026-05-09 — the plugin MCP config (inline in
+.claude-plugin/plugin.json) uses ${CLAUDE_PLUGIN_ROOT} substitution;
+we must confirm the launcher honours it correctly.
 """
 
 from __future__ import annotations

tests_py/scripts/test_launcher_resolution.py

@@ -1,7 +1,8 @@
-"""Contract test for .mcp.json — the plugin↔Claude-Code interface.
+"""Contract test for the plugin MCP server config — the plugin↔Claude-Code interface.
 
-Verifies the `.mcp.json` shape against the documented Claude Code plugin
-contract. Source: https://code.claude.com/docs/en/plugins-reference,
+Verifies the inline `mcpServers` object in `.claude-plugin/plugin.json`
+against the documented Claude Code plugin contract.
+Source: https://code.claude.com/docs/en/plugins-reference,
 section "Environment variables":
 
   > ${CLAUDE_PLUGIN_ROOT}: ... Both are substituted inline anywhere they
@@ -16,16 +17,29 @@
     "env": { "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data" }
   }
 
-Discord 2026-05-09: prior `.mcp.json` used a Python `-c` one-liner that
+History of this contract:
+
+Discord 2026-05-09: prior config used a Python `-c` one-liner that
 read ~/.claude/plugins/installed_plugins.json and execvp'd into the
 launcher. Failure modes were silent because `python3 -c` swallowed stack
 traces. The fix routes through the documented substitution mechanism.
 
-This test guards against regression to the inline `-c` script (the
-substitutability violation: the inline script imposed a STRONGER
-precondition than the contract — it required a specific marketplace
-key in installed_plugins.json, rejecting --plugin-dir / --plugin-url /
-manual-install scenarios that the documented contract supports).
+2026-06-12: the config moved from a repo-root `.mcp.json` (referenced by
+plugin.json as "./.mcp.json") to an inline object in plugin.json. Reason:
+Claude Code ALSO interprets a repo-root `.mcp.json` as PROJECT-scoped MCP
+config when the plugin source repo itself is opened as a working
+directory. In project scope `${CLAUDE_PLUGIN_ROOT}` is never substituted
+(it is plugin-scope only), so the spawn ran
+`python3 '<repo>/${CLAUDE_PLUGIN_ROOT}/scripts/launcher.py'` → ENOENT →
+"MCP error -32000: Connection closed" on every session in this repo,
+shadowing the healthy plugin-scoped server. Inline plugin.json
+`mcpServers` is documented and is invisible to project-scope discovery.
+
+This test guards against regression to either failure mode: the inline
+`-c` script (substitutability violation: it imposed a STRONGER
+precondition than the contract — a specific marketplace key in
+installed_plugins.json) and the reintroduction of a repo-root
+`.mcp.json`.
 """
 
 from __future__ import annotations
@@ -36,17 +50,41 @@
 import pytest
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
-MCP_JSON = REPO_ROOT / ".mcp.json"
+PLUGIN_JSON = REPO_ROOT / ".claude-plugin" / "plugin.json"
 
 
 @pytest.fixture(scope="module")
 def mcp_config() -> dict:
-    return json.loads(MCP_JSON.read_text())
+    manifest = json.loads(PLUGIN_JSON.read_text())
+    return manifest["mcpServers"]
+
+
+def test_mcp_servers_inline_object(mcp_config: dict) -> None:
+    """`mcpServers` must be an inline object, not a path string.
 
+    A path string ("./.mcp.json") requires a repo-root `.mcp.json`,
+    which Claude Code double-interprets as project-scoped config when
+    the plugin source repo is the working directory (see module
+    docstring, 2026-06-12).
+    """
+    assert isinstance(mcp_config, dict), (
+        f"mcpServers must be an inline object, got: {type(mcp_config).__name__}"
+    )
+    assert "cortex" in mcp_config
 
-def test_mcp_json_exists(mcp_config: dict) -> None:
-    assert "mcpServers" in mcp_config
-    assert "cortex" in mcp_config["mcpServers"]
+
+def test_no_repo_root_mcp_json() -> None:
+    """A repo-root `.mcp.json` must not exist.
+
+    Claude Code picks it up as PROJECT-scoped MCP config in this repo,
+    where ${CLAUDE_PLUGIN_ROOT} is never substituted — the spawn fails
+    with -32000 and shadows the healthy plugin-scoped server.
+    """
+    assert not (REPO_ROOT / ".mcp.json").exists(), (
+        "Repo-root .mcp.json reintroduced — it double-registers as "
+        "project-scoped config with unsubstituted ${CLAUDE_PLUGIN_ROOT}. "
+        "Keep the MCP server config inline in .claude-plugin/plugin.json."
+    )
 
 
 def test_no_inline_python_c_wrapper(mcp_config: dict) -> None:
@@ -56,9 +94,9 @@ def test_no_inline_python_c_wrapper(mcp_config: dict) -> None:
     installed_plugins.json. Manual installs and --plugin-dir runs broke
     silently because python3 -c discarded the traceback.
     """
-    args = mcp_config["mcpServers"]["cortex"]["args"]
+    args = mcp_config["cortex"]["args"]
     assert "-c" not in args, (
-        "Detected `-c` inline script in .mcp.json args. This swallows "
+        "Detected `-c` inline script in mcpServers args. This swallows "
         "launcher errors and breaks --plugin-dir / manual-install. "
         "Use ${CLAUDE_PLUGIN_ROOT}/scripts/launcher.py instead."
     )
@@ -71,7 +109,7 @@ def test_args_use_claude_plugin_root_substitution(mcp_config: dict) -> None:
     the form ${CLAUDE_PLUGIN_ROOT} are substituted inline before the
     process is spawned.
     """
-    args = mcp_config["mcpServers"]["cortex"]["args"]
+    args = mcp_config["cortex"]["args"]
     joined = " ".join(args)
     assert "${CLAUDE_PLUGIN_ROOT}" in joined, (
         f"args[] must reference ${{CLAUDE_PLUGIN_ROOT}} for plugin path "
@@ -81,7 +119,7 @@ def test_args_use_claude_plugin_root_substitution(mcp_config: dict) -> None:
 
 def test_launcher_path_referenced(mcp_config: dict) -> None:
     """The args must point at scripts/launcher.py with the mcp_server target."""
-    args = mcp_config["mcpServers"]["cortex"]["args"]
+    args = mcp_config["cortex"]["args"]
     assert any("scripts/launcher.py" in a for a in args), (
         f"Expected scripts/launcher.py in args, got: {args}"
     )
@@ -106,5 +144,5 @@ def test_command_is_python3(mcp_config: dict) -> None:
     """`command` must be a python interpreter; the contract requires the
     spawned process to be able to execute the launcher.py script.
     """
-    cmd = mcp_config["mcpServers"]["cortex"]["command"]
+    cmd = mcp_config["cortex"]["command"]
     assert cmd in ("python3", "python"), f"Expected python3 (or python), got: {cmd!r}"