@plurnk/plurnk-mcp 1.7.0 → 1.8.0

package/.env.defaults

@@ -5,6 +5,15 @@
 PLURNK_MCP_CONNECT_TIMEOUT=30000
 PLURNK_MCP_REQUEST_TIMEOUT=86400000
 
+# Configured servers are available to clients. Only this exact JSON-array
+# subset connects and becomes model-visible by default; workspaces may override it.
+PLURNK_MCP_ENABLED=[]
+
+# Turn 0 surveys enabled tool FAMILIES (one row per server, summary = its
+# one-liner). Servers named here also expand their complete tool tree into
+# the turn-0 survey:
+# PLURNK_MCP_EXPANDED=[]
+
 # Each configured server contributes its enabled `[server] (tool)` rows and server:// resources.
 #
 # Streamable HTTP:
@@ -19,3 +28,19 @@ PLURNK_MCP_REQUEST_TIMEOUT=86400000
 # PLURNK_MCP_atlas_ARGS=["/absolute/path/to/atlas-server.mjs"]
 # PLURNK_MCP_atlas_CWD=/absolute/working/directory
 # PLURNK_MCP_atlas_ENV={"TOKEN":"${ATLAS_TOKEN}"}
+#
+# npx (installed-on-demand executables) — the documented Brave Search fixture,
+# demo-tier only; credentials stay one ${NAME} reference in the operator env:
+# PLURNK_MCP_BRAVE=npx
+# PLURNK_MCP_BRAVE_ARGS=["-y","@brave/brave-search-mcp-server@2.1.0"]
+# PLURNK_MCP_BRAVE_ENV={"BRAVE_API_KEY":"${BRAVE_API_KEY}"}
+# PLURNK_MCP_BRAVE_TOOLS=["brave_web_search","brave_news_search"]
+# PLURNK_MCP_BRAVE_READ=["brave_web_search","brave_news_search"]
+#
+# _SUMMARY companions are fallbacks only — declare one when the server's own
+# summary metadata is missing, confusing, or garbage. The family row can carry
+# its flagship invocation form directly:
+# PLURNK_MCP_BRAVE_SUMMARY=EXEC [brave] (brave_web_search) <!-- Retrieve web results -->
+# PLURNK_MCP_BRAVE_BRAVE_WEB_SEARCH_SUMMARY=General web search.
+#
+# Then list it above to make it model-visible, e.g. PLURNK_MCP_ENABLED=["brave"].

package/README.md

