ungated-global: system project whose servers ride every project, pre-gate
Some checks failed
CI/CD / lint (pull_request) Successful in 1m12s
CI/CD / test (pull_request) Successful in 1m26s
CI/CD / typecheck (pull_request) Successful in 3m22s
CI/CD / smoke (pull_request) Failing after 1m57s
CI/CD / build (pull_request) Successful in 5m15s
CI/CD / publish (pull_request) Has been skipped
Some checks failed
CI/CD / lint (pull_request) Successful in 1m12s
CI/CD / test (pull_request) Successful in 1m26s
CI/CD / typecheck (pull_request) Successful in 3m22s
CI/CD / smoke (pull_request) Failing after 1m57s
CI/CD / build (pull_request) Successful in 5m15s
CI/CD / publish (pull_request) Has been skipped
New seed-once system project `ungated-global`: every server attached to it is merged into every project's MCP endpoint in front of the gate (listed and callable before begin_session), and its project prompt is prepended to every project's instructions. - mcpd: bootstrapUngatedGlobal seeds the project once-ever (marker key `ungatedGlobalSeeded` in mcpctl-system-settings), with default server `calcmcp` (patched CalcMCP fork, mysources.co.uk/michal/calcmcp:1.1.0) and a "never do math yourself, always use calcmcp" prompt. Deletions are durable: `mcpctl delete server calcmcp -p ungated-global` stays deleted. - mcpd: GET /projects/:id/servers appends global servers flagged `ungatedGlobal: true` (direct attachment wins, no self-merge); GET /projects/:id/instructions prepends the global prompt and lists the global servers. - mcplocal: discovery surfaces the flagged names; the gate plugin exempts them — gated tools/list returns begin_session + exempt tools, calls to them pass through without ungating, and initialize instructions list them under "Available immediately (no begin_session required)". - templates/calcmcp.yaml so a deleted default can be re-created by hand. - docs/ungated-global.md. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
56
docs/ungated-global.md
Normal file
56
docs/ungated-global.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# ungated-global: servers under every project, before the gate
|
||||
|
||||
`ungated-global` is a system project with one special property: **every server
|
||||
attached to it is exposed under every project's MCP endpoint, in front of the
|
||||
gate** — its tools are listed and callable before `begin_session`, and the
|
||||
project's `prompt` is prepended to every project's instructions.
|
||||
|
||||
Fresh mcpd instances seed it **once** with the default `calcmcp` server
|
||||
(scientific calculator, patched fork of
|
||||
[thinkitpossible/CalcMCP](https://github.com/thinkitpossible/CalcMCP) at
|
||||
<https://mysources.co.uk/michal/CalcMCP>) and a prompt telling models to never
|
||||
do math themselves and always use calcmcp.
|
||||
|
||||
## Semantics
|
||||
|
||||
- **Seed-once, not resurrect**: the first successful mcpd startup writes
|
||||
`ungatedGlobalSeeded: true` into the `mcpctl-system-settings` secret. After
|
||||
that, nothing is ever re-created — deletions are durable:
|
||||
- `mcpctl delete server calcmcp -p ungated-global` detaches the default
|
||||
server (delete the server resource itself to also stop its instance);
|
||||
- deleting the whole `ungated-global` project turns the feature off.
|
||||
To re-create the default by hand there is a `calcmcp` template:
|
||||
`mcpctl create server calcmcp --from-template calcmcp`, then attach it to
|
||||
a (re-created) `ungated-global` project.
|
||||
- **Merging** happens in mcpd:
|
||||
- `GET /api/v1/projects/:id/servers` appends ungated-global's servers,
|
||||
flagged `ungatedGlobal: true`. A server attached to the project directly
|
||||
wins (no duplicate, no flag).
|
||||
- `GET /api/v1/projects/:id/instructions` prepends ungated-global's
|
||||
`prompt` and appends its servers to the server list.
|
||||
- **Gate exemption** happens in mcplocal: discovery passes the flagged names
|
||||
into the gate plugin (`ungatedServers`); while a session is gated,
|
||||
`tools/list` returns `begin_session` **plus** the exempt servers' tools, and
|
||||
calls to them pass through without triggering the gate intercept or
|
||||
ungating the session. Initialize instructions list them under
|
||||
"Available immediately (no begin_session required)".
|
||||
|
||||
## Editing the prompt
|
||||
|
||||
The pre-gate directive lives on the project itself:
|
||||
|
||||
```bash
|
||||
mcpctl patch project ungated-global --prompt "…"
|
||||
```
|
||||
|
||||
Caveat: clients that ignore MCP initialize instructions (e.g. LibreChat uses
|
||||
config-literal serverInstructions) never see project prompts — for those, the
|
||||
carrier is the tool/server descriptions themselves, which is why calcmcp's
|
||||
server description also says "use it for every mathematical calculation".
|
||||
|
||||
## Security note
|
||||
|
||||
Anything attached to ungated-global is reachable from **every** project by
|
||||
**every** token that can reach any project endpoint. Only attach servers that
|
||||
are safe in every context: no secrets, no egress, no side effects. calcmcp is
|
||||
pure compute (no env, no network).
|
||||
Reference in New Issue
Block a user