feat(mcp): document removal and warn on mcpServers in config.yaml

The default agent's system prompt now documents the full MCP lifecycle —
add (stdio/http), remove, list, and test — and hard-steers off writing
mcpServers into config.yaml/YAML, which Pythinker never parses for MCP (the
entry is silently dropped and the server never appears in /mcp).

As a backstop, MCP config loading now logs a warning when it finds an
mcpServers block in a global or project config.yaml, so a misplaced entry is
diagnosable in pythinker.log instead of failing silently.

Adds regression tests for the prompt guidance and the loader detection.

Author: elkaix

CHANGELOG.md

@@ -21,7 +21,7 @@ GitHub Releases page; `0.8.0` is the new starting line.
 - **Agent phase-0 enhancements.** Adds a model-invocable cross-session Recall tool (search and read prior sessions on demand, sanitized and read-only for subagents), read-only MCP resources/prompts surfaced as tools, project-scoped `.pythinker/mcp.json` layering, subagent token/cost roll-up to the orchestrator, and truncated tool output that spills to disk with a recovery hint instead of being lost.
 - **No more spurious `coroutine … was never awaited` warnings.** Dropped Sentry's `AsyncioIntegration`, whose `create_task` monkeypatch wrapped every coroutine and — when a task was cancelled before its first step during turn/prompt teardown — orphaned the inner coroutine, printing `WireUISide.receive` and prompt_toolkit "never awaited" `RuntimeWarning`s to the console. The integration added no spans (tracing/profiling are off), and exception capture for async tasks is preserved by the existing asyncio exception handler.
 - **Read-only profile guard hardened against version-pinned interpreters.** Inline-code interpreter invocations that use a version-suffixed or absolute binary (`python3.14 -c …`, `/usr/bin/python3.12 -c …`, `node20 -e …`) are now classified as mutating/destructive just like the bare `python`/`node` forms, so they can no longer bypass a read-only subagent profile or skip destructive deliberation.
-- **The agent sets up MCP servers on request instead of refusing.** Asked to add or set up an MCP server, the default agent now knows it runs in Pythinker: it configures the server via `pythinker mcp add` or by editing `~/.pythinker/mcp.json` / `./.pythinker/mcp.json`, then tells you to restart to load it — rather than refusing or citing Claude Code/Desktop config paths (`~/.claude.json`) it cannot use.
+- **The agent sets up and removes MCP servers on request instead of refusing.** Asked to add, remove, or set up an MCP server, the default agent now knows it runs in Pythinker: it configures the server with the `pythinker mcp add`/`remove` CLI (or by editing `~/.pythinker/mcp.json` / `./.pythinker/mcp.json`), verifies with `pythinker mcp list`/`test`, and tells you to restart or `/reload` to load the change — rather than refusing or citing Claude Code/Desktop config paths (`~/.claude.json`) it cannot use. The prompt now also hard-steers the agent away from writing `mcpServers` into `~/.pythinker/config.yaml` (YAML is never parsed for MCP, so such an entry is silently dropped and the server never appears in `/mcp`). As a backstop, MCP config loading now logs a warning when it finds an `mcpServers` block in a `config.yaml` (global or project), so a human or agent that misplaces it gets a diagnosable trace instead of a silent drop.
 
 ## 0.38.0 (2026-06-08)
 

src/pythinker_code/agents/default/system.md

@@ -114,7 +114,16 @@ When handling the user's request, if it involves creating, modifying, or running
 
 MCP (Model Context Protocol) servers expose their capabilities as ordinary tools that are already connected and present in your toolset (their descriptions name the originating server). When the user asks to use, test, or call an MCP server, just invoke its tools directly — never pip install the server, import it as a Python module, or search the repo for its configuration. If the user names an MCP server but you see no tools from it in your toolset, the server is not connected (still loading, failed, or unauthorized) rather than missing — do not try to install or build it. Tell the user to check `/mcp` for server status, and for an OAuth server reported as unauthorized, to run `pythinker mcp auth <server_name>`.
 
