mcp-patchbay 0.0.0 → 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.
@@ -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.
@@ -0,0 +1,54 @@
1
+ {
2
+ "version": 1,
3
+ "servers": {
4
+ "example-files": {
5
+ "description": "Read and write files in /path/to/project",
6
+ "policy": "allow",
7
+ "command": "npx",
8
+ "args": ["-y", "@modelcontextprotocol/server-filesystem@2.2.0", "/path/to/project"],
9
+ "prefix": "files"
10
+ },
11
+ "example-everything": {
12
+ "description": "The MCP reference test server, for trying things out",
13
+ "policy": "confirm",
14
+ "command": "npx",
15
+ "args": ["-y", "@modelcontextprotocol/server-everything@2.2.1"],
16
+ "timeoutMs": 60000
17
+ },
18
+ "example-remote": {
19
+ "description": "A remote MCP server that needs a sign-in",
20
+ "policy": "confirm",
21
+ "url": "https://mcp.example.com/mcp"
22
+ },
23
+ "example-remote-key": {
24
+ "description": "A remote MCP server with an API key header",
25
+ "policy": "confirm",
26
+ "url": "https://mcp.example.com/mcp",
27
+ "headers": { "Authorization": "Bearer ${EXAMPLE_API_KEY}" },
28
+ "env": { "EXAMPLE_API_KEY": "replace-me" }
29
+ },
30
+ "example-local-tool": {
31
+ "description": "A local stdio server with its own env and working directory",
32
+ "policy": "confirm",
33
+ "command": "/path/to/bin/example-mcp-server",
34
+ "args": ["--stdio"],
35
+ "env": { "EXAMPLE_LOG_LEVEL": "info" },
36
+ "cwd": "/path/to/project"
37
+ },
38
+ "example-danger": {
39
+ "description": "Never available to the agent",
40
+ "policy": "deny",
41
+ "command": "/path/to/bin/example-admin-server"
42
+ }
43
+ },
44
+ "autostart": {
45
+ "default": [],
46
+ "projects": {
47
+ "/path/to/project": ["example-files"]
48
+ }
49
+ },
50
+ "oauth": {
51
+ "configDir": "~/.config/mcp-patchbay/oauth",
52
+ "authTimeoutSeconds": 300
53
+ }
54
+ }
package/package.json CHANGED
@@ -1,23 +1,49 @@
1
1
  {
2
2
  "name": "mcp-patchbay",
3
- "version": "0.0.0",
4
- "description": "Reserves the name for mcp-patchbay, an MCP server that hosts other MCP servers and switches them on and off during a session. The first release, 0.1.0, ships here.",
5
- "license": "Apache-2.0",
6
- "author": "Distronode <opensource@distronode.com>",
7
- "homepage": "https://github.com/distronode-corporation/mcp-patchbay#readme",
3
+ "version": "0.1.0",
4
+ "description": "An MCP server that hosts other MCP servers as child processes and lets the agent switch them on and off mid-session, with a person confirming risky ones.",
5
+ "keywords": [
6
+ "mcp",
7
+ "model-context-protocol",
8
+ "claude-code",
9
+ "proxy",
10
+ "mcp-server",
11
+ "tools",
12
+ "elicitation"
13
+ ],
8
14
  "repository": {
9
15
  "type": "git",
10
16
  "url": "git+https://github.com/distronode-corporation/mcp-patchbay.git"
11
17
  },
12
- "bugs": {
13
- "url": "https://github.com/distronode-corporation/mcp-patchbay/issues"
14
- },
18
+ "license": "Apache-2.0",
19
+ "author": "Distronode Corporation",
20
+ "type": "module",
15
21
  "bin": {
16
- "mcp-patchbay": "bin/mcp-patchbay.js"
22
+ "mcp-patchbay": "src/cli.js"
23
+ },
24
+ "exports": {
25
+ ".": "./src/server.js",
26
+ "./package.json": "./package.json"
17
27
  },
18
28
  "files": [
19
- "bin/mcp-patchbay.js",
29
+ "src/",
20
30
  "README.md",
21
- "LICENSE"
22
- ]
31
+ "SECURITY-MODEL.md",
32
+ "SECURITY.md",
33
+ "CHANGELOG.md",
34
+ "LICENSE",
35
+ "NOTICE",
36
+ "examples/servers.json"
37
+ ],
38
+ "engines": {
39
+ "node": ">=22"
40
+ },
41
+ "scripts": {
42
+ "test": "node --test --test-reporter=spec \"test/**/*.test.js\""
43
+ },
44
+ "dependencies": {
45
+ "@modelcontextprotocol/sdk": "1.32.2",
46
+ "mcp-remote": "0.15.2",
47
+ "zod": "4.6.7"
48
+ }
23
49
  }