arthur-s · Oct 3, 2026 · Oct 3, 2026 · Oct 3, 2026 · Oct 3, 2026
diff --git a/README.md b/README.md
@@ -91,6 +91,8 @@ softpractice update
 | `softpractice open` | Open the task, material, or latest result in the browser |
 | `softpractice mcp` | Run the MCP server for Claude Code, Codex, Claude Desktop, and other agents |
 | `softpractice mcp setup codex-desktop` | Configure MCP for Codex Desktop without installing Codex CLI |
+| `softpractice mcp status` | Check the running server and its project |
+| `softpractice mcp remove codex-desktop` | Remove the connection from Codex settings |
 | `softpractice project restore` | Restore a project from the latest usable revision |
 
 Run `softpractice help <command>` for detailed help.
@@ -149,128 +151,120 @@ never replaces them, and they are not part of your submission.
 
 `softpractice mcp` connects a coding agent to your SoftPractice lesson:
 reading the task and material, running public checks, submitting a commit, and
-reading the evaluation. It is a local **stdio** MCP server: your MCP client
-starts the process and communicates with it. No server URL or listening port
-is needed.
+reading the evaluation.
 
-### Before connecting
+### Configure once, from any folder
 
-Install the CLI (see [Install](#install)), sign in, and open an existing lesson
-Git project, downloaded with `softpractice starter` or restored with
-`softpractice project restore`:
+Install the CLI (see [Install](#install)), then configure your desktop client.
+You do not need a lesson project yet:
 
 ```bash
-softpractice login
-cd /path/to/your/lesson-project
-softpractice status
+softpractice mcp setup claude-desktop
+# or
+softpractice mcp setup codex-desktop
 ```
 
-The MCP server uses the CLI's saved sign-in. It never starts a sign-in itself;
-there is no separate MCP OAuth login. Configure the launch command
-`softpractice mcp` in your client. The client starts it for you, so you do not
-need to leave it running in a terminal.
+Setup registers the CLI's absolute executable path and `mcp connect` as the
+launch arguments. It preserves other settings and saves the previous file as
+`.bak`. Claude Desktop uses `claude_desktop_config.json`; on Windows, setup
+also finds the configuration used by the Microsoft Store version. Codex uses
+`~/.codex/config.toml` (or `$CODEX_HOME/config.toml`) and a tool timeout of
+180 seconds. Codex Desktop, CLI, and the IDE extension share these settings.
+No separate Codex CLI installation is needed for desktop setup.
 
-By default it works in the directory where the client starts it. Use
-`--project /absolute/path/to/your/lesson-project` to pin the folder, especially
-for desktop clients. When switching projects, change that path. If the client
-cannot find `softpractice` on `PATH`, use the executable's full path as the
-command. The client must run on the computer where the CLI and project exist.
+For manual configuration, append `--print` to either setup command. It prints
+the JSON or TOML entry without writing settings. Replace an existing
+`softpractice` entry rather than adding a duplicate.
 
-### Claude Desktop
+### Start the lesson server
 
-From the lesson project folder:
+Sign in, then start the server for a Git project downloaded with
+`softpractice starter` or restored with `softpractice project restore`:
 
 ```bash
-softpractice mcp setup claude-desktop
+softpractice login
+cd /path/to/your/lesson-project
+softpractice mcp
 ```
 
-The command adds the `softpractice` server to the Claude Desktop settings
-file, `claude_desktop_config.json`, with absolute paths to the program and the
-project: Claude Desktop does not see the `PATH` from your terminal profile and
-does not start the server in your project folder. Other servers and app
-settings in the file are kept; the previous file is saved next to it as
-`claude_desktop_config.json.bak`. On Windows, the command also finds the file
-that the Microsoft Store version of the app actually reads.
-
-Then quit Claude Desktop completely, not just its window, and start it again.
-The `softpractice` tools appear in the chat's tools menu. When you switch to
-another lesson project, run the command again in its folder.
-
-To configure the app manually, print the entry and add it to `mcpServers` in
-the file opened by **Settings → Developer → Edit Config**, keeping the servers
-already configured:
+Or start from any folder with an explicit project:
 
 ```bash
-softpractice mcp setup claude-desktop --print
+softpractice mcp --project /path/to/your/lesson-project
 ```
 
-### Claude Code
+Keep this terminal open. The server validates the Git repository and
+SoftPractice project link before accepting connections. It uses the CLI's
+saved sign-in; it never opens a sign-in flow itself.
 
-From the lesson project folder:
+Start the server before restarting the desktop client. The client's stdio
+bridge, `softpractice mcp connect`, forwards MCP messages to the running
+server on `127.0.0.1:39473`. Connections require a random per-run key saved in
+the CLI's user configuration folder. Both processes must run on the same
+computer under the same user and use the same `SOFTPRACTICE_CONFIG_DIR` if
+that environment variable is set. This address is not an HTTP URL.
 
-```bash
-claude mcp add --transport stdio --scope local softpractice -- softpractice mcp
-claude mcp list
-```
+Only one lesson server can run on this computer at a time. To switch projects,
+stop it with Ctrl+C, start it in the other lesson folder, and reconnect the
+client's MCP connection (or restart the client). Setup does not need to be
+repeated. If the server is offline, the bridge prints the startup command to
+stderr and exits; start the server and reconnect.
 
-This registration is private to you and applies to this project. Start Claude
-Code in the same folder; use `/mcp` to check the connection. See the
-[Claude Code MCP documentation](https://code.claude.com/docs/en/mcp).
+### Claude Code and Codex CLI
 
-### Codex Desktop
-
-From the lesson project folder:
+To use the same manually started server:
 
 ```bash
-softpractice mcp setup codex-desktop
+claude mcp add --transport stdio --scope user softpractice -- softpractice mcp connect
+# or, if Codex Desktop setup has not already configured it:
+codex mcp add softpractice -- softpractice mcp connect
 ```
 
-You do not need to install Codex CLI. The command adds the `softpractice`
-server to `~/.codex/config.toml` with absolute paths to the program and project
-and a tool timeout of 180 seconds. If `CODEX_HOME` is set, it uses
-`config.toml` in that folder. Other settings, servers, and their comments
-are kept; the previous file is saved next to it as `config.toml.bak`.
-Running setup again for the same project leaves the file unchanged.
+If the client cannot find `softpractice`, use the executable's full path.
+See the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp)
+and [Codex MCP documentation](https://developers.openai.com/codex/mcp).
+
+`softpractice mcp` always starts the local server, including with redirected
+stdin or in the background. Only server startup selects the project. Setup
+connects the client to the single running server and does not accept `--project`.
 
-Restart Codex Desktop, open the lesson project folder, and check the
-`softpractice` server in the MCP settings. Ask the agent: “Use the
-SoftPractice MCP server to show my lesson status and current task.” It
-should call `status` and `task`. When switching to another lesson project,
-run the command again in its folder or pass
-`--project /absolute/path/to/your/lesson-project`.
+### Checking the server
 
-To configure the app manually, print the TOML entry:
+From any folder, check which server is running:
 
 ```bash
-softpractice mcp setup codex-desktop --print
+softpractice mcp status
+softpractice mcp status --json
 ```
 
-Add it to `config.toml`, keeping the servers already configured. If
-`[mcp_servers.softpractice]` already exists, replace that table instead of
-adding a duplicate. Codex Desktop, CLI, and the IDE extension share these
-settings on the same host. Setup pins one project to the `softpractice`
-server for all these clients. A trusted project's `.codex/config.toml` can
-override user-level settings. See the
-[official Codex MCP documentation](https://developers.openai.com/codex/mcp).
+The command checks a live connection and shows the lesson folder, PID,
+local address, and CLI version. A stopped server returns `not_running`;
+a key file left after a crash is not treated as proof of a running server.
+No lesson project or sign-in is needed. This reports the local process;
+lesson information remains available through `softpractice status` and the
+MCP `status` tool.
 
-### Codex CLI
+### Stopping the server and removing the connection
 
-If you already configured Codex Desktop with the command above, no further
-registration is needed. Start `codex` in the lesson folder; `/mcp` shows
-active servers.
+Press Ctrl+C in the server's terminal to stop the lesson server. The client
+configuration remains available for the next startup.
 
-To configure using Codex CLI, replace the project path:
+To remove the client connection, run from any folder:
 
 ```bash
-codex mcp add softpractice -- softpractice mcp --project /path/to/your/lesson-project
-codex mcp list
+softpractice mcp remove claude-desktop
+# or
+softpractice mcp remove codex-desktop
 ```
 
-For local checks and evaluation polling, add `tool_timeout_sec = 180` to
-the generated `[mcp_servers.softpractice]` table in `~/.codex/config.toml`.
-If the client cannot find `softpractice`, use the executable's full path.
-You can also use `softpractice mcp setup codex-desktop`: it configures the
-same file.
+This removes only the SoftPractice entry, preserves other settings, and saves
+the previous file as `.bak`. Repeating the command is safe: missing entries
+or files are left untouched. Restart the client to apply the change. Codex
+shares these settings between Desktop, CLI, and the IDE extension; project
+settings may override them.
+
+Removing the connection does not stop the lesson server. To reconnect,
+run the corresponding `softpractice mcp setup` command again.
 
 ### Using the server