-When the user asks you to **add, install, or set up a new MCP server** (as opposed to using one that is already connected), you can and should do it — you are running in **Pythinker**, whose MCP configuration is a JSON file you have the tools to edit. This is not Claude Code or Claude Desktop, so never reference `~/.claude.json`, `claude_desktop_config.json`, or any non-Pythinker config path. Server definitions live under the `mcpServers` map in `./.pythinker/mcp.json` (project-scoped, applies to this workspace) and `~/.pythinker/mcp.json` (global); the global file loads first and the project file layers on top. Configure a server either by running `pythinker mcp add <name> …` via `Shell` (e.g. `pythinker mcp add --transport stdio <name> -- npx some-mcp@latest`, or `pythinker mcp add --transport http <name> <url>`) or by writing the `mcpServers` entry directly into one of those JSON files. A newly added server is **not** available in the current session — its tools only connect the next time Pythinker starts — so after configuring it, do the actual edit, then tell the user to restart Pythinker and use `/mcp` to confirm it loaded. Never claim a server has been added without actually writing the config, and never refuse on the grounds that you "have no tool to edit it."
+When the user asks you to **add, remove, install, or set up an MCP server** (as opposed to using one that is already connected), you can and should do it — you are running in **Pythinker**, whose MCP configuration is a **JSON** file you have the tools to edit. This is not Claude Code or Claude Desktop, so never reference `~/.claude.json`, `claude_desktop_config.json`, or any non-Pythinker config path. Server definitions live under the `mcpServers` map in `./.pythinker/mcp.json` (project-scoped, applies to this workspace) and `~/.pythinker/mcp.json` (global); the global file loads first and the project file layers on top. **Only these `mcp.json` files are read for MCP.** Never put an `mcpServers` block in `~/.pythinker/config.yaml` or any YAML file — `config.yaml` holds unrelated user settings, is not parsed for MCP, and an `mcpServers` entry there is silently dropped, so the server never appears in `/mcp`.
+
+Prefer the `pythinker mcp` CLI (run via `Shell`) over hand-editing JSON — it validates the entry and fails loudly instead of writing a broken config:
+
+- Add a stdio server: `pythinker mcp add --transport stdio <name> -- npx some-mcp@latest`
+- Add an HTTP server: `pythinker mcp add --transport http <name> <url>` (append `--header "KEY: value"` for auth, or `--auth oauth` for an OAuth server)
+- Remove a server: `pythinker mcp remove <name>`
+- Verify: `pythinker mcp list` to confirm it is registered, and `pythinker mcp test <name>` to check it actually connects and list its tools
+
+If you hand-edit instead, write the `mcpServers` entry only into one of the `mcp.json` files above — never YAML. A newly added or removed server does **not** take effect in the current session; the toolset connects servers only when Pythinker next starts or the user runs `/reload`. So after configuring it, do the actual edit, then tell the user to restart Pythinker (or run `/reload`) and use `/mcp` to confirm the change. Never claim a server has been added or removed without actually writing the config, and never refuse on the grounds that you "have no tool to edit it."
 
 If the `Agent` tool is available, you can use it to delegate a focused subtask to a subagent instance. Treat subagents as focused roles, not just extra capacity: use `explore` for read-only mapping, `plan` for strategy, `coder` or `implementer` for scoped edits, `review` for severity-scored critique, `verifier` for validation gates, and `judge` for final quality checks before delivery. The tool can either start a new instance or resume an existing one by `agent_id`. Subagent instances are persistent session objects with their own context history. When delegating, provide a complete prompt with all necessary context because a newly created subagent instance does not automatically see your current context. If an existing subagent already has useful context or the task clearly continues its prior work, prefer resuming it instead of creating a new instance. Default to foreground subagents. Use `run_in_background=true` only when there is a clear benefit to letting the conversation continue before the subagent finishes, and you do not need the result immediately to decide your next step. Spawn multiple subagents in the same turn when they can investigate independent regions concurrently, but keep background launches within available background task slots.
 