@@ -5,16 +5,21 @@ module for [Plurnk](https://github.com/plurnk/plurnk-service). It projects
 trusted MCP servers through Plurnk's existing executor, resource, proposal,
 entry, Problem, lifecycle, and AG-UI contracts.
 
-The module accepts only protocol revision `2026-07-28`. A legacy endpoint is
-rejected with a `protocol-revision-unsupported` Problem that names the required
-revision and `server/discover`; Plurnk does not negotiate a downgrade.
-
-## Attach a server
-
-Service environment variables provide optional defaults for every workspace.
-Users can also attach, replace, reconnect, or detach a server in one workspace
-without restarting the daemon. An existing AG-UI connection sends the ordinary
-management-action form under `forwardedProps.plurnk.action`:
+The module's own wire authority is protocol revision `2026-07-28`
+({§mcp-authority}). Connection setup negotiates-and-degrades: a server that
+offers the pinned revision and `server/discover` gets the complete extension
+wire; a server the SDK negotiated below the pin is an ordinary MCP peer that
+serves its standard surface at its own negotiated revision. Plurnk does not
+downgrade its own extension wire, but it does not reject an older supported
+revision.
+
+## Manage workspace servers
+
+Service environment variables provide available servers for every workspace;
+`PLURNK_MCP_ENABLED` selects the exact cold-enabled subset. Users can add,
+enable, disable, or remove workspace servers without restarting the daemon. An
+existing AG-UI connection sends the ordinary management-action form under
+`forwardedProps.plurnk.action`:
 
 ```json
 {
@@ -22,11 +27,10 @@ management-action form under `forwardedProps.plurnk.action`:
     "plurnk": {
       "workspace": "example",
       "action": {
-        "kind": "workspace.mcp.attach",
-        "server": {
-          "name": "project",
-          "transport": "stdio",
-          "command": "/opt/mcp/current-server",
+        "kind": "workspace.mcp.add",
+        "alias": "project",
+        "target": "/opt/mcp/current-server",
+        "options": {
           "args": ["--stdio"],
           "env": { "PROJECT_TOKEN": "${PROJECT_TOKEN}" },
           "tools": ["issue_read", "issue_write"],
@@ -46,20 +50,69 @@ Available workspace actions are:
 
 | Action | Parameters |
 |---|---|
-| `workspace.mcp.list` | none |
-| `workspace.mcp.attach` | `server` definition |
-| `workspace.mcp.replace` | `server` definition with the existing name |
-| `workspace.mcp.detach` | `name` |
-| `workspace.mcp.reconnect` | `name` |
-| `workspace.mcp.oauth.complete` | `name`, complete `callbackUrl` |
+| `workspace.mcp.list` | optional client `overlay` |
+| `workspace.mcp.add` | `alias`, `target`; optional `options` |
+| `workspace.mcp.enable` | `alias`; optional client `overlay` and explicit `options` |
+| `workspace.mcp.disable` | `alias` |
+| `workspace.mcp.remove` | `alias` |
+| `workspace.mcp.oauth.complete` | `alias`, complete `callbackUrl` |
 | `workspace.mcp.complete` | `server`, completion `ref` and `argument`; optional `context` |
 
 The owning [specification](./SPEC.md) defines the complete action and server
 definition contracts.
 
+Client and project configuration can specialize a cold service definition
+without copying it or restarting the daemon. For example, a service catalog
+can provide the executable while one project's `.env` supplies its identity:
+
+```text
+# $XDG_CONFIG_HOME/plurnk/.env, read by the service
+PLURNK_MCP_GITEA=/usr/local/bin/possumtech-gitea-mcp
+PLURNK_MCP_ENABLED=[]
+
+# <project>/.env, read by the client
+PLURNK_MCP_GITEA_ARGS=["plurnk_pk"]
+```
+
+The client carries its raw declarations while listing and enabling. Listing is
+inert. `/mcp enable gitea` (or `plurnk mcp enable gitea` in a named workspace)
+composes service, durable workspace, client, and optional command-file fields
+in that order, prepares the connection, then persists the complete unexpanded
+workspace specialization. Arrays and maps replace rather than append or merge.
+
+## Demo fixtures
+
+Web discovery is an ordinary MCP attachment ({§web-search-retrieval}); the demo
+tier exercises search through a documented fixture rather than an owned
+runtime. Two service-owned definitions are permitted to participate in demos
+of MCP and model behavior — Gitea (above) and Brave Search:
+
+```text
+# $XDG_CONFIG_HOME/plurnk/.env, read by the service — demo fixtures; never default-enabled
+PLURNK_MCP_BRAVE=npx
+PLURNK_MCP_BRAVE_ARGS=["-y","@brave/brave-search-mcp-server@2.1.0"]
+PLURNK_MCP_BRAVE_ENV={"BRAVE_API_KEY":"${BRAVE_API_KEY}"}
+PLURNK_MCP_BRAVE_TOOLS=["brave_web_search","brave_news_search"]
+PLURNK_MCP_BRAVE_READ=["brave_web_search","brave_news_search"]
+PLURNK_MCP_ENABLED=[]
+```
+
+The credential is one symbolic reference — the authoritative `BRAVE_API_KEY`
+environment value is expanded only while preparing the connection, never
+copied. The fixture admits exactly the web/news search tools and classifies
+them read-only; the rest of the vendor catalog is not admitted.
+
+**Pinned release and revision.** `@brave/brave-search-mcp-server@2.1.0`
+(stdio) pins `@modelcontextprotocol/sdk@1.29.0`, whose latest protocol
+revision is `2025-11-25` and which does not implement `server/discover`. The
+host negotiates-and-degrades ({§mcp-authority}), so the fixture connects at
+`2025-11-25` with the standard tool surface — verified live: the demo story
+`{§web-search-retrieval}` researched through the real Brave MCP tool and
+answered from it.
+
 ## Service defaults
 
-One `PLURNK_MCP_<server>` variable declares each default server. Its suffix
+One `PLURNK_MCP_<server>` variable declares each available server. Its suffix
 case-folds to an `[a-z][a-z0-9-]*` executor and URI-authority name.
 
 Streamable HTTP:
@@ -69,6 +122,7 @@ PLURNK_MCP_github=https://example.test/mcp
 PLURNK_MCP_github_BEARER=${GITHUB_TOKEN}
 PLURNK_MCP_github_TOOLS=["issue_read","issue_search"]
 PLURNK_MCP_github_READ=["issue_read","issue_search"]
+PLURNK_MCP_ENABLED=["github"]
 ```
 
 Stdio:
@@ -98,8 +152,8 @@ Portable timeouts and complete examples live in [`.env.defaults`](./.env.default
 
 | MCP surface | Plurnk surface |
 |---|---|
-| Enabled tool | Exact Registered Tools row and `## EXEC0 [server] (tool)` |
-| Tool schemas | `worker://plurnk/docs/<server>.md` |
+| Server tools | `worker://plurnk/tools/<server>.md` family summary |
+| Enabled tool | Exact `worker://plurnk/tools/<server>/<encoded-tool>.md` document and `## EXEC0 [server] (tool)` |
 | Resource catalog | `server:///` or `server:///resources` |
 | Resource | `server:///resources/<encoded-uri>` through ordinary `FIND` and `READ` |
 | Prompt catalog | `server:///prompts` |
@@ -119,7 +173,7 @@ client.
 ## Authorization
 
 HTTP definitions support bearer references, client credentials, and
-interactive OAuth. Stdio never receives OAuth. Interactive attachment returns
+interactive OAuth. Stdio never receives OAuth. Interactive add or enable returns
 `{ "status": 202, "authorization": { "url": "..." } }` without publishing a
 partial server. After the user completes that URL, the client submits its
 complete callback URL through `workspace.mcp.oauth.complete`. PKCE, issuer and

package/SPEC.md

@@ -9,23 +9,34 @@ executor, resource, proposal, entry, Problem, and lifecycle contracts.
 
 ## §mcp-authority Protocol authority
 
-The only accepted revision is `2026-07-28`, specification commit
+The host's own wire authority is revision `2026-07-28`, specification commit
 `5f5440bb26a62e2cf3440b92da5a667efa03b267`. The implementation exact-pins
 `@modelcontextprotocol/client@2.0.0`. SDK exports are not protocol authority:
 that package deliberately retains legacy and deprecated API shapes. It owns
 core negotiation and transport; this package owns only exact-pinned extension
 wire that the SDK does not yet implement.
 
-The optional Tasks authority is the official `experimental-ext-tasks` contract
-at commit `2c1425d9a288b9b1f489430fe1e00bb392b47e48`. Its absence from the current
-SDK runtime does not revive that SDK's retained 2025 Tasks vocabulary.
+Connection setup negotiates-and-degrades. A server that negotiates the pinned
+revision and offers `server/discover` is a **modern** peer: it gets the complete
+extension wire (the `_meta` envelope, `resultType`, the Tasks extension) and its
+discover result is the identity and capability source. A server the SDK
+negotiated below the pin is an ordinary MCP peer: it serves the standard
+tool/resource/prompt surface from its `initialize` result at its negotiated
+revision, and the host applies no envelope, discover, or Tasks requirements to
+it. There is no rejection for offering an older supported revision and no
+protocol downgrade of the host's own extension wire: modern peers and legacy
+peers simply carry different surfaces.
 
-Every request carries the modern `_meta` envelope. Connection setup verifies
-`server/discover` at the pinned revision before publishing any runtime or
-scheme. There is no protocol downgrade or legacy fallback.
+The optional Tasks authority is the official `experimental-ext-tasks` contract
+at commit `2c1425d9a288b9b1f489430fe1e00bb392b47e48`. It is negotiated
+per-connection and absent from a legacy peer.
 
 ## §mcp-core-matrix Core capability matrix
 
+The accountable capability matrix lives in `capabilityMatrix.ts`
+({§mcp-capability-matrix}); this section states the core surface contract the
+matrix rows cite.
+
 | Surface | Upstream contract | Plurnk host disposition |
 |---|---|---|
 | Base | JSON-RPC 2.0; per-request protocol, identity, and capability metadata; every result has `resultType` | Require the modern envelope and preserve protocol results and errors without reconstructing them |
@@ -58,6 +69,26 @@ Polling honors each current `pollIntervalMs` under the one owning operation
 deadline. Task input keys are fulfilled at most once, in one atomic client
 interaction per observed input set. A completed Task is validated as the
 originating tool result; a failed Task preserves its JSON-RPC error.
+Handle ownership and the restart journey are bounded in {§tasks-lifetime}.
+
+## §tasks-lifetime Tasks lifetime and re-run
+
+Task handles are owned in-process by the connection and operation that created
+them; Plurnk deliberately declines durable task-handle recovery. A durable
+handle would need a persisted scheduler and a home for a result whose owning
+operation does not outlive the daemon; the ordinary Plurnk journey is that a
+restart re-runs the operation, which drives a fresh task. The server's own
+persistence of task state is respected only within one connection lifetime;
+nothing task-shaped is written to SQLite and no MCP sidecar lifecycle exists.
+
+| Boundary | Behaviour |
+|---|---|
+| Client disconnect | The daemon-owned operation and its task keep running; the client reattaches to the operation, not the task. |
+| Daemon restart | The connection and every in-flight task handle die with it; the tool call fails like any interrupted operation, the loop re-runs, and the tool call creates a fresh task. |
+| Workspace reattachment | The attachment reconstructs from its durable definition; in-flight tasks on the replaced connection are abandoned, not resumed. |
+| Expiry | The owning operation deadline bounds polling; a non-converging task fails at the standard round bound and is cancelled. |
+| Cancellation | Owner abort cancels the task before settling; the handle is then terminal. |
+| Already terminal | Terminal results and errors are consumed by the drive loop; a completed or failed task is never re-polled or re-resumed. |
 
 ## §mcp-exclusions Removed, deprecated, and excluded surfaces
 
@@ -71,9 +102,29 @@ originating tool result; a failed Task preserves its JSON-RPC error.
 | Removed | `resources/subscribe`, `resources/unsubscribe`, SSE resumption and `Last-Event-ID` | Use `subscriptions/listen`; reissue a lost request with a new ID |
 | Removed | Legacy Tasks `tasks/list`, `tasks/result`, and task-augmentation request fields | Use only the negotiated final Tasks extension |
 | Excluded | Other official, experimental, or private extensions | Require a separately owned contract before negotiation |
-| Excluded | Legacy revisions and dual-era operation | Pin `2026-07-28`; never probe-and-fallback |
+| Excluded | Dual-era operation | Modern peers and legacy peers carry different surfaces; the host never mixes the two on one connection |
 | Excluded | MCP server and authorization-server roles | This package is the host/client only |
 
+## §mcp-capability-matrix Accountable capability matrix
+
+`capabilityMatrix.ts` is the one accountable support matrix: one row per core
+surface, official extension, or explicitly selected experimental candidate,
+carrying authority, disposition (supported, partial, excluded, deferred),
+advertisement, interactivity, and evidence citations. Rows are "supported"
+only when every layer their owning contract includes has real coverage; a row
+cannot claim support merely because the direct SDK or conformance path passes.
+Every evidence citation must resolve through a named specification tag or a
+named composed test.
+
+The static wire advertisement is derived from the matrix by construction
+(`staticClientCapabilities`): an extension reaches the wire only because its
+row says `always`, and a `conditional` extension is added only by its owning
+connection logic ({§oauth-client-credentials}). The matrix unit tests enforce
+unique identities, no excluded row advertising, supported rows citing evidence,
+composed coverage for interactive advertised rows, and exact reconciliation
+between the matrix and the derived advertisement. Official required
+conformance stays a separate named gate, never folded into a matrix row.
+
 ## §mcp-transports Transport bindings
 
 | Binding | Contract |
@@ -81,6 +132,11 @@ originating tool result; a failed Task preserves its JSON-RPC error.
 | stdio | Spawn one exact executable with an explicit argument array and no shell; newline-delimited JSON-RPC is the only stdout/stdin traffic; stderr is diagnostic; shutdown closes stdin, waits, then terminates if necessary |
 | Streamable HTTP | Send one POST per request or notification; accept JSON or SSE responses; close the response stream to cancel; never open the removed general GET stream |
 
+§mcp-stdio-process-ownership A stdio connection owns the complete process group
+created for its server. Ordinary closure forwards stdin EOF and permits a
+bounded graceful exit; an expired shutdown bound or disappearance of the host
+process forcibly terminates the group, including descendants.
+
 Every HTTP request carries matching `MCP-Protocol-Version` and `Mcp-Method`
 headers. Named requests also carry `Mcp-Name`; declared primitive tool
 parameters carry validated `Mcp-Param-*` headers. Header names compare
@@ -108,11 +164,23 @@ originating distinction in its canonical Problem/result path.
 
 ## §mcp-configuration Configuration
 
-Two inputs produce one effective definition per workspace. Service environment
-variables are convenience defaults instantiated independently for every
-workspace. The workspace's durable attachment map may add a server, replace a
-default, or retain a tombstone that suppresses a default after detach. Neither
-source expands the model-facing namespace with a second discovery surface.
+Service configuration and workspace state produce one available set and one
+enabled subset per workspace. Every `PLURNK_MCP_<server>` declares an available
+service-owned definition. `PLURNK_MCP_ENABLED` names the exact subset enabled
+when a workspace has no override. Workspace state may positively override a
+service definition's enabledness or own an added definition and its enabledness.
+Disabled definitions remain client-visible but contribute no connection,
+Registry, documentation, or resource authority.
+
+§mcp-hydration-isolation **Cold endpoint failure is capability-local.** Invalid
+service configuration or durable state fails admission, but an enabled server
+that cannot connect or complete discovery during workspace hydration remains
+enabled and client-visible as `unavailable`. It publishes no runtime, tools,
+resources, or documentation and cannot prevent other capabilities or the daemon
+from starting. Enabling that already-enabled alias is an explicit reconnect
+attempt; failure preserves the unavailable snapshot, while success atomically
+replaces it. Interactive add and enable mutations continue to reject an
+unavailable candidate without changing durable state.
 
 | Variable | Contract |
 |---|---|
@@ -124,6 +192,10 @@ source expands the model-facing namespace with a second discovery surface.
 | `PLURNK_MCP_<server>_HEADERS` | JSON string map for supplementary HTTP headers |
 | `PLURNK_MCP_<server>_TOOLS` | Optional JSON array of exact enabled tool names; absent enables all listed server tools, while `[]` enables none |
 | `PLURNK_MCP_<server>_READ` | JSON string array forming an exact subset of enabled tools that the operator classifies as read-only; every other enabled tool retains the conservative `host` effect |
+| `PLURNK_MCP_<server>_SUMMARY` | Authored one-line server orientation ({§mcp-summary-derivation}) |
+| `PLURNK_MCP_<server>_<tool>_SUMMARY` | Authored one-line tool orientation; tool names fold the same way and may contain underscores |
+| `PLURNK_MCP_ENABLED` | JSON array of exact configured server aliases enabled by default; absent or `[]` enables none |
+| `PLURNK_MCP_EXPANDED` | JSON array subset of enabled servers whose complete tool tree also expands into the turn-0 tools survey ({§tools-resource-materialization}); absent or `[]` expands none |
 | `PLURNK_MCP_CONNECT_TIMEOUT` | Positive integer milliseconds |
 | `PLURNK_MCP_REQUEST_TIMEOUT` | Positive integer milliseconds |
 
@@ -135,9 +207,22 @@ executable string even when its path contains whitespace; arguments never hide
 inside it. Bearer authentication and a case-insensitive `Authorization` entry
 in `_HEADERS` are mutually exclusive.
 
+§mcp-summary-derivation **Every orientation line derives from authored
+metadata — never a container template.** The runtime declaration's summary
+resolves in order: the `_SUMMARY` companion, the server's own
+`serverInfo.description`, its display `title` (both spec metadata — a title
+like "Chrome DevTools MCP server" is already a one-liner), the first sentence
+of its `instructions` essay, then a factual tool-name list. Each tool's one-liner
+resolves: its `_<server>_<tool>_SUMMARY` companion, `annotations.title`, the
+first sentence of its `description` (capped), then the tool name. The family
+doc's Summary section and the survey row carry the server one-liner; the tool
+doc's Summary section IS the invocation form
+`EXEC [server] (tool) <!-- one-liner -->`, so the discovery row teaches the
+call ({§tools-resource-materialization}). Summary companions expand `${NAME}`
+references like every other companion.
+
 §mcp-definition-wire The contracts-owned `McpServerDefinition` JSON Schema is
-the one workspace action and durable-state shape. It is a closed discriminated
-union:
+the normalized durable definition shape. It is a closed discriminated union:
 
 | Transport / authorization | Required definition | Optional definition |
 |---|---|---|
@@ -147,7 +232,7 @@ union:
 | `http` + interactive OAuth / CIMD preferred | above plus `authorization: { type: "oauth", redirectUrl, clientMetadataUrl }` | `scope`; DCR remains the server-advertised fallback when CIMD is unavailable |
 | `http` + interactive OAuth / pre-registered | above plus `authorization: { type: "oauth", redirectUrl, clientId, clientSecret: "${NAME}" }` | `scope` |
 | `http` + interactive OAuth / DCR fallback only | above plus `authorization: { type: "oauth", redirectUrl }` | `scope` |
-| `http` + client credentials | above plus `authorization: { type: "client-credentials", clientId, clientSecret: "${NAME}" }` | `scope` |
+| `http` + client credentials | above plus `authorization: { type: "client-credentials", clientId, clientSecret: "${NAME}" }` | `scope`; `issuer` binds the credential to its authorization server ({§oauth-client-credentials}) |
 
 `tools` absent enables the complete listed set; `[]` enables none. `read` is an
 exact subset of the enabled set. A credential field is one complete symbolic
@@ -159,6 +244,27 @@ discovery state, and authorization callback state remain process-memory
 credentials; a restart reconstructs the attachment as authorization-required
 instead of writing secrets into SQLite.
 
+The contracts-owned `McpServerOptions` schema is the closed supplement accepted
+by `workspace.mcp.add` and customized enable. It may contain `args`, `cwd`,
+`env`, `headers`, `authorization`, `tools`, and `read`; it cannot repeat alias,
+target, or transport. An absolute HTTP(S) target selects Streamable HTTP. Every
+other target is one exact stdio executable. The normalized definition rejects
+transport-inapplicable options before any connection work.
+
+§mcp-configuration-cascade MCP server configuration has one field-wise
+precedence order: service environment, durable workspace specialization,
+client configuration overlay, then explicit action options. Arrays and maps
+replace their lower value instead of appending or merging. A client-supplied
+target replaces the complete lower definition before its companion variables
+apply; a companion without a client target specializes the lower definition.
+The contracts-owned `{§mcp-configuration-overlay}` is parsed by the same owner
+and path as service environment declarations. It carries no service controls,
+does not activate a server, and is never persisted as raw environment syntax.
+A successful customized enable persists one complete, normalized, unexpanded
+workspace definition. Thus later enablement needs neither the originating
+client nor its configuration file, and symbolic credentials remain resolvable
+only by the service at connection preparation.
+
 ### §mcp-management-actions Workspace management
 
 Every action below declares `scope: "workspace"` under
@@ -167,12 +273,12 @@ workspace identifier in params.
 
 | Action | Parameters | Result / effect |
 |---|---|---|
-| `workspace.mcp.list` | none | Sorted effective server summaries: name, source, transport, connection/authorization state, negotiated identity/capabilities, enabled tools, and read subset. No credential values. |
-| `workspace.mcp.attach` | `server: McpServerDefinition` | Adds a name absent from the effective workspace. Preparation completes before publication. |
-| `workspace.mcp.replace` | `server: McpServerDefinition` | Replaces one effective definition under the same name; absence is 404. |
-| `workspace.mcp.detach` | `name` | Removes a workspace attachment or writes a tombstone for a service default, then removes its exact Registry, docs, and resource authority. |
-| `workspace.mcp.reconnect` | `name` | Builds a fresh connection from the existing unexpanded definition and atomically replaces the old connection after successful preparation. |
-| `workspace.mcp.oauth.complete` | `name`, `callbackUrl` | State- and issuer-validates one pending interactive callback through the SDK, completes connection preparation, then performs the originally requested attach, replace, or reconnect. |
+| `workspace.mcp.list` | optional `overlay: McpConfigurationOverlay` | Sorted available server summaries: alias, source, target, transport, enabledness, connection/authorization/unavailable state, unavailable Problem, negotiated identity/capabilities, enabled tools, and read subset. A client-only definition is shown disabled with source `client`; carrying configuration neither connects nor persists it. No credential values. |
+| `workspace.mcp.add` | `alias`, `target`; optional `options: McpServerOptions` | Adds and enables a workspace-owned alias absent from the available set. Preparation completes before publication. |
+| `workspace.mcp.enable` | `alias`; optional `overlay: McpConfigurationOverlay`, `options: McpServerOptions` | Resolves the alias through {§mcp-configuration-cascade} and enables it for this workspace. A definition differing from the service baseline becomes the durable workspace specialization. Successful preparation precedes persistence and capability publication. Already connected with the same definition is a no-op; already enabled but unavailable retries preparation. |
+| `workspace.mcp.disable` | `alias` | Disables an available alias, retaining it for client discovery while removing its connection and complete model-facing capability set. Already disabled is a no-op. |
+| `workspace.mcp.remove` | `alias` | Removes a workspace specialization. A same-named service definition is revealed disabled; a workspace-only alias disappears. Service definitions without a specialization reject removal and direct the client to disable them. |
+| `workspace.mcp.oauth.complete` | `alias`, `callbackUrl` | State- and issuer-validates one pending interactive callback through the SDK, completes connection preparation, then performs the originally requested add or enable. |
 | `workspace.mcp.complete` | `server`, `ref`, `argument`; optional `context` | Requests negotiated prompt/resource-template argument completion for a client-owned interaction. |
 
 Expected preparation failures cross the action boundary as MCP-management
@@ -180,26 +286,98 @@ Problems rather than generic AG-UI failures:
 
 | Endpoint condition | Problem |
 |---|---|
-| Definitively does not offer pinned `2026-07-28` through `server/discover` | `502 protocol-revision-unsupported`, non-retryable; names the server, required revision and method, and directs the operator to upgrade or replace the legacy endpoint |
-| Cannot connect or complete current discovery/catalog preparation | `502 server-unavailable`, retryable; names the server and transport without exposing credentials |
+| Cannot connect or complete discovery/catalog preparation at the negotiated revision | `502 server-unavailable`, retryable; names the server and transport without exposing credentials |
+| Client-credentials grant rejected by the authorization server | `502 oauth-client-credentials-failed`, non-retryable; names the server and client id, never the secret ({§oauth-client-credentials}) |
 
 Interactive preparation returns a successful pending result shaped as
 `{ status: 202, authorization: { url } }`; it publishes no candidate runtime.
-The action owner retains one pending candidate per `(workspace, name)` and a
-new request cancels and replaces it. Unrelated workspace changes remain
-authoritative while authorization is pending; drift of the same server fails
-completion with a conflict instead of replaying a stale workspace snapshot.
-`oauth.complete` accepts the complete
+The action owner retains one pending candidate per `(workspace, alias)` and a
+new request cancels and replaces it ({§oauth-lifetime}). Unrelated workspace
+changes remain authoritative while authorization is pending; drift of the same
+server fails completion with a conflict instead of replaying a stale workspace
+snapshot. `oauth.complete` accepts the complete
 callback URL so state, `code`, and `iss` remain one parsing unit. A missing,
 expired, mismatched, or replayed callback fails without exposing attacker-owned
 OAuth error text. It completes either pending hydration or the originally
-requested attach, replace, or reconnect. There is no callback HTTP endpoint,
-authority-root resource, or MCP-specific AG-UI route.
+requested add or enable.
+
+## §oauth-lifetime Interactive OAuth lifetime and reauthorization
+
+Interactive OAuth state is deliberately ephemeral and process-memory: client
+registration data, access and refresh tokens, the PKCE verifier, and pending
+state live only in the owning connection or pending candidate. Nothing
+OAuth-secret is written to SQLite; the durable workspace state holds only the
+unexpanded definition ({§mcp-configuration}). There is no callback HTTP
+listener, authority-root resource, or daemon-side browser side channel: the
+client returns the complete callback URL through `workspace.mcp.oauth.complete`
+so `state`, `code`, and `iss` remain one parsing unit. Reauthorization after a
+daemon restart is the intended journey, documented here rather than presented
+as an accidental failure.
+
+| Journey point | Behaviour |
+|---|---|
+| Pending authorization | One pending candidate per `(workspace, alias)`; a new add or customized enable cancels and replaces it. A callback from a superseded attempt fails state validation instead of cross-completing. |
+| Client disconnect | Does not touch the pending candidate; it can still be completed, or replaced by a fresh request. |
+| Daemon restart during pending | The candidate is lost: nothing was durable, no attachment publishes, and `oauth.complete` answers `404 oauth-not-pending`. Start authorization again. |
+| Daemon restart after authorization | The durable definition rehydrates but tokens are gone; the attachment publishes `authorization-required` and enable returns a fresh `{ status: 202, authorization: { url } }`. The operator reauthorizes. |
+| Token expiry | An expired access token surfaces as one unauthorized response; the SDK re-acquires via `refresh_token` when one was issued, otherwise re-enters interactive authorization. |
+| Refresh | Happens only against the issuer bound during the original authorization; the refreshed token replaces the in-memory token. |
+| Workspace disable/remove | Closes the attachment and clears its pending candidate; no durable secret deletion is needed because nothing secret is durable. |
+| Server replacement | Completion compares the pending candidate's expected definition with the current one; drift of the same server fails `409 oauth-target-conflict` instead of replaying a stale snapshot. |
+| Cross-authorization protection | Candidates are keyed by `(workspace, alias)`; callback state, PKCE, and issuer are validated by the SDK against the attempt that created them, so no other workspace, alias, or attempt can complete this authorization. |
+
+## §oauth-client-credentials Client-credentials grant adoption
+
+The `client-credentials` arm of `McpServerDefinition.authorization` adopts the
+official `io.modelcontextprotocol/oauth-client-credentials` extension's
+client-secret form faithfully: an MCP connection whose definition holds a
+client-credentials grant advertises the extension capability in
+`clientCapabilities.extensions`; connections without one never claim it. The
+grant uses `client_secret_basic` authentication with `grant_type
+client_credentials`. Scope from the definition's optional `scope` is passed to
+the token request. The credential itself is one complete symbolic environment
+reference (`clientSecret: "${NAME}"`), expanded only while preparing the
+connection; it is never stored in SQLite, logged, or echoed in Problems.
+
+| Aspect | Behaviour |
+|---|---|
+| Issuer binding | The definition's optional `issuer` is passed as the SDK provider's `expectedIssuer`, stamping the credential with its authorization server so SEP-2352 issuer checks refuse to send it elsewhere. Absent, the SDK's legacy no-binding behaviour applies. |
+| Token lifetime | Token refresh is 401-triggered by the SDK client: an expired access token surfaces as one unauthorized response, the provider re-fetches with the stored credential, and the request is retried. Proactive expiry scheduling is a client-internal optimization, not a wire requirement; Plurnk does not wrap the SDK with its own scheduler. |
+| Rotation | `clientSecret` resolution happens per connection preparation, so rotating the operator environment value takes effect on the next preparation of the server. |
+| Errors | A rejected grant crosses the action boundary as `502 oauth-client-credentials-failed`, non-retryable, naming the server and client id only; SDK OAuth error text is never echoed. Other connection failures keep the generic `server-unavailable` allocation. |
+
+Static credentials authorize application principals (service attachments, CI,
+daemons), not human users. Private-key JWT and static JWT assertions for
+client authentication are a declared non-goal; the specification permits a
+secret-only client and Plurnk declines the assertion arms. The interactive
+OAuth arm is the human-principal path ({§mcp-management-actions}); bearer
+remains the private-service/legacy transport credential.
+
+## §mcp-ema-deferral Enterprise-managed authorization deferral
+
+Plurnk does not advertise or implement
+`io.modelcontextprotocol/enterprise-managed-authorization`. The SDK supplies
+the wire steps (ID-JAG acquisition via RFC 8693 and the RFC 7523 JWT bearer
+grant); the extension's remaining responsibilities are enterprise deployment
+policy, not open-source host mechanics:
+
+| Responsibility | Ownership |
+|---|---|
+| Capability advertisement, ID-JAG and access-token exchange, scope-error handling | Public protocol responsibilities the SDK host could own |
+| SSO acquisition of the identity assertion (ID token or SAML) | Presumes a user session the headless daemon does not own |
+| Saving the identity assertion for later use | Durable identity material; conflicts with the credential policy — secrets have one owner, the operator environment, and never a durable store |
+| IdP endpoint and client registration configuration | Organization-owned; Plurnk has no org-level configuration seam |
+
+The conformance client declines the enterprise scenarios, the capability
+matrix keeps the extension non-advertised ({§mcp-capability-matrix}), and the
+extension stays separate from core OAuth and client-credentials reporting.
+Re-evaluate when an organization-owned configuration owner exists and a
+decision on durable identity material is ratified.
 
 ## §mcp-setup Atomic lifecycle
 
-For each workspace, hydration resolves service defaults against the durable
-attachment/tombstone map, opens and discovers every effective connection,
+For each workspace, hydration resolves service defaults and durable positive
+workspace state, opens and discovers only enabled connections,
 lists the negotiated catalogs, applies enabled/effect policy, builds each exact
 tool Registry and resource facet, and submits one complete owner snapshot to
 {§module-workspace-capabilities}. A configured tool absent from the server, a
@@ -207,8 +385,9 @@ duplicate remote name, an enabled name not representable as a Plurnk target,
 or a `read` name outside the enabled set fails that workspace hydration. No
 partial namespace is published and every acquired candidate closes.
 
-Attach, replace, and reconnect prepare the candidate while the old snapshot
-remains authoritative, then commit only at {§module-workspace-quiescence}. The
+Add and enable prepare the candidate while the old snapshot remains
+authoritative, then commit only at {§module-workspace-quiescence}. Disable and
+remove commit the complete reduced snapshot at the same boundary. The
 old connection rejects replacement while it owns an active protocol request,
 MRTR exchange, or Task. Cache/list-change watches are infrastructure and close
 with the old connection after the new snapshot commits. A failed candidate or
@@ -246,27 +425,62 @@ pending client-owned interaction exactly as proposal review does. MRTR round
 limits, request timeout, cancellation, and Task terminal state are one
 operation lifecycle; none becomes a hidden retry loop.
 
+## §mcp-result-content Passive result content
+
+Every passive content variant the modern revision defines — text, image,
+audio, resource links, and embedded text/blob resources — is preserved
+losslessly into the EXEC channel as one JSON value
+({§json-result-rendering}), the durable evidence path. Plurnk does not claim
+first-class client rendering of non-text variants and adds no MCP-only media
+envelopes: presentation is a client concern over ordinary typed
+entries/resources, and a text-only client degrades by rendering the JSON. A
+standalone `blob` content block is not a modern `tools/call` content member
+(blobs ride inside embedded blob resources) and is rejected as
+protocol-invalid. Size limits and MIME trust remain ordinary channel and
+entry policy, not MCP-specific rules.
+
+## §mcp-apps-exclusion MCP Apps exclusion
+
+Plurnk does not advertise or implement MCP Apps. An Apps host must sandbox
+render third-party HTML/JavaScript, enforce CSP and `_meta.ui` permissions,
+mediate a `postMessage` JSON-RPC `ui/` dialect, proxy app-initiated tool
+calls with consent, and own teardown. No Plurnk client can enforce that
+sandbox today (terminal and Neovim cannot), the daemon is not a second
+application platform, and AG-UI has no standard Apps projection — inventing
+a private event stream to carry Apps is rejected. Tool descriptions carrying
+`_meta.ui` metadata project into Plurnk without it: model-facing summaries
+derive only from name, description, title, and input schema, and no UI
+resource is fetched or preloaded. The capability matrix keeps the extension
+non-advertised ({§mcp-capability-matrix}). Re-evaluate only when a
+sandbox-capable client exists and a standard AG-UI projection is agreed;
+even then the capability would be per-client-advertised, never daemon-wide.
+
 ## §mcp-model-projection Model-facing projection
 
 | MCP surface | Plurnk surface |
 |---|---|
-| Server | One registered executor family and matching resource scheme |
-| Enabled tool | One exact Registered Tools row and `## EXEC0 [<server>] (<tool>)` call |
-| Enabled tool details | `worker://plurnk/docs/<server>.md` through the standard kernel documentation surface |
+| Server | One registered executor family, `worker://plurnk/tools/<server>.md`, and matching resource scheme |
+| Enabled tool | One annotated call in the compact family document plus one exact `worker://plurnk/tools/<server>/<encoded-tool>.md` input-contract document |
+| Tool survey | Ordinary FIND summary metadata from the standard executable-tool resource tree |
 | Resource catalog | `<server>:///` and `<server>:///resources` |
 | Resources | `<server>:///resources` and encoded resource-URI descendants |
 | Prompts | `<server>:///prompts` and encoded prompt-name descendants |
 
 §mcp-tool-presentation One canonical enabled-tool snapshot owns every
 model-facing and executable consequence. Each enabled remote tool becomes one
-exact target in {§executor-tool-registry}. Its Registered Tools row carries the
-remote description, requiredness derived from the input schema, and a
-deterministic one-line JSON-shaped signature: quoted property names, `?` on
-optional properties, primitive type words, and literal unions—never fabricated
-argument data. The snapshot's standard kernel document contains each enabled
-tool's description and exact input/output JSON Schemas. Disabled names appear
-in neither surface, and there is no MCP-specific FIND, READ, authority-root, or
-other model discovery mechanism for tools.
+exact target in {§executor-tool-registry}. Its standard
+{§executor-tool-document} carries the normalized remote description as Summary,
+requiredness derived from the input schema, and a deterministic one-line
+JSON-shaped invocation signature: quoted property names, `?` on optional
+properties, primitive type words, and literal unions—never fabricated argument
+data. The compact family document projects those same facts into annotated,
+copyable EXEC headings; each exact child additionally projects property-level
+input descriptions and standard constraints such as defaults, formats, ranges,
+lengths, and patterns. A missing remote description receives a deterministic
+server-and-tool summary rather than an invented capability claim. Output schemas
+do not enter model teaching; the returned value remains ordinary evidence. Disabled names
+appear in neither discovery nor admission, and there is no MCP-specific FIND,
+READ, authority-root, or other model discovery mechanism for tools.
 
 Core validates the exact target and the selected tool's invocation before
 effect admission. `McpExecutor.run()` independently rejects a target outside