Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

fix(mcp): warn on an unknown CLAUDISH_MCP_TOOLS value

Jack Rudenko29b0b230216f
diff --git a/ai-docs/architecture/mcp-channel.md b/ai-docs/architecture/mcp-channel.md
index f2128b0c..cb89a196 100644
--- a/ai-docs/architecture/mcp-channel.md
+++ b/ai-docs/architecture/mcp-channel.md
@@ -346,7 +346,11 @@ Tool gating via the `CLAUDISH_MCP_TOOLS` env var (lower-cased, `resolveToolGroup
| `agentic` | `preflight`, `team`, `report_error` |
| `session` | the 7 session tools |
| `debug` | `compare_models` |
-| `channel`, or any other value | all 14 |
+| `channel`, or any other value | all 14, plus one stderr line naming the value and the valid ones (`unknownToolModeWarning`); for `channel` it says the group was renamed to `session` |
+
+Unknown values keep selecting everything, because a server that lists fewer tools than its host
+expects fails later and quietly. The stderr line is there so a typo is not read as `all` with
+no trace.
`session` was `channel` until 10.7.0. The rename removed the old name with no alias, per the
thesaurus rule, so `channel` now falls into the unknown-value rule and selects everything. The
diff --git a/docs/usage/mcp-server.md b/docs/usage/mcp-server.md
index eb84ea0a..b7ef6589 100644
--- a/docs/usage/mcp-server.md
+++ b/docs/usage/mcp-server.md
@@ -258,10 +258,17 @@ The session tools are in the `session` group, which `all` (the default) includes
| `agentic` | `preflight`, `team`, `report_error` |
| `session` | `create_session`, `send_input`, `get_output`, `cancel_session`, `list_sessions`, `get_diagnostics`, `capture_session` |
| `debug` | `compare_models` |
-| any other value | all 14 |
+| any other value | all 14, with a warning on stderr |
+
+Any other value still selects all 14 tools, and the server writes one line to stderr naming the
+value and the valid ones:
+
+```
+[claudish] CLAUDISH_MCP_TOOLS="agentc" is not a tool mode; selecting all tools. Valid values: all, low-level, agentic, session, debug
+```
`channel` was the old name of the `session` group. It is no longer a group, so it selects all 14
-tools.
+tools, and the warning says it was renamed to `session`.
### Polling workflow
diff --git a/packages/cli/src/mcp-server.ts b/packages/cli/src/mcp-server.ts
index 17bd7204..7770ceca 100644
--- a/packages/cli/src/mcp-server.ts
+++ b/packages/cli/src/mcp-server.ts
@@ -2304,11 +2304,27 @@ function resolveToolGroups(mode: string): Set<ToolGroup> {
}
}
+/** Every value `CLAUDISH_MCP_TOOLS` recognises, in the order the docs list them. */
+const TOOL_MODES = ["all", "low-level", "agentic", "session", "debug"] as const;
+
+/**
+ * The stderr line for a `CLAUDISH_MCP_TOOLS` value that names no tool mode, or
+ * undefined for a recognised one. The value still selects every tool; the line
+ * exists so a typo, or the removed `channel`, is not silently read as `all`.
+ */
+function unknownToolModeWarning(mode: string): string | undefined {
+ if ((TOOL_MODES as readonly string[]).includes(mode)) return undefined;
+ const renamed = mode === "channel" ? " (`channel` was renamed to `session`)" : "";
+ return `[claudish] CLAUDISH_MCP_TOOLS=${JSON.stringify(mode)} is not a tool mode${renamed}; selecting all tools. Valid values: ${TOOL_MODES.join(", ")}`;
+}
+
// ─── Server Setup ────────────────────────────────────────────────────────────
async function main() {
const toolMode = (process.env.CLAUDISH_MCP_TOOLS || "all").toLowerCase();
const enabledGroups = resolveToolGroups(toolMode);
+ const toolModeWarning = unknownToolModeWarning(toolMode);
+ if (toolModeWarning) console.error(toolModeWarning);
// Tools only, for every tool mode. No `experimental: {"claude/channel": {}}`: the
// server pushes nothing; a host polls `list_sessions` and reads the records.