src/pythinker_code/cli/__init__.py

@@ -4,7 +4,7 @@
 import os
 from importlib import import_module
 from pathlib import Path
-from typing import TYPE_CHECKING, Annotated, Any, Literal
+from typing import TYPE_CHECKING, Annotated, Any, Literal, cast
 
 import typer
 
@@ -191,6 +191,51 @@ def _find_project_mcp_config_file() -> Path | None:
     return None
 
 
+def _yaml_files_with_misplaced_mcp_servers() -> list[Path]:
+    """Return ``config.yaml``/``.yml`` files that wrongly carry an ``mcpServers`` block.
+
+    Pythinker reads MCP servers only from ``mcp.json`` (see
+    ``_load_mcp_configs_from_cli_inputs``); a ``config.yaml`` is not part of that
+    path. An ``mcpServers`` block written into a ``config.yaml`` is therefore never
+    parsed for MCP — the server silently fails to load and never appears in
+    ``/mcp``. We surface that as a warning instead of dropping it silently.
+
+    Checks the global ``~/.pythinker`` directory and the nearest project
+    ``.pythinker`` directory (walking up to the repository root), mirroring the
+    two locations from which ``mcp.json`` itself is read.
+    """
+    import yaml
+
+    from .mcp import get_global_mcp_config_file
+
+    dirs: list[Path] = [get_global_mcp_config_file().parent]
+    cwd = Path.cwd().resolve()
+    for directory in (cwd, *cwd.parents):
+        project_dir = directory / ".pythinker"
+        if project_dir.is_dir():
+            dirs.append(project_dir)
+        if (directory / ".git").exists():
+            break
+
+    offending: list[Path] = []
+    seen: set[Path] = set()
+    for directory in dirs:
+        for name in ("config.yaml", "config.yml"):
+            path = directory / name
+            if path in seen:
+                continue
+            seen.add(path)
+            if not path.is_file():
+                continue
+            try:
+                data = yaml.safe_load(path.read_text(encoding="utf-8"))
+            except (OSError, yaml.YAMLError):
+                continue
+            if isinstance(data, dict) and cast("dict[str, Any]", data).get("mcpServers"):
+                offending.append(path)
+    return offending
+
+
 def _load_mcp_configs_from_cli_inputs(
     mcp_config_file: list[Path] | None,
     mcp_config: list[str] | None,
@@ -239,6 +284,17 @@ def _load_mcp_configs_from_cli_inputs(
         except json.JSONDecodeError as e:
             raise typer.BadParameter(f"Invalid JSON: {e}", param_hint="--mcp-config") from e
 
+    for path in _yaml_files_with_misplaced_mcp_servers():
+        from pythinker_code.utils.logging import logger
+
+        logger.warning(
+            "Ignoring `mcpServers` in {path}: Pythinker reads MCP servers only from "
+            "mcp.json, so this block has no effect and the server will not appear in "
+            "/mcp. Move it into ~/.pythinker/mcp.json (or .pythinker/mcp.json), e.g. "
+            "with `pythinker mcp add`.",
+            path=path,
+        )
+
     return configs
 
 

tests/core/test_cli_reload.py

@@ -5,7 +5,10 @@
 
 import pytest
 
-from pythinker_code.cli import _load_mcp_configs_from_cli_inputs
+from pythinker_code.cli import (
+    _load_mcp_configs_from_cli_inputs,
+    _yaml_files_with_misplaced_mcp_servers,
+)
 
 
 def test_load_mcp_configs_rechecks_default_file_between_reloads(
@@ -27,3 +30,68 @@ def test_load_mcp_configs_rechecks_default_file_between_reloads(
     default_mcp_file.write_text(json.dumps(expected), encoding="utf-8")
 
     assert _load_mcp_configs_from_cli_inputs(None, None) == [expected]
+
+
+def test_detects_misplaced_mcp_servers_in_yaml_configs(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    """`mcpServers` in a config.yaml (global or project) is flagged, since
+    Pythinker reads MCP only from mcp.json and would otherwise drop it silently."""
+    share = tmp_path / "share"
+    share.mkdir()
+    monkeypatch.setattr(
+        "pythinker_code.cli.mcp.get_global_mcp_config_file", lambda: share / "mcp.json"
+    )
+    (share / "config.yaml").write_text("mcpServers:\n  foo:\n    command: npx\n", encoding="utf-8")
+
+    project = tmp_path / "proj"
+    (project / ".pythinker").mkdir(parents=True)
+    (project / ".git").mkdir()
+    (project / ".pythinker" / "config.yaml").write_text(
+        "mcpServers:\n  bar:\n    command: npx\n", encoding="utf-8"
+    )
+    monkeypatch.chdir(project)
+
+    found = {p.resolve() for p in _yaml_files_with_misplaced_mcp_servers()}
+    assert (share / "config.yaml").resolve() in found
+    assert (project / ".pythinker" / "config.yaml").resolve() in found
+
+
+def test_clean_yaml_config_is_not_flagged(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    """A config.yaml without an `mcpServers` block must not be flagged."""
+    share = tmp_path / "share"
+    share.mkdir()
+    monkeypatch.setattr(
+        "pythinker_code.cli.mcp.get_global_mcp_config_file", lambda: share / "mcp.json"
+    )
+    (share / "config.yaml").write_text(
+        "onboarding:\n  seen:\n    busy_input_prompt: true\n", encoding="utf-8"
+    )
+    project = tmp_path / "proj"
+    project.mkdir()
+    (project / ".git").mkdir()
+    monkeypatch.chdir(project)
+
+    assert _yaml_files_with_misplaced_mcp_servers() == []
+
+
+def test_load_mcp_configs_ignores_misplaced_yaml(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    """A stray mcpServers-in-config.yaml must not break loading or leak into the
+    returned configs — only the real mcp.json is loaded."""
+    share = tmp_path / "share"
+    share.mkdir()
+    mcp_file = share / "mcp.json"
+    monkeypatch.setattr("pythinker_code.cli.mcp.get_global_mcp_config_file", lambda: mcp_file)
+    expected = {"mcpServers": {"ctx": {"url": "https://mcp.example.test", "transport": "http"}}}
+    mcp_file.write_text(json.dumps(expected), encoding="utf-8")
+    (share / "config.yaml").write_text(
+        "mcpServers:\n  ignored:\n    command: npx\n", encoding="utf-8"
+    )
+    project = tmp_path / "proj"
+    project.mkdir()
+    (project / ".git").mkdir()
+    monkeypatch.chdir(project)
+
+    assert _load_mcp_configs_from_cli_inputs(None, None) == [expected]

tests/core/test_load_agent.py

@@ -81,6 +81,29 @@ def test_system_prompt_explains_adding_mcp_servers(builtin_args: BuiltinSystemPr
     assert "not Claude Code or Claude Desktop" in prompt
 
 
+def test_system_prompt_explains_removing_and_rejects_yaml_mcp_config(
+    builtin_args: BuiltinSystemPromptArgs,
+):
+    """The agent must also know how to *remove* a server, and must be steered off
+    the real-world failure of writing `mcpServers` into `config.yaml` (YAML),
+    which Pythinker never parses for MCP — the entry is silently dropped and the
+    server never shows in `/mcp`.
+    """
+    from pythinker_code.agentspec import DEFAULT_AGENT_FILE
+
+    prompt = _load_system_prompt(
+        DEFAULT_AGENT_FILE.parent / "system.md",
+        {"ROLE_ADDITIONAL": ""},
+        builtin_args,
+    )
+
+    # Removal is documented, not just add.
+    assert "pythinker mcp remove" in prompt
+    # Hard steer away from the config.yaml / YAML misplacement seen in the wild.
+    assert "config.yaml" in prompt
+    assert "silently dropped" in prompt
+
+
 def test_system_prompt_treats_injected_date_as_authoritative(
     builtin_args: BuiltinSystemPromptArgs,
 ):