@event4u/agent-config 1.40.0 → 1.41.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "1.40.0"
+    "version": "1.41.0"
   },
   "plugins": [
     {

package/CHANGELOG.md

@@ -318,6 +318,39 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [1.41.0](https://github.com/event4u-app/agent-config/compare/1.40.0...1.41.0) (2026-05-12)
+
+### Features
+
+* **mcp/worker:** add optional MCP-Token Bearer auth ([134c6ee](https://github.com/event4u-app/agent-config/commit/134c6ee34ee5fc1f1809f5be72df1ac82ad0cca6))
+* **mcp:** L2+L4 — implement 7 read-only tools + catalog sync ([44a0082](https://github.com/event4u-app/agent-config/commit/44a00827a7e19051e58e2a5866a37e8c6e4fb1a6))
+* **mcp:** K1+K2 — telemetry SQLite store + CLI dashboard ([e53f321](https://github.com/event4u-app/agent-config/commit/e53f321d3d6a7fb5c95a97232898fbda15cd129b))
+* **mcp:** J6 — telemetry healthcheck + consumer discovery notice ([41f02f7](https://github.com/event4u-app/agent-config/commit/41f02f773feb6248ea315e0820d2a81d960b98c9))
+* **mcp:** J1-J4 — discovery catalog + stub envelope + telemetry ([38aff65](https://github.com/event4u-app/agent-config/commit/38aff651138d8c20929cab88ac437f3106ba44c3))
+
+### Documentation
+
+* **mcp:** remove public endpoint, document self-hosting + Bearer auth ([6c5d7b0](https://github.com/event4u-app/agent-config/commit/6c5d7b04231e9e274265e7f0481502455085f748))
+
+### Refactoring
+
+* **scripts:** migrate readers to centralized agent_settings loader ([7849c03](https://github.com/event4u-app/agent-config/commit/7849c03f282cdaf344ac56056d55cb1c63e17eba))
+
+### Tests
+
+* **mcp:** L3 — hermetic shape contracts for 7 RO tools ([0d3edc9](https://github.com/event4u-app/agent-config/commit/0d3edc9fb1f98df80a4eb503a0dd4c868d2f85f2))
+* **mcp:** J5 — acceptance tests for catalog, envelope, telemetry ([806e4bb](https://github.com/event4u-app/agent-config/commit/806e4bb2bdd2292dfb75eddd9b4eff6073f16a00))
+
+### Chores
+
+* **mcp/taskfile:** add mcp:cloud:secret-put task ([dcffef5](https://github.com/event4u-app/agent-config/commit/dcffef5c384bf75261189b035417593418c8c36c))
+* **roadmap:** flip Phase 2 + Phase 3 of road-to-mcp-full-coverage ([2ce23bc](https://github.com/event4u-app/agent-config/commit/2ce23bcaf7482aeb095cc85d106a78ac5c0d2682))
+* **roadmap:** flip Phase 1 of road-to-mcp-full-coverage (J1–J6) ([707f5c0](https://github.com/event4u-app/agent-config/commit/707f5c002f827b2600cfcf6019d3d22166b46fc2))
+* **ci:** regenerate derived artifacts and fix command-count drift ([dd4eeac](https://github.com/event4u-app/agent-config/commit/dd4eeac96094d99bae318b2160a914be46caead9))
+* **roadmaps:** archive road-to-portable-dev-preferences ([77f4cf1](https://github.com/event4u-app/agent-config/commit/77f4cf1825962503891973800450c3ca769e2adc))
+
+Tests: 3173 (+32 since 1.40.0)
+
 ## [1.40.0](https://github.com/event4u-app/agent-config/compare/1.39.0...1.40.0) (2026-05-11)
 
 ### Features

package/README.md

@@ -90,38 +90,64 @@ Install directly in your agent for global, cross-project use:
 → [Full getting started guide](docs/getting-started.md) ·
 [More examples & expected behavior](docs/showcase.md)
 
-### Remote MCP — zero install
+### Self-hosted MCP on Cloudflare — zero local install
 
-Skills, commands, rules, and guidelines are also served as a hosted MCP
-endpoint. No clone, no `task mcp:setup`, no Python venv — point any
-MCP-capable client (Claude Desktop, Cursor, Zed, Continue, hosted agents)
-at:
+Skills, commands, rules, and guidelines can be served as an MCP endpoint
+from your own Cloudflare Worker — no clone, no `task mcp:setup`, no
+Python venv on the consumer machine, just an HTTP URL any MCP client
+(Claude Desktop, Claude Code, Cursor, Zed, Continue, hosted agents)
+talks to.
 
-```
-https://agent-config-mcp.event4u.workers.dev
+The Worker source lives in `workers/mcp/`; deploying it to your own
+Cloudflare account takes ~5 minutes:
+
+```bash
+task mcp:cloud:login         # one-time, opens browser
+task mcp:cloud:setup         # check → r2-create → r2-verify → whoami
+task mcp:cloud:secret-put    # set MCP-Token (Bearer auth, recommended)
+# Then deploy via CI — see operator guide below.
 ```
 
-Verify it's live:
+After deploy your Worker lives at
+`https://agent-config-mcp.<your-account>.workers.dev` (or a custom
+domain you wire in Step 7 of the operator guide). Verify:
 
 ```bash
-curl https://agent-config-mcp.event4u.workers.dev
+curl https://agent-config-mcp.<your-account>.workers.dev
 # → { "ok": true, "name": "agent-config-mcp", "release_key": "v…", … }
 ```
 
-Read-only, identity-stable per release. Per-client setup snippets
-(Claude Desktop, Claude Code, Cursor, Zed, Continue) —
-[`docs/setup/mcp-client-config.md`](docs/setup/mcp-client-config.md).
-URL shapes (latest vs. pinned `/v<X.Y.Z>`) —
-[`docs/setup/mcp-cloud-endpoints.md`](docs/setup/mcp-cloud-endpoints.md).
-Operator setup (account, R2, secrets) — [`docs/setup/mcp-cloud-setup.md`](docs/setup/mcp-cloud-setup.md).
+Per-client setup snippets (Claude Desktop, Claude Code, Cursor, Zed,
+Continue) — [`docs/setup/mcp-client-config.md`](docs/setup/mcp-client-config.md).
+URL shapes (latest vs. pinned `/v<X.Y.Z>`) — [`docs/setup/mcp-cloud-endpoints.md`](docs/setup/mcp-cloud-endpoints.md).
+Full operator walkthrough (account, R2, GitHub secrets, deploy) —
+[`docs/setup/mcp-cloud-setup.md`](docs/setup/mcp-cloud-setup.md).
 Experimental — A0-cloud contract lives at `docs/contracts/mcp-cloud-scope.md` (internal reference only per `STABILITY.md`).
 
-> **Scope — Lite, not Full.** The hosted MCP endpoint serves the
-> read-only governance surface (skills · commands · rules · guidelines
-> · contexts) as MCP prompts and resources. It does **not** execute any
-> of the ~112 Python scripts that ship with the package (linters,
-> audits, `task ci`, work-engine hooks, …). Those require the full
-> local install per [Quickstart](#quickstart). See
+#### Lock your Worker behind a Bearer token
+
+Without auth, any MCP client that knows your `*.workers.dev` URL can
+read the catalog. For private deploys, set the `MCP-Token` secret and
+the Worker will require `Authorization: Bearer <token>` on every POST:
+
+```bash
+task mcp:cloud:secret-put          # wraps `npx wrangler secret put MCP-Token --name agent-config-mcp`
+# wrangler prompts for the value interactively — never passed via argv.
+```
+
+Once the secret is set, every client config block needs the token in
+its headers — see [`docs/setup/mcp-client-config.md`](docs/setup/mcp-client-config.md) § Bearer auth for the
+per-client snippets (Claude Desktop, Claude Code, Cursor, Zed,
+Continue). The `GET /` liveness probe stays open so health checks keep
+working without the token.
+
+> **Scope — Lite, not Full.** The Worker serves the read-only governance
+> surface (skills · commands · rules · guidelines · contexts) as MCP
+> prompts and resources, plus a small set of read-only tools (`memory_lookup`,
+> `chat_history_read`, `list_*`, `read_resource_body`). It does **not**
+> execute any of the ~112 Python scripts that ship with the package
+> (linters, audits, `task ci`, work-engine hooks, …). Those require the
+> full local install per [Quickstart](#quickstart). See
 > `docs/contracts/mcp-cloud-scope.md` (internal reference only per
 > `STABILITY.md`) for the execution-safety boundary.
 

package/docs/catalog.md

@@ -1,6 +1,6 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **405 public artefacts** shipped by
+Consumer-facing catalog of all **406 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
@@ -248,7 +248,7 @@ are excluded.
 | rule | [`user-interaction`](../.agent-src/rules/user-interaction.md) | auto | Asking the user a question, presenting options, or summarizing progress — numbered-options Iron Law, single-recommendation rule, progress indicators |
 | rule | [`verify-before-complete`](../.agent-src/rules/verify-before-complete.md) | always | Verify before completion — run tests and quality tools before claiming done |
 
-## Commands (105)
+## Commands (106)
 
 | kind | name | cluster | description |
 |---|---|---|---|
@@ -349,7 +349,8 @@ are excluded.
 | command | [`rule-compliance-audit`](../.agent-src/commands/rule-compliance-audit.md) |  | Audit rule trigger quality, simulate activation, detect overlaps, and find never-activating rules |
 | command | [`set-cost-profile`](../.agent-src/commands/set-cost-profile.md) |  | Change the cost_profile in .agent-settings.yml — shows each profile's meaning and applies the selection |
 | command | [`sync-agent-settings`](../.agent-src/commands/sync-agent-settings.md) |  | Sync `.agent-settings.yml` against the current template + profile — adds new sections/keys, preserves user values, shows a diff before writing |
-| command | [`sync-gitignore`](../.agent-src/commands/sync-gitignore.md) |  | Sync the `event4u/agent-config` block in the consumer project's .gitignore — adds missing entries, preserves user-added lines, shows a diff before writing |
+| command | [`sync-gitignore:fix`](../.agent-src/commands/sync-gitignore/fix.md) | cluster: sync-gitignore | Scrub legacy pre-`/agents/` patterns from the consumer's .gitignore (inside or outside the managed block) and re-sync the canonical entries |
+| command | [`sync-gitignore`](../.agent-src/commands/sync-gitignore.md) | cluster: sync-gitignore | Sync the `event4u/agent-config` block in the consumer project's .gitignore — adds missing entries, preserves user-added lines, shows a diff before writing |
 | command | [`tests:create`](../.agent-src/commands/tests/create.md) | cluster: tests | Write meaningful tests for the changes in the current branch |
 | command | [`tests:execute`](../.agent-src/commands/tests/execute.md) | cluster: tests | Run PHP tests inside the Docker container |
 | command | [`tests`](../.agent-src/commands/tests.md) | cluster: tests | Tests orchestrator — routes to create, execute |

package/docs/contracts/file-ownership-matrix.json

@@ -591,6 +591,12 @@
       "load_context": [],
       "load_context_eager": []
     },
+    ".agent-src.uncompressed/commands/sync-gitignore/fix.md": {
+      "kind": "command",
+      "rule_type": null,
+      "load_context": [],
+      "load_context_eager": []
+    },
     ".agent-src.uncompressed/commands/tests.md": {
       "kind": "command",
       "rule_type": null,
@@ -4075,6 +4081,27 @@
       "via": "self",
       "depth": 0
     },
+    {
+      "source": ".agent-src.uncompressed/commands/sync-gitignore.md",
+      "target": ".agent-src.uncompressed/commands/sync-gitignore/fix.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/sync-gitignore/fix.md",
+      "target": ".agent-src.uncompressed/commands/sync-gitignore.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/sync-gitignore/fix.md",
+      "target": ".agent-src.uncompressed/commands/sync-gitignore/fix.md",
+      "type": "WRITE",
+      "via": "self",
+      "depth": 0
+    },
     {
       "source": ".agent-src.uncompressed/commands/tests.md",
       "target": ".agent-src.uncompressed/commands/tests.md",

package/docs/contracts/mcp-discovery-phase-notice.md

@@ -0,0 +1,56 @@
+# MCP Discovery-Phase Notice
+
+**Audience:** MCP consumers integrating with `event4u/agent-config` — host
+applications, CLIs, agents calling our stdio server or the Cloudflare Worker.
+**Status:** active during Phase 1 of
+[`road-to-mcp-full-coverage`](../../agents/roadmaps/road-to-mcp-full-coverage.md).
+
+## What you will see
+
+`tools/list` advertises ~20 tools. Most return a `not_implemented` envelope when
+called — wire shape in [`mcp-tool-stub-envelope`](mcp-tool-stub-envelope.md).
+This is intentional. Phase 1 is *discovery*: every call — implemented, stub, or
+unknown — is logged so Phase 2's implementation cut is derived from real
+consumer behaviour, not guesses.
+
+## What we need from you
+
+**Keep calling the tools you would naturally call.** A call against a stub is
+not a failed integration; it is a vote. Telemetry records carry
+`{tool_name, client_id_hash, ts, transport, outcome}` — no payload bodies, no
+raw identifiers (J4 in the roadmap). Three outcomes are logged:
+
+- `implemented` — a real handler ran.
+- `stub` — catalog entry, no transport handler; you received the envelope.
+- `latent_demand` — name not in the catalog at all. **The most valuable
+  signal.** If you want a tool that does not exist, call it — do not work
+  around the absence silently.
+
+## How to verify telemetry is flowing
+
+On any host running the stdio server:
+
+```bash
+python3 scripts/mcp_telemetry_health.py
+```
+
+Healthy → exit 0 with the 24 h count. Silent → exit 1; treat as an alert.
+Wire it into Sentry, a GitHub Actions cron, a mailer, or `launchd` — whatever
+you already trust. Worker telemetry lands in Cloudflare Workers Logs
+(structured `mcp.telemetry` lines); query via the dashboard or `wrangler tail`.
+
+## Phase 1 → Phase 2 gate
+
+When the gate fires (≥ 4 weeks of healthy telemetry, ≥ 500 logged attempts,
+≥ 50 distinct `client_id_hash` values), the council ranks tools by demand and
+picks the implementation cut. Tools above the line move from stub → real;
+tools below stay stubbed and may be removed. Silent windows ≥ 24 h refuse the
+K3 gate and restart the observation period — that is why the healthcheck
+output matters.
+
+## Contact
+
+Open an issue against
+[`event4u-app/agent-config`](https://github.com/event4u-app/agent-config) with
+the `mcp-discovery` label if a call returns something other than the documented
+envelope or if `latent_demand` is not landing for a tool you call.

package/docs/contracts/mcp-tool-stub-envelope.md

@@ -0,0 +1,78 @@
+---
+stability: experimental
+---
+
+# MCP Tool Stub Envelope — Phase 1 Discovery Contract
+
+> **Status:** Active · governs Phase 1 (J1–J6) of
+> [`road-to-mcp-full-coverage.md`](../../agents/roadmaps/road-to-mcp-full-coverage.md).
+> **Stability:** experimental — internal index reference only per
+> `STABILITY.md`.
+
+## Purpose
+
+Locks the wire shape of the `not_implemented` envelope returned by
+`tools/call` when a consumer agent invokes a catalog entry that has no
+implementation on the active transport. Every denied call returns a
+structured payload with a recovery hint, never a silent 404 and never
+a 500.
+
+## Source of truth
+
+`scripts/mcp_server/consumer_tool_catalog.json` (schema_version 1).
+Both the stdio server and the Cloud Worker bundle (`workers/mcp/`,
+packed by `scripts/pack_mcp_content.py`) read from this file. The
+manifest returned by `tools/list` is byte-identical apart from
+per-tool `implemented_on` metadata.
+
+## Catalog entry
+
+```json
+{
+  "name": "<snake_case>",
+  "description": "<≤500 chars; agent-facing>",
+  "side_effect": "ro | fs-write | shell",
+  "implemented_on": ["stdio"],
+  "input_schema": { "type": "object", "...": "JSON Schema draft-7" }
+}
+```
+
+`implemented_on` lists transports where a real handler is wired;
+missing transports return the envelope.
+
+## Envelope wire shape
+
+```json
+{
+  "code": "not_implemented",
+  "tool": "<catalog name>",
+  "transport": "stdio | worker",
+  "install_hint": "<copyable shell command>",
+  "alternative": "stdio",
+  "message": "<one-sentence explainer>"
+}
+```
+
+Stdio returns this as the JSON-RPC `result` (SDK wraps in
+`TextContent`); the Worker returns it as `error.data` alongside
+`code: -32601`. Field invariants: `code` is the frozen literal
+`not_implemented`; `tool` echoes the caller; `transport` is set per
+surface; `install_hint` comes from the catalog's `install_hint_stdio`
+field; `alternative` is the frozen literal `stdio` until Phase 3.
+Consumer agents must drive logic from `code`, not `message`.
+
+## Unknown-tool / latent-demand path
+
+A call to a name not in the catalog returns JSON-RPC error `-32601`
+with the same envelope shape, `code: "unknown_tool"`. Both transports
+log the attempt with `outcome: "latent_demand"` so Phase 2 can
+promote unforeseen names.
+
+## Acceptance
+
+- Both transports return `code == "not_implemented"` for every
+  catalog entry whose `implemented_on` excludes the transport.
+- Both transports return `code == "unknown_tool"` for any name not in
+  the catalog.
+- Schema version bumps on any incompatible field rename; new optional
+  fields are compatible.

package/docs/getting-started.md

@@ -153,7 +153,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 105 active commands](../.agent-src/commands/)
+→ [Browse all 106 active commands](../.agent-src/commands/)
 
 ---
 

package/docs/setup/mcp-client-config.md

@@ -1,8 +1,17 @@
-# MCP Client Config — Remote agent-config
+# MCP Client Config — Self-hosted agent-config Worker
 
-Connect any MCP-capable client to the hosted `agent-config-mcp` Worker
-at `https://agent-config-mcp.event4u.workers.dev`. Read-only,
-identity-stable per release, no auth.
+Connect any MCP-capable client to your own `agent-config-mcp` Cloudflare
+Worker. Read-only, identity-stable per release. Optional Bearer-token
+auth — see [§ Bearer auth](#bearer-auth) below.
+
+> **No public endpoint.** This package ships the Worker source under
+> `workers/mcp/`, but does **not** operate a shared hosted MCP server.
+> Deploy your own per [`mcp-cloud-setup.md`](mcp-cloud-setup.md) — your
+> URL will be `https://agent-config-mcp.<your-account>.workers.dev`
+> (or a custom domain you wire up in Step 7).
+>
+> In every snippet below, **replace `https://your-worker.workers.dev`
+> with your actual deployment URL**.
 
 For URL shapes (latest vs. pinned `/v<X.Y.Z>`) see
 [`mcp-cloud-endpoints.md`](mcp-cloud-endpoints.md). For operator
@@ -26,14 +35,29 @@ look for MCP server config inside `.agent-settings.yml`.
 | MCP client config (this page) | client-specific path per section above | the MCP client at startup | which MCP servers to talk to (name + URL / command) |
 | `.agent-settings.yml` | consumer project root (`<repo>/.agent-settings.yml`) | the agent at runtime (Claude / Cursor / …) | per-developer preferences: `name`, `ide`, `cost_profile`, `personal.autonomy`, `pipelines.skill_improvement`, `caveman.speak_scope`, … |
 
-The hosted MCP is **stateless** and **project-agnostic** — it serves
-the same skill / rule / command catalog to every client. Personalization
+The Worker is **stateless** and **project-agnostic** — it serves the
+same skill / rule / command catalog to every client. Personalization
 happens agent-side after the MCP delivers its content blob; the Worker
 itself does not read `.agent-settings.yml`.
 
 First-time setup of `.agent-settings.yml` runs through `/onboard`;
 template drift is handled by `/sync-agent-settings`.
 
+## Bearer auth
+
+If you set the `MCP-Token` secret on your Worker (via
+`task mcp:cloud:secret-put`), every POST request must carry the header
+`Authorization: Bearer <token>`. The `GET /` liveness probe stays
+unauthenticated.
+
+Add the header to each client below by appending the per-client header
+snippet shown in its section. Treat the token like any other secret —
+keep it out of repo files and shared dotfiles; prefer an env var
+(`MCP_TOKEN`) sourced from a password manager or shell init.
+
+If your Worker has **no** `MCP-Token` secret set, skip the header
+snippets — every POST is accepted as-is.
+
 ## Claude Desktop
 
 Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
@@ -44,7 +68,24 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
   "mcpServers": {
     "agent-config": {
       "command": "npx",
-      "args": ["-y", "mcp-remote", "https://agent-config-mcp.event4u.workers.dev"]
+      "args": ["-y", "mcp-remote", "https://your-worker.workers.dev"]
+    }
+  }
+}
+```
+
+With Bearer auth, add `--header`:
+
+```json
+{
+  "mcpServers": {
+    "agent-config": {
+      "command": "npx",
+      "args": [
+        "-y", "mcp-remote", "https://your-worker.workers.dev",
+        "--header", "Authorization: Bearer ${MCP_TOKEN}"
+      ],
+      "env": { "MCP_TOKEN": "paste-token-here" }
     }
   }
 }
@@ -60,7 +101,14 @@ Connector** with the URL directly — no `mcp-remote` wrapper needed.
 Native HTTP transport — one command:
 
 ```bash
-claude mcp add --transport http agent-config https://agent-config-mcp.event4u.workers.dev
+claude mcp add --transport http agent-config https://your-worker.workers.dev
+```
+
+With Bearer auth:
+
+```bash
+
+
 ```
 
 Verify:
@@ -78,12 +126,14 @@ claude mcp list
 {
   "mcpServers": {
     "agent-config": {
-      "url": "https://agent-config-mcp.event4u.workers.dev"
+      "url": "https://your-worker.workers.dev",
+      "headers": { "Authorization": "Bearer paste-token-here" }
     }
   }
 }
 ```
 
+(Omit the `headers` block if your Worker has no `MCP-Token` secret.)
 Reload Cursor (`Cmd+Shift+P → Reload Window`).
 
 ## Zed
@@ -96,12 +146,17 @@ Reload Cursor (`Cmd+Shift+P → Reload Window`).
     "agent-config": {
       "source": "custom",
       "command": "npx",
-      "args": ["-y", "mcp-remote", "https://agent-config-mcp.event4u.workers.dev"]
+      "args": [
+        "-y", "mcp-remote", "https://your-worker.workers.dev",
+        "--header", "Authorization: Bearer ${MCP_TOKEN}"
+      ],
+      "env": { "MCP_TOKEN": "paste-token-here" }
     }
   }
 }
 ```
 
+Drop the `--header` / `env` pair when the Worker has no token set.
 Zed has no native remote-MCP transport yet, so the `mcp-remote`
 bridge is required.
 
@@ -113,19 +168,28 @@ bridge is required.
 mcpServers:
   - name: agent-config
     command: npx
-    args: ["-y", "mcp-remote", "https://agent-config-mcp.event4u.workers.dev"]
+    args:
+      - "-y"
+      - mcp-remote
+      - https://your-worker.workers.dev
+      - --header
+      - "Authorization: Bearer ${MCP_TOKEN}"
+    env:
+      MCP_TOKEN: paste-token-here
 ```
 
+Drop the `--header` / `env` keys when the Worker has no token set.
+
 ## Verify
 
 After reload, every client should:
 
 1. List `agent-config` under connectors / tools with a release-key
    matching the live deploy. Probe the endpoint to see the current
-   release:
+   release (the `GET /` liveness probe is always unauthenticated):
 
    ```bash
-   curl https://agent-config-mcp.event4u.workers.dev
+   curl https://your-worker.workers.dev
    # → { "ok": true, "release_key": "v…", "signature": "…", … }
    ```
 
@@ -134,6 +198,23 @@ After reload, every client should:
 3. Expose rule + guideline + context resources under `rule://…`,
    `guideline://…`, `context://…`.
 
+With Bearer auth, a wrong/missing token returns HTTP 401 with body
+`{"jsonrpc":"2.0","id":null,"error":{"code":-32001,"message":"Unauthorized"}}` —
+quick way to confirm enforcement:
+
+```bash
+curl -X POST -H "content-type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}' \
+  https://your-worker.workers.dev
+# → 401 Unauthorized
+
+curl -X POST -H "content-type: application/json" \
+  -H "Authorization: Bearer $MCP_TOKEN" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}' \
+  https://your-worker.workers.dev
+# → 200 { "jsonrpc":"2.0","id":1,"result":{} }
+```
+
 If the client shows the connector but no prompts / resources,
 re-probe the URL — a 5xx from the Worker indicates the deploy is
 mid-roll, retry after a minute.

package/docs/setup/mcp-cloud-setup.md

@@ -15,6 +15,7 @@ machine.
 ```sh
 task mcp:cloud:login        # one-time, opens browser
 task mcp:cloud:setup        # check → r2-create → r2-verify → whoami
+task mcp:cloud:secret-put   # optional but recommended — sets MCP-Token (Bearer auth)
 # Copy account id from output → GitHub Secrets (see § GitHub Secrets)
 # Create scoped API token (see § API Token) → GitHub Secrets
 # Done. First `release: published` triggers the deploy.
@@ -114,7 +115,36 @@ Green smoke step → `latest.txt` repoints → release is live on
 `*.workers.dev`. A red smoke step leaves `latest.txt` on the previous
 release.
 
-## Step 7 — DNS (optional, Phase 5.2)
+## Step 7 — Bearer auth (recommended)
+
+Without auth, anyone who knows your `*.workers.dev` URL can read the
+catalog. The Worker checks for an `MCP-Token` secret and, when set,
+gates every POST behind `Authorization: Bearer <token>`. The `GET /`
+liveness probe stays open so health checks keep working.
+
+Generate a token (any high-entropy random string — `openssl rand -hex 32`
+or your password manager) and set it on the Worker:
+
+```sh
+task mcp:cloud:secret-put
+# wrangler prompts for the value interactively (stdin) — never passed
+# via argv, never written to shell history.
+```
+
+This wraps `npx wrangler secret put MCP-Token --name agent-config-mcp`.
+The secret is encrypted in Cloudflare and injected as `env["MCP-Token"]`
+at request time; the source repo never sees the value.
+
+Once set, every MCP client config needs the header — per-client
+snippets (Claude Desktop, Claude Code, Cursor, Zed, Continue) live in
+[`mcp-client-config.md`](mcp-client-config.md) § Bearer auth.
+
+Rotate by re-running `task mcp:cloud:secret-put` with a fresh value;
+the new secret takes effect on the next request (no redeploy needed).
+To remove auth entirely, run
+`npx wrangler secret delete MCP-Token --name agent-config-mcp`.
+
+## Step 8 — DNS (optional, Phase 5.2)
 
 Custom domain `mcp.<your-domain>` setup lives in
 [`docs/setup/mcp-cloud-endpoints.md`](mcp-cloud-endpoints.md) § DNS
@@ -141,6 +171,7 @@ setup. Until cutover, the Worker serves on the free
 | `task mcp:cloud:r2-create` | Create R2 bucket (idempotent) |
 | `task mcp:cloud:r2-verify` | Verify R2 bucket exists |
 | `task mcp:cloud:setup` | Full chain — check → r2 → whoami |
+| `task mcp:cloud:secret-put` | Set the `MCP-Token` Bearer-auth secret (interactive) |
 | `task mcp:cloud:dev` | Local `wrangler dev` on :8787 |
 | `task mcp:cloud:deploy-dispatch TAG=v…` | Manual workflow trigger |
 

package/docs/setup/per-ide/claude-desktop.md

@@ -68,9 +68,15 @@ If the menu is empty:
 
 ## Step 3 — optional MCP server
 
-Claude Desktop also speaks MCP. Wiring up the hosted `agent-config-mcp`
-Worker exposes the **full** skill / rule / command catalog (~480 items)
-on demand, on top of the 15 you installed in Step 1.
+Claude Desktop also speaks MCP. Wiring up your own self-hosted
+`agent-config-mcp` Cloudflare Worker exposes the **full** skill / rule /
+command catalog (~480 items) on demand, on top of the 15 you installed
+in Step 1.
+
+Deploy the Worker first per [`../mcp-cloud-setup.md`](../mcp-cloud-setup.md) — your
+URL will be `https://agent-config-mcp.<your-account>.workers.dev`
+(or a custom domain you wire up in Step 7). Replace
+`https://your-worker.workers.dev` below with that URL.
 
 Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
 (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows /
@@ -81,7 +87,25 @@ Linux is `~/.config/Claude/claude_desktop_config.json`):
   "mcpServers": {
     "agent-config": {
       "command": "npx",
-      "args": ["-y", "mcp-remote", "https://agent-config-mcp.event4u.workers.dev"]
+      "args": ["-y", "mcp-remote", "https://your-worker.workers.dev"]
+    }
+  }
+}
+```
+
+If you set the `MCP-Token` secret on the Worker (recommended — see
+[`../mcp-cloud-setup.md`](../mcp-cloud-setup.md) § Bearer auth), add the header:
+
+```json
+{
+  "mcpServers": {
+    "agent-config": {
+      "command": "npx",
+      "args": [
+        "-y", "mcp-remote", "https://your-worker.workers.dev",
+        "--header", "Authorization: Bearer ${MCP_TOKEN}"
+      ],
+      "env": { "MCP_TOKEN": "paste-token-here" }
     }
   }
 }
@@ -89,11 +113,12 @@ Linux is `~/.config/Claude/claude_desktop_config.json`):
 
 A pre-wired template ships at
 [`templates/claude_desktop_config.json.template`](../../../templates/claude_desktop_config.json.template) —
-copy + uncomment the MCP block.
+copy, swap the placeholder URL for your deploy, and uncomment the MCP
+block.
 
 Restart Claude Desktop. The 🔌 icon shows the connector under
 **Settings → Connectors**. Full transport details (mcp-remote vs.
-native HTTP) live in
+native HTTP) and per-client Bearer-auth snippets live in
 [`../mcp-client-config.md`](../mcp-client-config.md).
 
 ## Claude Desktop ↔ Claude Code config sharing
@@ -125,7 +150,7 @@ Desktop config**. Once Step 1 + Step 3 are done in Desktop:
   inside Cowork sessions without a separate install.
 - Cowork-specific limit (per Anthropic docs): MCP tools that write to
   the local filesystem are sandboxed — read-only tools (the entire
-  hosted `agent-config-mcp` surface) work fine.
+  `agent-config-mcp` Worker surface) work fine.
 
 If a feature works in Desktop but not in Cowork, check that you're on
 a paid plan — Cowork is gated, Desktop's free tier has the full