mcp-patchbay 0.0.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,128 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
5
+ [Semantic Versioning](https://semver.org/).
6
+
7
+ ## 0.1.1 - 2026-11-16
8
+
9
+ ### Added
10
+
11
+ - Zero-config first run. When the default config, `~/.config/mcp-patchbay/servers.json`, does
12
+ not exist, the patchbay creates it with no servers (`{"version": 1, "servers": {}}`; on POSIX
13
+ the file at mode 600 and, if it has to create it, the directory at mode 700), logs one stderr
14
+ line saying where and how to add servers, and serves its own tools. Before, it exited 78. An existing group- or
15
+ world-writable directory is still refused before anything is written, and a missing
16
+ `--config` or `$MCP_PATCHBAY_CONFIG` file anywhere else is still an error (exit 78).
17
+ - A leading `~` or `${HOME}` in `--config` and `$MCP_PATCHBAY_CONFIG` is expanded. An empty
18
+ `--config=` is now a usage error (exit 64) instead of meaning the default.
19
+ - MCP Registry listing as `io.github.distronode-corporation/mcp-patchbay`: `server.json`, the
20
+ `mcpName` field in `package.json`, and a release step that publishes it with
21
+ `mcp-publisher` through GitHub OIDC once the npm version is out.
22
+ - A Claude Desktop extension bundle, `mcp-patchbay-<version>.mcpb`, built and validated with
23
+ the MCPB CLI, smoke-tested on macOS, Windows and Linux, and attached to each GitHub release.
24
+ - PRIVACY.md and a Privacy Policy section in the README: the patchbay collects and sends
25
+ nothing.
26
+
27
+ ### Documentation
28
+
29
+ - README Quick start: `claude mcp add` comes first and works on its own; adding connectors is
30
+ the next step.
31
+
32
+ ## 0.1.0 - 2026-11-14
33
+
34
+ ### Added
35
+
36
+ - An MCP server over stdio that hosts configured MCP servers as child processes, with the tools
37
+ `servers`, `enable`, `disable`, `restart` and `info`. Each carries
38
+ `_meta: {"anthropic/alwaysLoad": true}`.
39
+ - Policies `allow`, `confirm` and `deny`. `confirm` asks a person through a form-mode
40
+ elicitation, and fails closed when the client has no elicitation support.
41
+ - Live tool publishing with `notifications/tools/list_changed`. `enable` waits up to 2 s for the
42
+ client's re-list.
43
+ - Proxying:
44
+ - pass-through tool definitions and results, with `outputSchema` not enforced;
45
+ - cancellation and progress (original progress tokens);
46
+ - `roots/list` and elicitation forwarding, and roots `list_changed` fan-out;
47
+ - sampling refused;
48
+ - merging of children's own `list_changed`;
49
+ - a per-server `timeoutMs`.
50
+ - Children:
51
+ - full env inheritance with per-entry `env`;
52
+ - a process group per child on POSIX;
53
+ - tolerance of non-JSON stdout;
54
+ - redacted stderr ring buffers;
55
+ - crash isolation;
56
+ - pidfiles, and reaping of leftovers after a crash.
57
+ - Remote servers through mcp-remote 0.15.2:
58
+ - header values kept out of argv;
59
+ - `MCP_REMOTE_CONFIG_DIR` at 0700;
60
+ - sign-in detection with a URL-mode elicitation (or a form fallback);
61
+ - the state `waiting-for-sign-in`.
62
+ - Autostart per project (`CLAUDE_PROJECT_DIR`), and instructions folded into the patchbay's own,
63
+ capped at 4,096 characters.
64
+ - Redaction of tokens, URL query strings, and entries' own env, args and headers in everything
65
+ the patchbay emits.
66
+ - CLI: `import` (from a Claude Code config), `doctor`, and `rename-permissions`.
67
+ - The `examples/write-gate` PreToolUse hook example, with tests.
68
+ - `confirmVia`, a top-level config setting: `"elicitation"` (the default, unchanged behaviour) or
69
+ `"host"`. With `"host"`, `enable` and `restart` refuse to start a `confirm` server and point to
70
+ a new tool, `enable_confirm {name}`. The host's own permission prompt for that tool is the
71
+ person's approval. This makes `confirm` servers usable in clients that do not show form
72
+ elicitation to the person, such as the Claude Code VS Code extension, which answers it
73
+ `decline`. `enable_confirm` refuses `allow` and `deny` servers and is listed only in host mode.
74
+ - `import` writes `confirmVia: "host"`.
75
+ - `doctor` prints `confirmVia` and warns about Claude Code allow rules that would approve
76
+ `enable_confirm` without asking (the exact name, `mcp__patchbay__*`, `mcp__patchbay`, `*` and
77
+ other wildcards) and about `defaultMode: "bypassPermissions"`, in the user's settings and, with
78
+ `--project <dir>`, the project's. In host mode a warning exits 1. `--no-start` skips starting
79
+ servers.
80
+ - `rename-permissions` never writes a rule that matches `enable_confirm`.
81
+
82
+ ### Fixed
83
+
84
+ - Shutdown no longer orphans children that ignore SIGTERM. A detached helper sends SIGKILL to the
85
+ remaining process groups after 500 ms, without delaying the patchbay's exit. Pidfiles are kept
86
+ until a child's exit is observed, and the startup reaper now escalates to SIGKILL. After a
87
+ crash, the leftover group members also get a SIGKILL follow-up.
88
+ - A remote server's `url` is now treated as a secret. The whole url, each path segment, each
89
+ query value and any userinfo (6+ characters) are redacted from `info`, `lastError` and logs.
90
+ mcp-remote logs the url to stderr, and many endpoints carry their key in the path. The url
91
+ is still on mcp-remote's argv (mcp-remote has no other way to take it), which is now
92
+ documented.
93
+ - Only mcp-remote children (`url` entries, an `mcp-remote` command, or `npx mcp-remote`) can
94
+ trigger the sign-in prompt, and only while they are starting. The prompt is always labelled
95
+ `[<server>] `. A re-auth request while a server is on is logged instead of prompting. The
96
+ sign-in URL is no longer written to the log, not even in redacted form.
97
+ - `rename-permissions` without `--config` now loads the default config (`$MCP_PATCHBAY_CONFIG`
98
+ or `~/.config/mcp-patchbay/servers.json`) and applies server prefixes. Before, deny rules for
99
+ prefixed servers silently stopped matching. Without a config file, it warns that names were
100
+ mapped as they are.
101
+ - A `restart` racing a `disable` no longer turns a `confirm` server back on: the disable cancels
102
+ the restart. An `enable` in that window joins the restart instead of showing a prompt whose
103
+ answer was ignored. A crash marks the server `failed` at once (it used to wait 20 ms), so a
104
+ restart right after a crash asks a person again.
105
+ - Autostart names that are inherited object keys (`constructor`, `toString`, `__proto__`) are
106
+ now rejected as unknown servers at load time (exit 78); before, they crashed `initialize`.
107
+ The same `hasOwn` check now covers `import --project` and `rename-permissions`' prefix lookup.
108
+ An env key named `__proto__` is now kept as a key instead of being dropped.
109
+ - A JSON syntax error in the config, in `import --from <claude.json>`, or in the
110
+ `rename-permissions` settings file is reported as the file path plus line and column. Node's
111
+ parser message quoted the surrounding text, which could include a token.
112
+ - Kills can no longer hit an unrelated process through a reused pid. Post-exit cleanup and the
113
+ startup reaper never fall back to signalling a bare pid. Pidfiles now record the process start
114
+ time (Linux, `v: 2`), and the reaper requires it to match and requires the pid to still lead
115
+ its own process group. A pidfile without a start time is not trusted on Linux.
116
+ - The config permission check is now complete (POSIX). The file is opened once, `fstat`ed and
117
+ read through that descriptor (no check-then-read race). A group- or world-writable (or
118
+ foreign-owned) parent directory is refused. A symlinked config is accepted only if its target
119
+ and the target's directory pass the same checks. A FIFO is refused without blocking.
120
+
121
+ ### Documentation
122
+
123
+ - SECURITY-MODEL.md, SPEC.md and README now say exactly what happens to tool results: they are
124
+ parsed with `CallToolResultSchema`, which drops unknown keys inside content blocks and
125
+ rejects unknown content types. The docs no longer claim "unchanged".
126
+ - The redaction guarantee now states its 6-character minimum and covers the url. The sign-in
127
+ URL text matches the code.
128
+ - README: `npm test` takes about 20 s, not 40 s.
package/NOTICE ADDED
@@ -0,0 +1,8 @@
1
+ mcp-patchbay
2
+ Copyright 2026 Distronode Corporation
3
+
4
+ This product includes software developed by Distronode Corporation, licensed
5
+ under the Apache License, Version 2.0. The full licence text is in LICENSE.
6
+
7
+ mcp-patchbay is original work, not a fork, and no third-party source code is
8
+ vendored into this repository.
package/PRIVACY.md ADDED
@@ -0,0 +1,47 @@
1
+ # Privacy policy
2
+
3
+ This policy covers mcp-patchbay, the npm package `mcp-patchbay` and the Claude Desktop
4
+ extension bundle (`.mcpb`) built from this repository, published by Distronode Corporation.
5
+
6
+ ## Data collection
7
+
8
+ mcp-patchbay collects nothing about you. It has no telemetry, no analytics, no crash reporting
9
+ and no update check, and it never contacts Distronode or any service of its own.
10
+
11
+ ## Usage and storage
12
+
13
+ mcp-patchbay runs on your computer and stores only these files, all under your control:
14
+
15
+ - your config, `~/.config/mcp-patchbay/servers.json` (or the path you choose), which you write;
16
+ - sign-in tokens for remote servers you configure, kept by mcp-remote in the directory set by
17
+ `oauth.configDir` (by default `~/.config/mcp-patchbay/oauth`, mode 700);
18
+ - small pidfiles in your runtime directory, so leftovers can be cleaned up after a crash;
19
+ - when you run `import` or `rename-permissions --write` yourself, a timestamped `.bak` copy of
20
+ the file it changes, next to that file.
21
+
22
+ The modes above apply on macOS and Linux. Windows has no such modes, so there these files get
23
+ the permissions of the folder they are in.
24
+
25
+ It passes tool calls and results between your MCP client (such as Claude Code or Claude Desktop)
26
+ and the servers you configured. It keeps no copy of them. Its own logs go to stderr, where your
27
+ client keeps them, and are redacted for tokens, query strings and each server's env, args and
28
+ headers (values of 6 characters or more; SECURITY-MODEL.md has the exact rules).
29
+
30
+ ## Third-party sharing
31
+
32
+ mcp-patchbay shares nothing with Distronode or anyone else. The servers you add to the config
33
+ are separate programs: when you switch one on, it may send data to its own service under that
34
+ service's privacy policy. mcp-patchbay does not add any service to your config by itself; the
35
+ config it creates on first run has no servers.
36
+
37
+ ## Data retention
38
+
39
+ Nothing is retained by Distronode, because nothing is sent to it. The files above stay on your
40
+ computer until you delete them; [Uninstall and rollback](README.md#uninstall-and-rollback) lists
41
+ them.
42
+
43
+ ## Contact
44
+
45
+ Questions about this policy: open an issue at
46
+ <https://github.com/distronode-corporation/mcp-patchbay/issues>, or email
47
+ **opensource@distronode.com**. Security reports: see [SECURITY.md](SECURITY.md).
package/README.md CHANGED
@@ -1,7 +1,406 @@
1
1
  # mcp-patchbay
2
2
 
3
- Version 0.0.0 only reserves the name on npm. `mcp-patchbay` ships here with its first release,
4
- 0.1.0.
3
+ [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/16485/badge)](https://www.bestpractices.dev/projects/16485)
5
4
 
6
- Until then, the source and instructions are on GitHub:
7
- https://github.com/distronode-corporation/mcp-patchbay
5
+ > **If you allow `mcp__patchbay` as a whole in your client's permissions, you approve every tool of every server it hosts.**
6
+ > Allow individual tools (`mcp__patchbay__<server>__<tool>`) instead. See [Policy and safety model](#policy-and-safety-model).
7
+
8
+ `mcp-patchbay` is an MCP server that hosts other MCP servers as child processes, and lets the AI
9
+ agent switch them on and off in the middle of a session.
10
+
11
+ - The agent sees five small tools: `servers`, `enable`, `disable`, `restart` and `info`.
12
+ - When the agent enables a server, the patchbay starts it, and its tools appear straight away as
13
+ `<server>__<tool>`. The patchbay sends `notifications/tools/list_changed`, so the client
14
+ refreshes its tool list.
15
+ - When a server is disabled, its tools disappear the same way.
16
+ - For servers you mark `confirm`, **a person**, not the agent, approves each enable, through an
17
+ MCP elicitation prompt in the client.
18
+
19
+ **Why.** Every connected MCP server costs context (its tool definitions) and a running process,
20
+ whether or not the session needs it. With the patchbay, you configure all your servers once, and
21
+ only the ones a task needs are running and visible.
22
+
23
+ **Requirements**
24
+
25
+ - Node.js 22 or later.
26
+ - An MCP client that honours `notifications/tools/list_changed` and supports elicitation (form
27
+ mode, and ideally URL mode for sign-ins). For Claude Code, that means **2.1.287 or later**.
28
+
29
+ Without elicitation support, `confirm` servers cannot be enabled. That is deliberate: the
30
+ patchbay fails closed.
31
+
32
+ Contents: [Quick start](#quick-start) · [Config reference](#config-reference) ·
33
+ [Naming contract](#naming-contract) · [Moving from Claude Code: `import` and
34
+ `rename-permissions`](#moving-from-claude-code) · [Policy and safety model](#policy-and-safety-model) ·
35
+ [Known limits](#known-limits) · [Comparison](#comparison) · [Uninstall and rollback](#uninstall-and-rollback) ·
36
+ [Privacy Policy](#privacy-policy)
37
+
38
+ ## Quick start
39
+
40
+ 1. Register the patchbay with Claude Code under the name **`patchbay`**. The naming contract and
41
+ the 128-character rule assume that name.
42
+
43
+ ```sh
44
+ claude mcp add --scope user patchbay -- npx -y mcp-patchbay@0.1.1
45
+ ```
46
+
47
+ That is all the first run needs. When `~/.config/mcp-patchbay/servers.json` does not exist,
48
+ the patchbay creates it with no servers (`{"version": 1, "servers": {}}`), says so in one
49
+ line on stderr, and serves its own tools. Nothing is switched on and the file holds no
50
+ secrets. On macOS and Linux the file is mode 600, and the directory, if the patchbay has to
51
+ create it, mode 700; an existing directory is kept as it is, provided nobody else can write
52
+ it. Windows has no such modes (see [Known limits](#known-limits)).
53
+
54
+ 2. Then add your connectors. This example hosts the public filesystem server
55
+ ([`@modelcontextprotocol/server-filesystem@2.2.0`](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem)).
56
+ Edit `~/.config/mcp-patchbay/servers.json` so it reads:
57
+
58
+ ```json
59
+ {
60
+ "version": 1,
61
+ "servers": {
62
+ "example-files": {
63
+ "description": "Read and write files in /path/to/project",
64
+ "policy": "confirm",
65
+ "command": "npx",
66
+ "args": ["-y", "@modelcontextprotocol/server-filesystem@2.2.0", "/path/to/project"]
67
+ }
68
+ }
69
+ }
70
+ ```
71
+
72
+ Keep the file private. The patchbay refuses to start if the file, or the directory it is in,
73
+ is group- or world-writable (`chmod 600 ~/.config/mcp-patchbay/servers.json` fixes the file).
74
+ Already have servers in Claude Code? [`import`](#import) writes this file from them.
75
+
76
+ 3. Check it. `doctor` validates the file and briefly starts every `allow` server. Add `--all` to
77
+ also start `confirm` servers like this one.
78
+
79
+ ```sh
80
+ npx -y mcp-patchbay@0.1.1 doctor --all
81
+ ```
82
+
83
+ 4. The config is read once, at startup, so reconnect the patchbay (`/mcp`, then `patchbay`). In
84
+ a session, ask the agent to "enable example-files". Claude Code shows the prompt
85
+ *"Allow the agent to turn on example-files (Read and write files in /path/to/project)?"*.
86
+ Once you approve, tools such as `mcp__patchbay__example-files__read_text_file` are available.
87
+
88
+ A longer, synthetic example is in [`examples/servers.json`](examples/servers.json).
89
+
90
+ `--config <path>` and `$MCP_PATCHBAY_CONFIG` stay strict: only the default path is ever created
91
+ for you, and a missing file anywhere else exits with code 78.
92
+
93
+ ### Claude Desktop
94
+
95
+ Each [release](https://github.com/distronode-corporation/mcp-patchbay/releases) carries
96
+ `mcp-patchbay-<version>.mcpb`, a desktop extension bundle with its dependencies included.
97
+ Double-click it, or use **Settings > Extensions > Advanced settings > Install Extension...** in
98
+ Claude Desktop. Its one setting is the config file, `~/.config/mcp-patchbay/servers.json` by
99
+ default, which the first run creates as above. Then add your connectors to it and turn the
100
+ extension off and on again in **Settings > Extensions** so it rereads the file. If a `confirm`
101
+ server cannot be enabled because the client shows no approval form, set
102
+ [`"confirmVia": "host"`](#confirmvia-elicitation-or-host).
103
+
104
+ ## Config reference
105
+
106
+ The config location is `--config <path>`, else `$MCP_PATCHBAY_CONFIG`, else
107
+ `~/.config/mcp-patchbay/servers.json`. The file is read **once**, at startup. To apply changes,
108
+ restart the patchbay (in Claude Code: `/mcp`, then reconnect `patchbay`).
109
+
110
+ ```json
111
+ {
112
+ "version": 1,
113
+ "confirmVia": "host",
114
+ "servers": {
115
+ "example-files": {
116
+ "description": "Files in /path/to/project",
117
+ "policy": "allow",
118
+ "command": "npx",
119
+ "args": ["-y", "@modelcontextprotocol/server-filesystem@2.2.0", "/path/to/project"],
120
+ "env": { "EXAMPLE_LOG_LEVEL": "info" },
121
+ "cwd": "/path/to",
122
+ "prefix": "files",
123
+ "timeoutMs": 0
124
+ },
125
+ "example-remote": {
126
+ "description": "A remote MCP server",
127
+ "policy": "confirm",
128
+ "url": "https://mcp.example.com/mcp",
129
+ "headers": { "X-Example-Tenant": "example" }
130
+ }
131
+ },
132
+ "autostart": {
133
+ "default": [],
134
+ "projects": { "/path/to/project": ["example-files"] }
135
+ },
136
+ "oauth": { "configDir": "~/.config/mcp-patchbay/oauth", "authTimeoutSeconds": 300 }
137
+ }
138
+ ```
139
+
140
+ Validation is strict: an unknown key anywhere is an error that names its path. Any config error
141
+ exits with code **78** and a message on stderr.
142
+
143
+ | Key | Meaning |
144
+ |---|---|
145
+ | `version` | Must be `1`. |
146
+ | `confirmVia` | How a person approves a `confirm` server. `"elicitation"` (the default): `enable` asks through the client's form elicitation. `"host"`: `enable` refuses, and the agent calls `enable_confirm`, which the host's own tool-permission prompt asks the person about. `import` writes `"host"`. See [confirmVia](#confirmvia-elicitation-or-host). |
147
+ | `servers.<name>` | The name uses 1–64 characters from `[A-Za-z0-9_-]`, with no `__` and no trailing `_`. |
148
+ | `description` | One line, at most 300 characters. The agent sees it in `servers` and in the patchbay's instructions. |
149
+ | `policy` | `allow` (the agent may enable it), `confirm` (a person must approve each enable; the default), or `deny` (it can never be enabled). |
150
+ | `command`, `args`, `env`, `cwd` | A stdio server. `cwd` must be absolute. The child gets `{...the patchbay's env, ...env}`, the same as Claude Code gives its own servers. |
151
+ | `url`, `headers` | A remote server, launched through the bundled [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) 0.15.2. The URL must be `https`, except for `localhost` and `127.0.0.1`. Header names use `[A-Za-z0-9_-]`. `env` is also allowed and is passed to mcp-remote. |
152
+ | `prefix` | A short alias used instead of the name in tool names. Names and prefixes must be unique, ignoring case. |
153
+ | `timeoutMs` | The cap on one tool call, in milliseconds. `0` (the default) means no cap. |
154
+ | `autostart.default` | Servers started at launch, with no confirmation. Not allowed for `deny` servers. |
155
+ | `autostart.projects` | Per-project lists, keyed by absolute directory. The key is matched against `CLAUDE_PROJECT_DIR`, or else the current directory. A matching list replaces `default`. |
156
+ | `oauth.configDir` | Where mcp-remote keeps OAuth state for `url` servers. It is created with mode 0700. |
157
+ | `oauth.authTimeoutSeconds` | How long a sign-in may take (1–86400, default 300). |
158
+
159
+ Each server has exactly one of `command` or `url`.
160
+
161
+ Autostart is your own config choice, so it counts as consent. The instructions of autostarted
162
+ servers are folded into the patchbay's own `instructions`, within 4,096 characters in total and
163
+ shared fairly between servers.
164
+
165
+ **Headers and secrets.** Header values are not put on mcp-remote's command line, where other
166
+ local users could read them. Instead the patchbay passes `--header Name:${MCP_PATCHBAY_HEADER_n}`
167
+ and puts the value in mcp-remote's environment, which expands it. A value that already contains
168
+ a `${VAR}` placeholder is passed as it is, and mcp-remote expands it from its own environment
169
+ (that is, the patchbay's env plus the entry's `env`).
170
+
171
+ **Other environment variables.**
172
+
173
+ - `MCP_PATCHBAY_DEBUG=1` copies every child's stderr (redacted) into the patchbay's own stderr log.
174
+ - `MCP_PATCHBAY_MCP_REMOTE_BIN` replaces the mcp-remote script. This is for tests, and you should
175
+ not normally set it.
176
+
177
+ ## The agent's tools
178
+
179
+ | Tool | Input | What it does |
180
+ |---|---|---|
181
+ | `servers` | — | Lists every configured server: name, description, policy, state (`off`, `starting`, `on`, `failed`, `waiting-for-sign-in`), its tool count when on, its redacted last error when failed, skipped tools, and whether it can be enabled (and if not, why). |
182
+ | `enable` | `{name}` | Starts the server, after asking a person if the policy is `confirm`. Returns its tool count, up to 10 sample tool names, and its instructions (cut to 2,000 characters). With `confirmVia: "host"` it refuses `confirm` servers and points to `enable_confirm`. |
183
+ | `enable_confirm` | `{name}` | Only with `confirmVia: "host"`. Turns on a `confirm` server; the host asks the person before it runs, and that yes is the approval. Refuses `allow` servers (use `enable`) and `deny` servers. Marked `destructiveHint: true`. |
184
+ | `disable` | `{name}` | Stops the server and removes its tools. Refused while that server has calls in flight; the refusal says how many. |
185
+ | `restart` | `{name}` | Stops and starts the server again. There is no new confirmation if it was already on. If it was off, this is the same as `enable`. |
186
+ | `info` | `{name}` | Description, policy, state, the last stderr lines (redacted), and its full instructions when on. |
187
+
188
+ Every one of these tools carries `_meta: {"anthropic/alwaysLoad": true}`.
189
+
190
+ ### confirmVia: elicitation or host
191
+
192
+ Some clients declare form elicitation but never show it: in the Claude Code VS Code extension
193
+ (2.1.319), the patchbay's question is answered `decline` with nothing shown to the person. The
194
+ patchbay fails closed, so `confirm` servers cannot be turned on there with the default
195
+ `"elicitation"`. With `"host"`, the approval is the host's own permission prompt for
196
+ `mcp__patchbay__enable_confirm`, which those clients do show, and which the model cannot answer.
197
+
198
+ That prompt only appears if nothing approves the tool in advance. **Do not allow
199
+ `mcp__patchbay__enable_confirm`, `mcp__patchbay__*`, `mcp__patchbay` or `*`**, and do not run in
200
+ a mode that skips prompts (Claude Code's `bypassPermissions`, or `dontAsk` with the tool
201
+ allowed): there, every `enable_confirm` is approved automatically. `mcp-patchbay doctor
202
+ --project <dir>` reads your Claude Code settings and warns about such rules. There is no generic
203
+ "call any tool" or "exec" tool, and there never will be.
204
+
205
+ ## Naming contract
206
+
207
+ This mapping is a public contract. Permission rules and hooks can depend on it.
208
+
209
+ ```
210
+ exposed name = <prefix or server name> "__" <tool name with every char outside [A-Za-z0-9_-] replaced by "_">
211
+ client name = "mcp__patchbay__" + exposed name (when registered as "patchbay")
212
+ ```
213
+
214
+ - A server name or prefix never contains `__` and never ends with `_`. So the **first `__`**
215
+ after `mcp__patchbay__` always separates the server from the tool, even when the tool name
216
+ contains `__` or begins with `_`.
217
+ - For example, `mcp__patchbay__files___hidden` is server `files` and tool `_hidden`.
218
+ - If the client name would be longer than 128 characters, the tool is **skipped** and reported
219
+ in `servers` and `info`. The server part is never shortened.
220
+ - If two tools of one server sanitize to the same name, the first one listed wins and the others
221
+ are skipped and reported.
222
+ - These tools are also skipped: tools whose definition is invalid, and tools that require
223
+ task-augmented calls.
224
+ - Everything else passes through unchanged: `title`, `description`, `inputSchema`,
225
+ `outputSchema`, `annotations`, `_meta` and any other field.
226
+
227
+ ## Moving from Claude Code
228
+
229
+ ### `import`
230
+
231
+ ```sh
232
+ mcp-patchbay import --from ~/.claude.json --project /path/to/project --out ~/.config/mcp-patchbay/servers.json
233
+ ```
234
+
235
+ `import` only reads your Claude Code config; it never changes it.
236
+
237
+ - **Sources.** It reads the top-level `mcpServers`, plus `projects[<dir>].mcpServers` when
238
+ `--project` is given.
239
+ - **Mapping.** `http`/`sse` entries become `url` entries, with their headers. stdio entries
240
+ become `command` entries.
241
+ - **Policy.** Servers in that project's `disabledMcpServers` become `confirm`; everything else
242
+ becomes `allow`.
243
+ - **Autostart.** With `--project`, `autostart.projects[<dir>]` lists the servers *not* disabled
244
+ there. `autostart.default` is left empty.
245
+ - **Skips.** It skips, and reports, servers it cannot host: `claude.ai …` connectors,
246
+ `plugin:…` servers, `claude-in-chrome`, `ws` transports, names that are invalid here, and the
247
+ patchbay itself.
248
+ - **Output.** It backs up an existing output file to `<out>.bak-<timestamp>` first. It writes the
249
+ file at mode 0600, and never prints env or header values.
250
+
251
+ Afterwards, remove the imported servers from Claude Code (`claude mcp remove <name>`), or they run
252
+ twice: once directly and once through the patchbay.
253
+
254
+ Claude Code expands `${VAR}` in its own server configs. The patchbay does not do this for
255
+ `command`, `args` or `env`; mcp-remote does it for header values. Check imported entries that
256
+ relied on expansion.
257
+
258
+ ### `rename-permissions`
259
+
260
+ ```sh
261
+ mcp-patchbay rename-permissions ~/.claude/settings.json # dry run: prints a diff
262
+ mcp-patchbay rename-permissions ~/.claude/settings.json --write # backs up, then writes
263
+ ```
264
+
265
+ For each rule in `permissions.allow`, `ask` and `deny`, it **adds** a patchbay twin, and keeps
266
+ every existing rule:
267
+
268
+ - `mcp__X__tool` adds `mcp__patchbay__<seg>__tool`.
269
+ - `mcp__X` (a whole server) adds `mcp__patchbay__<seg>__*`.
270
+
271
+ `<seg>` is server `X`'s `prefix` if it has one, else `X`. The prefixes come from the patchbay
272
+ config: `--config <servers.json>`, else the same file the patchbay would load
273
+ (`$MCP_PATCHBAY_CONFIG`, else `~/.config/mcp-patchbay/servers.json`). If there is no config
274
+ file, it warns that prefixes are unknown and maps names as they are.
275
+
276
+ It skips rules it cannot proxy: `mcp__claude-in-chrome__*`, `mcp__plugin_*`, `mcp__claude_ai_*`,
277
+ rules with parentheses, and existing patchbay rules. It never adds a rule that would match
278
+ `mcp__patchbay__enable_confirm`.
279
+
280
+ ### `doctor`
281
+
282
+ ```sh
283
+ mcp-patchbay doctor --project /path/to/project --no-start
284
+ ```
285
+
286
+ It validates the config and prints `confirmVia`. It then reads `~/.claude/settings.json` and
287
+ `settings.local.json`, plus the project's `.claude/settings.json` and `settings.local.json`
288
+ with `--project`, and names every allow rule that would approve `enable_confirm` without asking
289
+ (the exact name, `mcp__patchbay`, and wildcards such as `mcp__patchbay__*` and `*`), and any
290
+ `defaultMode: "bypassPermissions"`. With `confirmVia: "host"` these are warnings and the exit
291
+ code is 1. Without `--no-start` it then starts each `allow` server briefly (`--all`: `confirm`
292
+ ones too) and reports its tool count.
293
+
294
+ ## Policy and safety model
295
+
296
+ The full threat model is in [SECURITY-MODEL.md](SECURITY-MODEL.md). In short:
297
+
298
+ - **The config is trusted. The agent is not.** The agent can only pick a configured name. It
299
+ cannot add servers or change commands, and it cannot run anything that is not in the file.
300
+ This is why the patchbay refuses a config that others can write to.
301
+ - **`confirm` means a person said yes**, for this session's enable. With `confirmVia:
302
+ "elicitation"` that is the client's elicitation UI, and only an accept with `allow: true`
303
+ counts; a client without elicitation support cannot enable `confirm` servers at all. With
304
+ `"host"` it is the host's permission prompt for `enable_confirm`, so it is only as strong as
305
+ your permission rules (see [confirmVia](#confirmvia-elicitation-or-host)).
306
+ - **`confirm` does not vet individual calls.** After a server is on, its tools are governed by
307
+ your client's permission rules, exactly like directly connected servers. **Do not allow
308
+ `mcp__patchbay` as a whole**: that approves every tool of every hosted server, including
309
+ servers you have not yet thought about.
310
+ - **Children are isolated from each other.** One server's `env` never reaches another child. A
311
+ crashing child marks only itself `failed`. Children are never restarted automatically.
312
+ - **Redaction.** Errors, logs and the `servers`/`info` output are redacted: URL query strings,
313
+ bearer tokens, `sk-…`, `ghp_…`, JWT-shaped strings, long hex and base64 runs, and the entry's own
314
+ env, args, header values and url (path segments, query values) all become `[redacted]`.
315
+ Exact values are only matched from 6 characters up, so shorter ones are not hidden.
316
+ - **Tool results are not redacted or sanitised.** They are parsed with the SDK's
317
+ `CallToolResultSchema`, like any SDK client parses them. Unknown keys inside content blocks are
318
+ dropped, and a content block of an unknown `type` makes the call fail. Everything else passes
319
+ through as the server sent it.
320
+ - **A remote server's url is on mcp-remote's command line**, so other local users can see it
321
+ with `ps`. Do not use a url that carries a key if other people share the machine; use a header.
322
+ - **Elicitations from hosted servers** are forwarded to you, prefixed with `[<server>]`.
323
+ Sampling requests from hosted servers are refused.
324
+ - **Process hygiene.** On POSIX each child leads its own process group. Every group gets SIGTERM
325
+ when the patchbay gets SIGINT or SIGTERM or its stdin closes, within milliseconds. Pidfiles let
326
+ the next start clean up after a crash.
327
+
328
+ ## Known limits
329
+
330
+ - **Tools only.** v1 proxies tools. Resources, prompts, completions, logging and tasks of hosted
331
+ servers are not available through the patchbay.
332
+ - **The patchbay must be registered as `patchbay`.** The 128-character rule and
333
+ `rename-permissions` assume the client name prefix `mcp__patchbay__`.
334
+ - **OAuth goes through mcp-remote.**
335
+ - Remote servers sign in through mcp-remote's flow. The patchbay shows you the sign-in link
336
+ as a URL elicitation, or as a form with the link if the client lacks URL mode. mcp-remote
337
+ also tries to open a browser.
338
+ - Tokens are stored by mcp-remote under `oauth.configDir`. They are **not** the tokens Claude
339
+ Code holds for its own direct connections, so you sign in once more per server.
340
+ - Claude Code's `/mcp` → "Authenticate" / re-auth **does not cover** servers behind the
341
+ patchbay. Claude Code only sees the patchbay, which is a local stdio server. To re-authenticate
342
+ a hosted server, `restart` it. To sign out, `disable` it and remove its files from
343
+ `oauth.configDir/mcp-remote-v1/`.
344
+ - Sign-in detection depends on the exact stderr text of mcp-remote 0.15.2.
345
+ - **Windows** is untested by the author. The CI matrix covers it, and these limits are known:
346
+ - Config permission checks are skipped.
347
+ - Children are not detached. Trees are killed with `taskkill /T /F /PID`, which runs as a
348
+ separate process, so a child may outlive the patchbay by a moment.
349
+ - When a child exits on its own, processes it started are not cleaned up: Windows has no
350
+ process group to address, and killing the exited pid could hit a process that reused it.
351
+ - `.cmd` shims such as `npx` cannot be spawned directly. Use
352
+ `"command": "cmd", "args": ["/c", "npx", ...]`.
353
+ - Command-line checks for reaping use PowerShell (`Get-CimInstance`).
354
+ - The signal tests are skipped.
355
+ - **Config changes need a restart** of the patchbay.
356
+
357
+ ## Comparison
358
+
359
+ | | mcp-patchbay | Docker Dynamic MCP | Magg | Claude Code subagent `mcpServers` |
360
+ |---|---|---|---|---|
361
+ | Runtime | Node.js, child processes | Docker MCP Gateway; needs Docker Desktop | Python | Built into Claude Code |
362
+ | License | Apache-2.0 | — | AGPL-3.0 | — |
363
+ | Who decides what runs | Your config. The agent enables configured names, and a person confirms `confirm` ones | The agent can find and add catalogue servers at run time | The agent can manage the server list through Magg's tools | Fixed per subagent definition |
364
+ | Generic call/exec tool | None, by design | Yes (`mcp-exec`) | — | None |
365
+ | Tools appear | In the main session, via `tools/list_changed` | In the session, via the gateway | In the session, via the aggregator | Only inside that subagent |
366
+
367
+ Docker's approach suits container-isolated catalogue servers. Subagent-scoped `mcpServers` need no
368
+ extra process, when a fixed set per subagent is enough.
369
+
370
+ ## Uninstall and rollback
371
+
372
+ 1. `claude mcp remove patchbay` (add `--scope user` if you added it that way).
373
+ 2. Re-add any servers you had moved, from your backup or with `claude mcp add …`. `import` never
374
+ changed `~/.claude.json`.
375
+ 3. Restore permission rules from the backup that `rename-permissions --write` made
376
+ (`settings.json.bak-<timestamp>`). Or keep them: the extra `mcp__patchbay__…` rules are
377
+ harmless without the patchbay.
378
+ 4. Remove the patchbay's files:
379
+ `rm -rf ~/.config/mcp-patchbay` (this includes `oauth/` with mcp-remote tokens) and
380
+ `${XDG_RUNTIME_DIR:-/tmp}/mcp-patchbay-$(id -u)` (pidfiles).
381
+ 5. If you installed it globally: `npm uninstall -g mcp-patchbay`.
382
+
383
+ ## Privacy Policy
384
+
385
+ mcp-patchbay collects no data and sends nothing to Distronode or anyone else: no telemetry, no
386
+ analytics, no update check. It stores only your config, sign-in tokens for remote servers you
387
+ configure (in `oauth.configDir`), pidfiles, and the `.bak` copies that `import` and
388
+ `rename-permissions --write` make, all on your computer, until you delete them. The servers you configure are separate programs with their own privacy policies.
389
+ The full policy, with the contact, is [PRIVACY.md](PRIVACY.md).
390
+
391
+ ## Development
392
+
393
+ ```sh
394
+ npm ci
395
+ npm test # node:test, about 20 s
396
+ python3 -m unittest discover -s examples/write-gate -v
397
+ ```
398
+
399
+ See [CONTRIBUTING.md](CONTRIBUTING.md), [SPEC.md](SPEC.md) (the protocol and lifecycle contract)
400
+ and [DECISIONS.md](DECISIONS.md).
401
+
402
+ Issues and source: <https://github.com/distronode-corporation/mcp-patchbay>.
403
+ Security reports: see [SECURITY.md](SECURITY.md).
404
+ This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md).
405
+
406
+ Licensed under the Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).