mcp-patchbay 0.0.0-stage → 0.1.0
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 +103 -0
- package/LICENSE +201 -0
- package/NOTICE +8 -0
- package/README.md +376 -2
- package/SECURITY-MODEL.md +229 -0
- package/SECURITY.md +26 -0
- package/examples/servers.json +54 -0
- package/package.json +47 -4
- package/src/children.js +521 -0
- package/src/cli.js +155 -0
- package/src/config.js +465 -0
- package/src/doctor.js +124 -0
- package/src/fsutil.js +55 -0
- package/src/import.js +168 -0
- package/src/instructions.js +88 -0
- package/src/log.js +22 -0
- package/src/naming.js +96 -0
- package/src/permissions.js +72 -0
- package/src/process.js +367 -0
- package/src/redact.js +132 -0
- package/src/rename-permissions.js +158 -0
- package/src/server.js +864 -0
- package/src/version.js +4 -0
package/README.md
CHANGED
|
@@ -1,3 +1,377 @@
|
|
|
1
|
-
#
|
|
1
|
+
# mcp-patchbay
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.bestpractices.dev/projects/16485)
|
|
4
|
+
|
|
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
|
+
|
|
37
|
+
## Quick start
|
|
38
|
+
|
|
39
|
+
This example hosts the public filesystem server
|
|
40
|
+
([`@modelcontextprotocol/server-filesystem@2.2.0`](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem)).
|
|
41
|
+
|
|
42
|
+
1. Write a config file and make it private. The patchbay refuses to start if the file, or the
|
|
43
|
+
directory it is in, is group- or world-writable.
|
|
44
|
+
|
|
45
|
+
```sh
|
|
46
|
+
mkdir -p -m 700 ~/.config/mcp-patchbay
|
|
47
|
+
cat > ~/.config/mcp-patchbay/servers.json <<'EOF'
|
|
48
|
+
{
|
|
49
|
+
"version": 1,
|
|
50
|
+
"servers": {
|
|
51
|
+
"example-files": {
|
|
52
|
+
"description": "Read and write files in /path/to/project",
|
|
53
|
+
"policy": "confirm",
|
|
54
|
+
"command": "npx",
|
|
55
|
+
"args": ["-y", "@modelcontextprotocol/server-filesystem@2.2.0", "/path/to/project"]
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
EOF
|
|
60
|
+
chmod 600 ~/.config/mcp-patchbay/servers.json
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
2. Check it. `doctor` validates the file and briefly starts every `allow` server. Add `--all` to
|
|
64
|
+
also start `confirm` servers like this one.
|
|
65
|
+
|
|
66
|
+
```sh
|
|
67
|
+
npx -y mcp-patchbay@0.1.0 doctor --all
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
3. Register the patchbay with Claude Code under the name **`patchbay`**. The naming contract and
|
|
71
|
+
the 128-character rule assume that name.
|
|
72
|
+
|
|
73
|
+
```sh
|
|
74
|
+
claude mcp add --scope user patchbay -- npx -y mcp-patchbay@0.1.0
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
4. In a session, ask the agent to "enable example-files". Claude Code shows the prompt
|
|
78
|
+
*"Allow the agent to turn on example-files (Read and write files in /path/to/project)?"*.
|
|
79
|
+
Once you approve, tools such as `mcp__patchbay__example-files__read_text_file` are available.
|
|
80
|
+
|
|
81
|
+
A longer, synthetic example is in [`examples/servers.json`](examples/servers.json).
|
|
82
|
+
|
|
83
|
+
## Config reference
|
|
84
|
+
|
|
85
|
+
The config location is `--config <path>`, else `$MCP_PATCHBAY_CONFIG`, else
|
|
86
|
+
`~/.config/mcp-patchbay/servers.json`. The file is read **once**, at startup. To apply changes,
|
|
87
|
+
restart the patchbay (in Claude Code: `/mcp`, then reconnect `patchbay`).
|
|
88
|
+
|
|
89
|
+
```json
|
|
90
|
+
{
|
|
91
|
+
"version": 1,
|
|
92
|
+
"confirmVia": "host",
|
|
93
|
+
"servers": {
|
|
94
|
+
"example-files": {
|
|
95
|
+
"description": "Files in /path/to/project",
|
|
96
|
+
"policy": "allow",
|
|
97
|
+
"command": "npx",
|
|
98
|
+
"args": ["-y", "@modelcontextprotocol/server-filesystem@2.2.0", "/path/to/project"],
|
|
99
|
+
"env": { "EXAMPLE_LOG_LEVEL": "info" },
|
|
100
|
+
"cwd": "/path/to",
|
|
101
|
+
"prefix": "files",
|
|
102
|
+
"timeoutMs": 0
|
|
103
|
+
},
|
|
104
|
+
"example-remote": {
|
|
105
|
+
"description": "A remote MCP server",
|
|
106
|
+
"policy": "confirm",
|
|
107
|
+
"url": "https://mcp.example.com/mcp",
|
|
108
|
+
"headers": { "X-Example-Tenant": "example" }
|
|
109
|
+
}
|
|
110
|
+
},
|
|
111
|
+
"autostart": {
|
|
112
|
+
"default": [],
|
|
113
|
+
"projects": { "/path/to/project": ["example-files"] }
|
|
114
|
+
},
|
|
115
|
+
"oauth": { "configDir": "~/.config/mcp-patchbay/oauth", "authTimeoutSeconds": 300 }
|
|
116
|
+
}
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Validation is strict: an unknown key anywhere is an error that names its path. Any config error
|
|
120
|
+
exits with code **78** and a message on stderr.
|
|
121
|
+
|
|
122
|
+
| Key | Meaning |
|
|
123
|
+
|---|---|
|
|
124
|
+
| `version` | Must be `1`. |
|
|
125
|
+
| `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). |
|
|
126
|
+
| `servers.<name>` | The name uses 1–64 characters from `[A-Za-z0-9_-]`, with no `__` and no trailing `_`. |
|
|
127
|
+
| `description` | One line, at most 300 characters. The agent sees it in `servers` and in the patchbay's instructions. |
|
|
128
|
+
| `policy` | `allow` (the agent may enable it), `confirm` (a person must approve each enable; the default), or `deny` (it can never be enabled). |
|
|
129
|
+
| `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. |
|
|
130
|
+
| `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. |
|
|
131
|
+
| `prefix` | A short alias used instead of the name in tool names. Names and prefixes must be unique, ignoring case. |
|
|
132
|
+
| `timeoutMs` | The cap on one tool call, in milliseconds. `0` (the default) means no cap. |
|
|
133
|
+
| `autostart.default` | Servers started at launch, with no confirmation. Not allowed for `deny` servers. |
|
|
134
|
+
| `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`. |
|
|
135
|
+
| `oauth.configDir` | Where mcp-remote keeps OAuth state for `url` servers. It is created with mode 0700. |
|
|
136
|
+
| `oauth.authTimeoutSeconds` | How long a sign-in may take (1–86400, default 300). |
|
|
137
|
+
|
|
138
|
+
Each server has exactly one of `command` or `url`.
|
|
139
|
+
|
|
140
|
+
Autostart is your own config choice, so it counts as consent. The instructions of autostarted
|
|
141
|
+
servers are folded into the patchbay's own `instructions`, within 4,096 characters in total and
|
|
142
|
+
shared fairly between servers.
|
|
143
|
+
|
|
144
|
+
**Headers and secrets.** Header values are not put on mcp-remote's command line, where other
|
|
145
|
+
local users could read them. Instead the patchbay passes `--header Name:${MCP_PATCHBAY_HEADER_n}`
|
|
146
|
+
and puts the value in mcp-remote's environment, which expands it. A value that already contains
|
|
147
|
+
a `${VAR}` placeholder is passed as it is, and mcp-remote expands it from its own environment
|
|
148
|
+
(that is, the patchbay's env plus the entry's `env`).
|
|
149
|
+
|
|
150
|
+
**Other environment variables.**
|
|
151
|
+
|
|
152
|
+
- `MCP_PATCHBAY_DEBUG=1` copies every child's stderr (redacted) into the patchbay's own stderr log.
|
|
153
|
+
- `MCP_PATCHBAY_MCP_REMOTE_BIN` replaces the mcp-remote script. This is for tests, and you should
|
|
154
|
+
not normally set it.
|
|
155
|
+
|
|
156
|
+
## The agent's tools
|
|
157
|
+
|
|
158
|
+
| Tool | Input | What it does |
|
|
159
|
+
|---|---|---|
|
|
160
|
+
| `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). |
|
|
161
|
+
| `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`. |
|
|
162
|
+
| `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`. |
|
|
163
|
+
| `disable` | `{name}` | Stops the server and removes its tools. Refused while that server has calls in flight; the refusal says how many. |
|
|
164
|
+
| `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`. |
|
|
165
|
+
| `info` | `{name}` | Description, policy, state, the last stderr lines (redacted), and its full instructions when on. |
|
|
166
|
+
|
|
167
|
+
Every one of these tools carries `_meta: {"anthropic/alwaysLoad": true}`.
|
|
168
|
+
|
|
169
|
+
### confirmVia: elicitation or host
|
|
170
|
+
|
|
171
|
+
Some clients declare form elicitation but never show it: in the Claude Code VS Code extension
|
|
172
|
+
(2.1.319), the patchbay's question is answered `decline` with nothing shown to the person. The
|
|
173
|
+
patchbay fails closed, so `confirm` servers cannot be turned on there with the default
|
|
174
|
+
`"elicitation"`. With `"host"`, the approval is the host's own permission prompt for
|
|
175
|
+
`mcp__patchbay__enable_confirm`, which those clients do show, and which the model cannot answer.
|
|
176
|
+
|
|
177
|
+
That prompt only appears if nothing approves the tool in advance. **Do not allow
|
|
178
|
+
`mcp__patchbay__enable_confirm`, `mcp__patchbay__*`, `mcp__patchbay` or `*`**, and do not run in
|
|
179
|
+
a mode that skips prompts (Claude Code's `bypassPermissions`, or `dontAsk` with the tool
|
|
180
|
+
allowed): there, every `enable_confirm` is approved automatically. `mcp-patchbay doctor
|
|
181
|
+
--project <dir>` reads your Claude Code settings and warns about such rules. There is no generic
|
|
182
|
+
"call any tool" or "exec" tool, and there never will be.
|
|
183
|
+
|
|
184
|
+
## Naming contract
|
|
185
|
+
|
|
186
|
+
This mapping is a public contract. Permission rules and hooks can depend on it.
|
|
187
|
+
|
|
188
|
+
```
|
|
189
|
+
exposed name = <prefix or server name> "__" <tool name with every char outside [A-Za-z0-9_-] replaced by "_">
|
|
190
|
+
client name = "mcp__patchbay__" + exposed name (when registered as "patchbay")
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
- A server name or prefix never contains `__` and never ends with `_`. So the **first `__`**
|
|
194
|
+
after `mcp__patchbay__` always separates the server from the tool, even when the tool name
|
|
195
|
+
contains `__` or begins with `_`.
|
|
196
|
+
- For example, `mcp__patchbay__files___hidden` is server `files` and tool `_hidden`.
|
|
197
|
+
- If the client name would be longer than 128 characters, the tool is **skipped** and reported
|
|
198
|
+
in `servers` and `info`. The server part is never shortened.
|
|
199
|
+
- If two tools of one server sanitize to the same name, the first one listed wins and the others
|
|
200
|
+
are skipped and reported.
|
|
201
|
+
- These tools are also skipped: tools whose definition is invalid, and tools that require
|
|
202
|
+
task-augmented calls.
|
|
203
|
+
- Everything else passes through unchanged: `title`, `description`, `inputSchema`,
|
|
204
|
+
`outputSchema`, `annotations`, `_meta` and any other field.
|
|
205
|
+
|
|
206
|
+
## Moving from Claude Code
|
|
207
|
+
|
|
208
|
+
### `import`
|
|
209
|
+
|
|
210
|
+
```sh
|
|
211
|
+
mcp-patchbay import --from ~/.claude.json --project /path/to/project --out ~/.config/mcp-patchbay/servers.json
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
`import` only reads your Claude Code config; it never changes it.
|
|
215
|
+
|
|
216
|
+
- **Sources.** It reads the top-level `mcpServers`, plus `projects[<dir>].mcpServers` when
|
|
217
|
+
`--project` is given.
|
|
218
|
+
- **Mapping.** `http`/`sse` entries become `url` entries, with their headers. stdio entries
|
|
219
|
+
become `command` entries.
|
|
220
|
+
- **Policy.** Servers in that project's `disabledMcpServers` become `confirm`; everything else
|
|
221
|
+
becomes `allow`.
|
|
222
|
+
- **Autostart.** With `--project`, `autostart.projects[<dir>]` lists the servers *not* disabled
|
|
223
|
+
there. `autostart.default` is left empty.
|
|
224
|
+
- **Skips.** It skips, and reports, servers it cannot host: `claude.ai …` connectors,
|
|
225
|
+
`plugin:…` servers, `claude-in-chrome`, `ws` transports, names that are invalid here, and the
|
|
226
|
+
patchbay itself.
|
|
227
|
+
- **Output.** It backs up an existing output file to `<out>.bak-<timestamp>` first. It writes the
|
|
228
|
+
file at mode 0600, and never prints env or header values.
|
|
229
|
+
|
|
230
|
+
Afterwards, remove the imported servers from Claude Code (`claude mcp remove <name>`), or they run
|
|
231
|
+
twice: once directly and once through the patchbay.
|
|
232
|
+
|
|
233
|
+
Claude Code expands `${VAR}` in its own server configs. The patchbay does not do this for
|
|
234
|
+
`command`, `args` or `env`; mcp-remote does it for header values. Check imported entries that
|
|
235
|
+
relied on expansion.
|
|
236
|
+
|
|
237
|
+
### `rename-permissions`
|
|
238
|
+
|
|
239
|
+
```sh
|
|
240
|
+
mcp-patchbay rename-permissions ~/.claude/settings.json # dry run: prints a diff
|
|
241
|
+
mcp-patchbay rename-permissions ~/.claude/settings.json --write # backs up, then writes
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
For each rule in `permissions.allow`, `ask` and `deny`, it **adds** a patchbay twin, and keeps
|
|
245
|
+
every existing rule:
|
|
246
|
+
|
|
247
|
+
- `mcp__X__tool` adds `mcp__patchbay__<seg>__tool`.
|
|
248
|
+
- `mcp__X` (a whole server) adds `mcp__patchbay__<seg>__*`.
|
|
249
|
+
|
|
250
|
+
`<seg>` is server `X`'s `prefix` if it has one, else `X`. The prefixes come from the patchbay
|
|
251
|
+
config: `--config <servers.json>`, else the same file the patchbay would load
|
|
252
|
+
(`$MCP_PATCHBAY_CONFIG`, else `~/.config/mcp-patchbay/servers.json`). If there is no config
|
|
253
|
+
file, it warns that prefixes are unknown and maps names as they are.
|
|
254
|
+
|
|
255
|
+
It skips rules it cannot proxy: `mcp__claude-in-chrome__*`, `mcp__plugin_*`, `mcp__claude_ai_*`,
|
|
256
|
+
rules with parentheses, and existing patchbay rules. It never adds a rule that would match
|
|
257
|
+
`mcp__patchbay__enable_confirm`.
|
|
258
|
+
|
|
259
|
+
### `doctor`
|
|
260
|
+
|
|
261
|
+
```sh
|
|
262
|
+
mcp-patchbay doctor --project /path/to/project --no-start
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
It validates the config and prints `confirmVia`. It then reads `~/.claude/settings.json` and
|
|
266
|
+
`settings.local.json`, plus the project's `.claude/settings.json` and `settings.local.json`
|
|
267
|
+
with `--project`, and names every allow rule that would approve `enable_confirm` without asking
|
|
268
|
+
(the exact name, `mcp__patchbay`, and wildcards such as `mcp__patchbay__*` and `*`), and any
|
|
269
|
+
`defaultMode: "bypassPermissions"`. With `confirmVia: "host"` these are warnings and the exit
|
|
270
|
+
code is 1. Without `--no-start` it then starts each `allow` server briefly (`--all`: `confirm`
|
|
271
|
+
ones too) and reports its tool count.
|
|
272
|
+
|
|
273
|
+
## Policy and safety model
|
|
274
|
+
|
|
275
|
+
The full threat model is in [SECURITY-MODEL.md](SECURITY-MODEL.md). In short:
|
|
276
|
+
|
|
277
|
+
- **The config is trusted. The agent is not.** The agent can only pick a configured name. It
|
|
278
|
+
cannot add servers or change commands, and it cannot run anything that is not in the file.
|
|
279
|
+
This is why the patchbay refuses a config that others can write to.
|
|
280
|
+
- **`confirm` means a person said yes**, for this session's enable. With `confirmVia:
|
|
281
|
+
"elicitation"` that is the client's elicitation UI, and only an accept with `allow: true`
|
|
282
|
+
counts; a client without elicitation support cannot enable `confirm` servers at all. With
|
|
283
|
+
`"host"` it is the host's permission prompt for `enable_confirm`, so it is only as strong as
|
|
284
|
+
your permission rules (see [confirmVia](#confirmvia-elicitation-or-host)).
|
|
285
|
+
- **`confirm` does not vet individual calls.** After a server is on, its tools are governed by
|
|
286
|
+
your client's permission rules, exactly like directly connected servers. **Do not allow
|
|
287
|
+
`mcp__patchbay` as a whole**: that approves every tool of every hosted server, including
|
|
288
|
+
servers you have not yet thought about.
|
|
289
|
+
- **Children are isolated from each other.** One server's `env` never reaches another child. A
|
|
290
|
+
crashing child marks only itself `failed`. Children are never restarted automatically.
|
|
291
|
+
- **Redaction.** Errors, logs and the `servers`/`info` output are redacted: URL query strings,
|
|
292
|
+
bearer tokens, `sk-…`, `ghp_…`, JWT-shaped strings, long hex and base64 runs, and the entry's own
|
|
293
|
+
env, args, header values and url (path segments, query values) all become `[redacted]`.
|
|
294
|
+
Exact values are only matched from 6 characters up, so shorter ones are not hidden.
|
|
295
|
+
- **Tool results are not redacted or sanitised.** They are parsed with the SDK's
|
|
296
|
+
`CallToolResultSchema`, like any SDK client parses them. Unknown keys inside content blocks are
|
|
297
|
+
dropped, and a content block of an unknown `type` makes the call fail. Everything else passes
|
|
298
|
+
through as the server sent it.
|
|
299
|
+
- **A remote server's url is on mcp-remote's command line**, so other local users can see it
|
|
300
|
+
with `ps`. Do not use a url that carries a key if other people share the machine; use a header.
|
|
301
|
+
- **Elicitations from hosted servers** are forwarded to you, prefixed with `[<server>]`.
|
|
302
|
+
Sampling requests from hosted servers are refused.
|
|
303
|
+
- **Process hygiene.** On POSIX each child leads its own process group. Every group gets SIGTERM
|
|
304
|
+
when the patchbay gets SIGINT or SIGTERM or its stdin closes, within milliseconds. Pidfiles let
|
|
305
|
+
the next start clean up after a crash.
|
|
306
|
+
|
|
307
|
+
## Known limits
|
|
308
|
+
|
|
309
|
+
- **Tools only.** v1 proxies tools. Resources, prompts, completions, logging and tasks of hosted
|
|
310
|
+
servers are not available through the patchbay.
|
|
311
|
+
- **The patchbay must be registered as `patchbay`.** The 128-character rule and
|
|
312
|
+
`rename-permissions` assume the client name prefix `mcp__patchbay__`.
|
|
313
|
+
- **OAuth goes through mcp-remote.**
|
|
314
|
+
- Remote servers sign in through mcp-remote's flow. The patchbay shows you the sign-in link
|
|
315
|
+
as a URL elicitation, or as a form with the link if the client lacks URL mode. mcp-remote
|
|
316
|
+
also tries to open a browser.
|
|
317
|
+
- Tokens are stored by mcp-remote under `oauth.configDir`. They are **not** the tokens Claude
|
|
318
|
+
Code holds for its own direct connections, so you sign in once more per server.
|
|
319
|
+
- Claude Code's `/mcp` → "Authenticate" / re-auth **does not cover** servers behind the
|
|
320
|
+
patchbay. Claude Code only sees the patchbay, which is a local stdio server. To re-authenticate
|
|
321
|
+
a hosted server, `restart` it. To sign out, `disable` it and remove its files from
|
|
322
|
+
`oauth.configDir/mcp-remote-v1/`.
|
|
323
|
+
- Sign-in detection depends on the exact stderr text of mcp-remote 0.15.2.
|
|
324
|
+
- **Windows** is untested by the author. The CI matrix covers it, and these limits are known:
|
|
325
|
+
- Config permission checks are skipped.
|
|
326
|
+
- Children are not detached. Trees are killed with `taskkill /T /F /PID`, which runs as a
|
|
327
|
+
separate process, so a child may outlive the patchbay by a moment.
|
|
328
|
+
- When a child exits on its own, processes it started are not cleaned up: Windows has no
|
|
329
|
+
process group to address, and killing the exited pid could hit a process that reused it.
|
|
330
|
+
- `.cmd` shims such as `npx` cannot be spawned directly. Use
|
|
331
|
+
`"command": "cmd", "args": ["/c", "npx", ...]`.
|
|
332
|
+
- Command-line checks for reaping use PowerShell (`Get-CimInstance`).
|
|
333
|
+
- The signal tests are skipped.
|
|
334
|
+
- **Config changes need a restart** of the patchbay.
|
|
335
|
+
|
|
336
|
+
## Comparison
|
|
337
|
+
|
|
338
|
+
| | mcp-patchbay | Docker Dynamic MCP | Magg | Claude Code subagent `mcpServers` |
|
|
339
|
+
|---|---|---|---|---|
|
|
340
|
+
| Runtime | Node.js, child processes | Docker MCP Gateway; needs Docker Desktop | Python | Built into Claude Code |
|
|
341
|
+
| License | Apache-2.0 | — | AGPL-3.0 | — |
|
|
342
|
+
| 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 |
|
|
343
|
+
| Generic call/exec tool | None, by design | Yes (`mcp-exec`) | — | None |
|
|
344
|
+
| 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 |
|
|
345
|
+
|
|
346
|
+
Docker's approach suits container-isolated catalogue servers. Subagent-scoped `mcpServers` need no
|
|
347
|
+
extra process, when a fixed set per subagent is enough.
|
|
348
|
+
|
|
349
|
+
## Uninstall and rollback
|
|
350
|
+
|
|
351
|
+
1. `claude mcp remove patchbay` (add `--scope user` if you added it that way).
|
|
352
|
+
2. Re-add any servers you had moved, from your backup or with `claude mcp add …`. `import` never
|
|
353
|
+
changed `~/.claude.json`.
|
|
354
|
+
3. Restore permission rules from the backup that `rename-permissions --write` made
|
|
355
|
+
(`settings.json.bak-<timestamp>`). Or keep them: the extra `mcp__patchbay__…` rules are
|
|
356
|
+
harmless without the patchbay.
|
|
357
|
+
4. Remove the patchbay's files:
|
|
358
|
+
`rm -rf ~/.config/mcp-patchbay` (this includes `oauth/` with mcp-remote tokens) and
|
|
359
|
+
`${XDG_RUNTIME_DIR:-/tmp}/mcp-patchbay-$(id -u)` (pidfiles).
|
|
360
|
+
5. If you installed it globally: `npm uninstall -g mcp-patchbay`.
|
|
361
|
+
|
|
362
|
+
## Development
|
|
363
|
+
|
|
364
|
+
```sh
|
|
365
|
+
npm ci
|
|
366
|
+
npm test # node:test, about 20 s
|
|
367
|
+
python3 -m unittest discover -s examples/write-gate -v
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md), [SPEC.md](SPEC.md) (the protocol and lifecycle contract)
|
|
371
|
+
and [DECISIONS.md](DECISIONS.md).
|
|
372
|
+
|
|
373
|
+
Issues and source: <https://github.com/distronode-corporation/mcp-patchbay>.
|
|
374
|
+
Security reports: see [SECURITY.md](SECURITY.md).
|
|
375
|
+
This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md).
|
|
376
|
+
|
|
377
|
+
Licensed under the Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
|
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
# Security model
|
|
2
|
+
|
|
3
|
+
`mcp-patchbay` brokers process execution on behalf of an AI agent. This document says what it
|
|
4
|
+
protects, what it trusts, and where its guarantees stop. For the protocol details, see
|
|
5
|
+
[SPEC.md](SPEC.md).
|
|
6
|
+
|
|
7
|
+
## Assets
|
|
8
|
+
|
|
9
|
+
- **Your machine.** Every hosted server runs as you, with your environment.
|
|
10
|
+
- **Credentials.** These live in server `env`, in `headers`, in mcp-remote's OAuth tokens under
|
|
11
|
+
`oauth.configDir`, and in whatever the servers themselves can reach.
|
|
12
|
+
- **Your consent.** The meaning of "a person approved this".
|
|
13
|
+
|
|
14
|
+
## Trust boundaries
|
|
15
|
+
|
|
16
|
+
| Party | Trusted? | Why |
|
|
17
|
+
|---|---|---|
|
|
18
|
+
| The config file | **Yes** | It is your decision about what may run. Because of that, the patchbay refuses (exit 78) a file that is group- or world-writable, or owned by someone other than you or root, or that sits in a directory that is group- or world-writable or owned by someone else (POSIX). A symlinked config is accepted only if its target, and the target's directory, pass the same checks. The file is opened once, and checked and read through that one descriptor. |
|
|
19
|
+
| The person at the client | Yes | They answer elicitations, and with `confirmVia: "host"` the host's permission prompt for `enable_confirm`. |
|
|
20
|
+
| The MCP client (for example Claude Code) | Yes, for transport and UI | The patchbay relies on it to show elicitations faithfully and to enforce per-tool permission rules. With `confirmVia: "host"` the `confirm` guarantee rests on its permission prompt. |
|
|
21
|
+
| The agent (the model) | **No** | It may be wrong, or steered by prompt injection from any content it reads. |
|
|
22
|
+
| Hosted servers (children) | **No** | They are third-party code. Their output, tool descriptions, instructions and requests may be hostile. |
|
|
23
|
+
| Remote MCP endpoints | No | They are reached through mcp-remote. |
|
|
24
|
+
|
|
25
|
+
## What the agent can and cannot do
|
|
26
|
+
|
|
27
|
+
The agent can:
|
|
28
|
+
|
|
29
|
+
- list the configured servers;
|
|
30
|
+
- enable an `allow` server;
|
|
31
|
+
- *ask* to enable a `confirm` server;
|
|
32
|
+
- disable, restart or inspect a configured server;
|
|
33
|
+
- call the tools of servers that are on, subject to the client's own permission rules.
|
|
34
|
+
|
|
35
|
+
The agent cannot:
|
|
36
|
+
|
|
37
|
+
- add a server, or change a command, its arguments, env, URL or headers. The config is read once
|
|
38
|
+
at startup, and no tool writes it.
|
|
39
|
+
- run an arbitrary command. There is no generic `call` or `exec` tool. A hosted server's tools
|
|
40
|
+
are reachable only under their own names.
|
|
41
|
+
- enable a `deny` server, through any path (`enable`, `restart` or autostart). `deny` servers in
|
|
42
|
+
`autostart` are rejected at load time.
|
|
43
|
+
- enable a `confirm` server without a person, unless the host's permission settings approve
|
|
44
|
+
`enable_confirm` for it (`confirmVia: "host"` only; see below).
|
|
45
|
+
|
|
46
|
+
## What `confirm` guarantees
|
|
47
|
+
|
|
48
|
+
`confirmVia` decides who asks the person. With `"elicitation"` (the default) the patchbay asks,
|
|
49
|
+
as described first below. With `"host"` the host asks, as described after that.
|
|
50
|
+
|
|
51
|
+
- **A person answers.** Before spawning a `confirm` server, the patchbay sends an
|
|
52
|
+
`elicitation/create` request in form mode to the client, with the message
|
|
53
|
+
`Allow the agent to turn on <name> (<description>)?` and one boolean field. The text comes from
|
|
54
|
+
your config, never from the agent.
|
|
55
|
+
- **It fails closed.** Only `action: "accept"` with `allow: true` proceeds. Decline, cancel, a
|
|
56
|
+
malformed answer, a timeout, a transport error, or a client that did not declare elicitation
|
|
57
|
+
support all mean "no".
|
|
58
|
+
- **It covers every path to a spawn.** `restart` of a server that is off goes through the same
|
|
59
|
+
check. Concurrent enables share one pending question rather than racing past it.
|
|
60
|
+
- **Autostart is the documented exception.** Listing a server in `autostart` is your own consent,
|
|
61
|
+
given in the trusted config.
|
|
62
|
+
|
|
63
|
+
### With `confirmVia: "host"`
|
|
64
|
+
|
|
65
|
+
- **The host's permission prompt is the approval.** `enable` and `restart` refuse to start a
|
|
66
|
+
`confirm` server and the patchbay never elicits. The only way to start one (autostart aside)
|
|
67
|
+
is the `enable_confirm` tool, and the patchbay treats every call that reaches it as approved.
|
|
68
|
+
So the guarantee rests entirely on the host asking the person before it runs that tool. The
|
|
69
|
+
model cannot answer that prompt; the patchbay cannot see whether it was shown.
|
|
70
|
+
- **`enable_confirm` only starts `confirm` servers.** It refuses `allow` and `deny` servers, so a
|
|
71
|
+
prompt for it always means a `confirm` server is about to start, and the prompt shows the
|
|
72
|
+
server name the agent chose. It is annotated `destructiveHint: true`, so a host that
|
|
73
|
+
auto-approves read-only or non-destructive tools still asks.
|
|
74
|
+
- **Anything that skips the prompt approves automatically.** In Claude Code that is:
|
|
75
|
+
- the `bypassPermissions` mode;
|
|
76
|
+
- the `dontAsk` mode with the tool allowed;
|
|
77
|
+
- an allow rule that matches `mcp__patchbay__enable_confirm`: the exact name,
|
|
78
|
+
`mcp__patchbay__*`, `mcp__patchbay`, or `*`.
|
|
79
|
+
|
|
80
|
+
In any of these, the agent can turn on every `confirm` server without a person, exactly as if
|
|
81
|
+
they were `allow`. `mcp-patchbay doctor` reads your user settings, and a project's with
|
|
82
|
+
`--project <dir>`, and warns (exit 1) about such rules and about `bypassPermissions`. It
|
|
83
|
+
cannot see modes chosen on the command line or in a session. `rename-permissions` never writes
|
|
84
|
+
such a rule.
|
|
85
|
+
- **Fails closed where it can.** Everything that decides a refusal (`deny`, unknown names, the
|
|
86
|
+
`enable` refusal) is in the patchbay. With `confirmVia: "elicitation"` the tool is not listed,
|
|
87
|
+
and a call to it is an unknown-tool error.
|
|
88
|
+
|
|
89
|
+
## What `confirm` does not guarantee
|
|
90
|
+
|
|
91
|
+
- **It does not vet calls.** Once a server is on, each of its tools is governed only by the
|
|
92
|
+
client's permission rules. If you allow `mcp__patchbay` as a whole, you approve every tool of
|
|
93
|
+
every server the patchbay hosts, including ones you have not yet looked at. Allow individual
|
|
94
|
+
`mcp__patchbay__<server>__<tool>` rules instead (`rename-permissions` helps).
|
|
95
|
+
- **It cannot stop the agent from asking.** A prompt-injected agent may ask you repeatedly to
|
|
96
|
+
enable a server. The prompt always names the real server and your own description.
|
|
97
|
+
- **It lasts for the session.** Approval covers that server until it is disabled, crashes, or the
|
|
98
|
+
patchbay exits. A later `restart` of a server that is on does not ask again. A `disable` that
|
|
99
|
+
arrives while that restart is stopping the old child cancels it, so the server stays off. A
|
|
100
|
+
crash marks the server `failed` as soon as the exit is observed, so a restart after that asks
|
|
101
|
+
again.
|
|
102
|
+
- **It trusts the client's UI.** The guarantee is only as strong as the client's elicitation UI
|
|
103
|
+
(or, with `confirmVia: "host"`, its permission prompt and your permission rules) and the
|
|
104
|
+
person's attention.
|
|
105
|
+
|
|
106
|
+
## Prompt injection
|
|
107
|
+
|
|
108
|
+
Tool descriptions and server instructions from children pass through to the agent unchanged
|
|
109
|
+
(apart from the tool's `name`). Tool results pass through **unsanitised**, but not byte for byte.
|
|
110
|
+
They are parsed with the SDK's `CallToolResultSchema` (SDK 1.32.2), as any SDK client would parse
|
|
111
|
+
them:
|
|
112
|
+
|
|
113
|
+
- unknown top-level keys and `_meta` are kept;
|
|
114
|
+
- unknown keys inside a content block, inside its `annotations` and inside an embedded
|
|
115
|
+
`resource` are dropped;
|
|
116
|
+
- a content block of an unknown `type` makes the whole call fail with a JSON-RPC error instead
|
|
117
|
+
of a result;
|
|
118
|
+
- a missing `content` becomes `[]`.
|
|
119
|
+
|
|
120
|
+
None of this is a security filter. The patchbay does not, and cannot, sanitise content
|
|
121
|
+
semantically. Treat a hosted server exactly as you would treat it if it were connected directly.
|
|
122
|
+
|
|
123
|
+
Two specific mitigations:
|
|
124
|
+
|
|
125
|
+
- **Elicitations from children are attributed.** They are forwarded to you with the message
|
|
126
|
+
prefixed `[<server>] `, so a child cannot pass its request off as the patchbay's own
|
|
127
|
+
confirmation. The answer goes only to that child.
|
|
128
|
+
- **Only mcp-remote can trigger a sign-in prompt, and only while it starts.** The sign-in line
|
|
129
|
+
detector runs only for `url` entries and for commands that are mcp-remote (including
|
|
130
|
+
`npx mcp-remote`), and only while the server is `starting` or `waiting-for-sign-in`. The
|
|
131
|
+
prompt is labelled `[<server>] `. So another child cannot show a patchbay "Sign in" prompt with
|
|
132
|
+
a link of its choosing, and an mcp-remote child that is already on cannot raise one later. A
|
|
133
|
+
url-mode elicitation still carries a URL chosen by the remote endpoint's sign-in flow; check
|
|
134
|
+
the host before you sign in.
|
|
135
|
+
- **Sampling is refused.** `sampling/createMessage` from children is refused, so a hosted server
|
|
136
|
+
cannot drive your model through the patchbay.
|
|
137
|
+
|
|
138
|
+
## Child environment
|
|
139
|
+
|
|
140
|
+
- **What a child gets.** A stdio child runs with `{...the patchbay's env, ...that entry's env}`,
|
|
141
|
+
the same as Claude Code. Variables such as `PATH`, `HOME`, `DISPLAY` and
|
|
142
|
+
`CLAUDE_PROJECT_DIR` therefore reach it. That means **every child sees every secret in the
|
|
143
|
+
patchbay's own environment**. Keep secrets in the specific entry's `env`, not in the
|
|
144
|
+
environment the patchbay is launched with.
|
|
145
|
+
- **Isolation between entries.** One entry's `env` is never given to another child.
|
|
146
|
+
- **Remote children.** mcp-remote additionally gets `MCP_REMOTE_CONFIG_DIR`, plus the header
|
|
147
|
+
values as `MCP_PATCHBAY_HEADER_<n>` variables. Header values are kept **out of argv**, because
|
|
148
|
+
argv is readable by other local users through `ps` or `/proc`. The environment of a process is
|
|
149
|
+
readable only by the same user (and root).
|
|
150
|
+
- **The url is visible in the process list.** mcp-remote 0.15.2 accepts the server url only as
|
|
151
|
+
a command-line argument, so the `url` of a remote entry *is* on argv. Any local user can read
|
|
152
|
+
it with `ps`. If your endpoint carries its key in the url (`https://host/s/<token>/mcp` or
|
|
153
|
+
`?key=…`), that key is exposed to the other users of the machine. Prefer an endpoint that
|
|
154
|
+
takes the key in a header. The patchbay's own output redacts the url (see Redaction).
|
|
155
|
+
- **Process groups.** Children are detached into their own process group on POSIX. When the
|
|
156
|
+
patchbay stops, each group is sent SIGTERM synchronously. A detached helper sends SIGKILL to
|
|
157
|
+
any group still there 500 ms later. The pidfiles stay until the exit is seen, so a child that
|
|
158
|
+
survives both is reaped (SIGTERM, then SIGKILL) at the next start.
|
|
159
|
+
|
|
160
|
+
## OAuth tokens
|
|
161
|
+
|
|
162
|
+
- **Where they live.** Remote servers sign in through mcp-remote 0.15.2. Its tokens are stored
|
|
163
|
+
under `oauth.configDir` (default `~/.config/mcp-patchbay/oauth`), which the patchbay creates at
|
|
164
|
+
mode 0700.
|
|
165
|
+
- **The sign-in URL.** It is sent **unredacted** to the person, in a URL-mode elicitation, or in a
|
|
166
|
+
form-mode message when URL mode is unavailable, because the sign-in needs it. The patchbay
|
|
167
|
+
itself never writes it to its logs, errors, or `servers` and `info` output. The patchbay's
|
|
168
|
+
log line says only that a sign-in is pending. mcp-remote's own stderr lines, which contain
|
|
169
|
+
it, are kept in the redacted stderr ring buffer (`info.stderrTail`), so query parameters such
|
|
170
|
+
as `state` and `code_challenge` show as `?[redacted]`. With `MCP_PATCHBAY_DEBUG=1` those
|
|
171
|
+
redacted lines are also copied to the patchbay's stderr.
|
|
172
|
+
- **What mcp-remote does.** mcp-remote itself tries to open a browser. It also listens on a local
|
|
173
|
+
callback port during sign-in.
|
|
174
|
+
|
|
175
|
+
## Redaction
|
|
176
|
+
|
|
177
|
+
Everything the patchbay itself produces about a child is redacted before it leaves the process:
|
|
178
|
+
stderr ring buffers, logs, `lastError`, `servers` and `info` output, doctor output, and error
|
|
179
|
+
messages relayed from children.
|
|
180
|
+
|
|
181
|
+
- **Patterns.** URL query strings and userinfo, `Bearer`/`Basic` credentials, `key=value` for
|
|
182
|
+
token-like keys, `sk-…`, `ghp_…` and similar prefixes, `github_pat_…`, `xox…-`, AWS key ids,
|
|
183
|
+
JWT-shaped strings, hex runs of 32 or more characters, and mixed-case base64 runs of 40 or more.
|
|
184
|
+
- **Exact values.** The entry's own env values, args and header values, and for remote entries
|
|
185
|
+
the url (whole, each path segment, each query value, any userinfo), are replaced by
|
|
186
|
+
`[redacted]`, but **only those 6 characters or longer**. The real guarantee is this: an env
|
|
187
|
+
value, arg, header value or url part of 6+ characters never appears verbatim in the patchbay's
|
|
188
|
+
errors, logs, `servers`/`info`/`enable` output or doctor output. Shorter values (a 5-character
|
|
189
|
+
PIN, a short path segment such as `/mcp`) are not scrubbed. They pass through when a child
|
|
190
|
+
prints them, unless a pattern above happens to match. Encoded forms (base64, URL-encoded
|
|
191
|
+
except in the url itself, split across lines) are not matched either.
|
|
192
|
+
- **Not redacted:** tool results, tool lists and child instructions. They are the hosted server's
|
|
193
|
+
own content, and changing them would break servers. A server that prints its own secret in a
|
|
194
|
+
tool result discloses it, exactly as it would when connected directly.
|
|
195
|
+
|
|
196
|
+
Redaction is pattern-based. It reduces accidental disclosure; it is not a guarantee against a
|
|
197
|
+
child deliberately leaking data.
|
|
198
|
+
|
|
199
|
+
## Process and file hygiene
|
|
200
|
+
|
|
201
|
+
- Logs go to stderr only. stdout carries only MCP messages.
|
|
202
|
+
- Pidfiles live in `${XDG_RUNTIME_DIR or tmp}/mcp-patchbay-<uid>/`, at mode 0700. The patchbay
|
|
203
|
+
refuses a directory it does not own. Pidfiles hold a SHA-256 of the child's command line, not
|
|
204
|
+
the command line itself.
|
|
205
|
+
- At startup, leftovers are killed only if their owning patchbay is gone **and** the pid still
|
|
206
|
+
runs the recorded command line **and** it still leads its own process group **and**, on
|
|
207
|
+
Linux, it has the recorded start time. Only the process group is signalled, never a bare pid.
|
|
208
|
+
This avoids killing a process that reused the pid. On other systems a reused pid that runs
|
|
209
|
+
the identical command line as its own group leader would still match.
|
|
210
|
+
- `import` writes its output at 0600, and backs up any file it replaces.
|
|
211
|
+
- `rename-permissions` keeps the file's mode, and backs it up before writing.
|
|
212
|
+
- Neither prints env or header values.
|
|
213
|
+
|
|
214
|
+
## Known gaps
|
|
215
|
+
|
|
216
|
+
- On Windows, there are no config-permission checks, children are not process-group leaders,
|
|
217
|
+
and tree kills are asynchronous (`taskkill`).
|
|
218
|
+
- A hosted server can still do anything its own code does, with your privileges. The patchbay
|
|
219
|
+
limits *which* servers run, not *what they do*.
|
|
220
|
+
- Configuration mistakes are yours. A `policy: allow` server that can write files can be enabled
|
|
221
|
+
by the agent without asking.
|
|
222
|
+
|
|
223
|
+
## Reporting a vulnerability
|
|
224
|
+
|
|
225
|
+
Please use **GitHub private vulnerability reporting** on the repository: the **Security** tab,
|
|
226
|
+
then **Report a vulnerability**. Do not open a public issue for security problems.
|
|
227
|
+
|
|
228
|
+
Include the version, your OS, a minimal config (with synthetic names and values), and steps to
|
|
229
|
+
reproduce.
|
package/SECURITY.md
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Security policy
|
|
2
|
+
|
|
3
|
+
## Supported versions
|
|
4
|
+
|
|
5
|
+
| Version | Supported |
|
|
6
|
+
|---|---|
|
|
7
|
+
| 0.1.x | Yes |
|
|
8
|
+
|
|
9
|
+
## Reporting a vulnerability
|
|
10
|
+
|
|
11
|
+
Please report privately, not in a public issue, discussion or pull request.
|
|
12
|
+
|
|
13
|
+
- **Preferred:** GitHub's private vulnerability reporting. Open the repository's
|
|
14
|
+
**Security** tab and choose **Report a vulnerability**, or go straight to
|
|
15
|
+
<https://github.com/distronode-corporation/mcp-patchbay/security/advisories/new>.
|
|
16
|
+
- **Fallback:** email **opensource@distronode.com** if you cannot use GitHub.
|
|
17
|
+
|
|
18
|
+
Include what you did, what happened, and what you expected. A proof of concept is welcome
|
|
19
|
+
but not required. Never include a real token or credential from a hosted server's
|
|
20
|
+
environment; if one is part of the problem, say where it appeared, not what it was.
|
|
21
|
+
|
|
22
|
+
Expect an acknowledgement within a few working days. This is a small project with no paid
|
|
23
|
+
bug bounty; what you get is credit in the changelog entry for the fix, if you want it.
|
|
24
|
+
|
|
25
|
+
The threat model is described in [SECURITY-MODEL.md](SECURITY-MODEL.md): what is trusted, what
|
|
26
|
+
`confirm` does and does not guarantee, and how redaction works.
|