@@ -75,7 +75,7 @@ For your own auth UI, disable built-in handling with `otpParam: false`, then cal
 
 - **Stay on loopback.** Bind to a routable address only intentionally, and require authentication when you do.
 - **Keep `auth: false` local.** The hosted bridges (`devframeViteBridge`, `@devframes/next`'s handler) gate their side-car by default; opt out with an explicit `auth: false` only when the host framework owns the trust boundary another way.
-- **The MCP route authenticates the caller.** `Origin` hardens the route-based MCP server against DNS-rebinding, but proves nothing about identity — a native client can send any `Origin`. So the route also requires a bearer: `mcp: true` reads it from `DEVFRAME_MCP_AUTH_TOKEN`, and the route refuses to mount ([`DF0077`](/errors/DF0077)) without a policy. Treat the two checks as separate defenses — see [MCP](/adapters/mcp).
+- **The MCP route trusts same-machine callers, harden it when that's not your boundary.** The origin gate keeps browsers and remote hosts out (loopback-only, `Origin`-less rejected), so `mcp: true` is enough for a local dev tool. `Origin` proves nothing about *which* local process is calling, though — so when the route is reachable beyond loopback (a widened `allowedOrigins`, a hosted app) or exposes destructive tools, add an identity check with `mcp: { authorization }` (a bearer from an env var, or a callback). See [MCP](/adapters/mcp).
 - **Treat tokens as secrets.** Never log the bearer token or the one-time code, or bake either into build output.
 - **Authorize every handler.** Validate inputs, and mark state-changing functions `type: 'destructive'` so MCP and agent clients prompt before invoking them.
 - **Origin-lock remote docks.** When a hub embeds a remote-UI dock, keep `originLock` on (the default) so its session token is only honored on a connection whose `Origin` matches the dock's own.
 
@@ -82,7 +82,7 @@ Registrations are validated fail-fast: one module per type (`DF8108`), an existi
 
 The hub's **single Auth** is one gate at the shared transport for every mounted devframe, built-ins, and the MCP route; one handshake (OTP, magic link, or pre-shared token) unlocks the namespace; `auth: false` disables it for localhost.
 
-The aggregate MCP route carries its **own** identity gate independent of this RPC Auth, since it grants agent clients privileged tool access: `mcp: true` requires the `DEVFRAME_MCP_AUTH_TOKEN` bearer (startup fails with [`DF0077`](/errors/DF0077) without it), or pass `mcp: { authorization }` explicitly. `Origin` remains request hardening, not identity.
+The aggregate MCP route has its own origin gate, independent of this RPC Auth: `mcp: true` trusts same-machine callers, and `mcp: { authorization }` adds an identity check when the hub is reachable beyond loopback. A mounted devframe's own `mcp` setting is ignored — the hub exposes one aggregate route over them all, and warns ([`DF8005`](/errors/DF8005)) when a devframe asks for MCP while the hub's is off.
 
 ## Singular vs hub mounting
 
 
@@ -18,45 +18,40 @@ await createMcpServer(myDevframe, { transport: 'stdio' })
 
 ## Route-based server
 
-The dev server exposes the same MCP API over HTTP, live. Enable with `cli.mcp`:
+The dev server exposes the same MCP API over HTTP, live. Enable with the top-level `mcp`:
 
 ```ts
 import { defineDevframe } from 'devframe'
 
 export default defineDevframe({
   // …
-  cli: {
-    // Reads the bearer from DEVFRAME_MCP_AUTH_TOKEN.
-    mcp: true,
-  },
+  mcp: true,
 })
 ```
 
 The endpoint speaks Streamable-HTTP at `/__mcp` (`/__<id>/__mcp` under a host framework), sharing its origin/port. `--mcp` / `--no-mcp` override; `__connection.json` advertises it.
 
 The endpoint is **stateless**: it serves the [2026-07-28 revision](https://modelcontextprotocol.io/specification/2026-07-28) per request through the SDK's `createMcpHandler`, building a fresh MCP server for each request — every HTTP request stands alone, with no `Mcp-Session-Id` to correlate. 2025-era clients are still served through the SDK's stateless legacy path.
 
-### Two gates: origin hardening and identity
+### Origin gate, and opt-in identity
 
-The route exposes privileged agent tools, so every request clears two independent gates. The **origin gate** requires `Origin` be loopback (or allow-listed) and rejects `Origin`-less requests — DNS-rebinding hardening that proves nothing about *who* is calling, since a native client can send any `Origin`. Widen it for a tunnel/LAN origin with `cli: { mcp: { authorization: process.env.MY_TOKEN, allowedOrigins: ['https://tunnel.example.com'] } }`.
+The **origin gate** guards every request: `Origin` must be loopback (or allow-listed), and `Origin`-less requests are rejected (a disallowed origin gets `403`). This is DNS-rebinding hardening that keeps browsers and remote hosts out, and it trusts same-machine callers — so `mcp: true` is all a local dev tool needs.
 
-The **identity gate** then proves the caller. `mcp: true` reads its bearer from the `DEVFRAME_MCP_AUTH_TOKEN` environment variable; a request presents it as `Authorization: Bearer <token>` and it is matched in constant time. A missing or wrong bearer gets `401` with a `WWW-Authenticate: Bearer` challenge; a disallowed origin gets `403`. Startup fails with [`DF0077`](/errors/DF0077) — the route is never mounted — when `mcp: true` finds no environment token, or an object config omits `authorization`.
-
-An object config sets the policy explicitly:
+`Origin` proves nothing about *who* is calling, though: a native process on the same box can send any `Origin`. When a same-machine process isn't your trust boundary — a LAN/tunnel origin, a shared/CI host, a destructive tool surface — layer on an **identity check** with `authorization`:
 
 ```ts
 export default defineDevframe({
-  cli: {
-    // A bearer from your own environment variable:
-    mcp: { authorization: process.env.MY_TOKEN },
-    // — or a callback identity check (governs identity only; it cannot relax the origin gate):
-    // mcp: { authorization: request => isTrusted(request) },
-    // — or an origin-only opt-out for a loopback-bound local tool that owns its trust boundary another way:
-    // mcp: { authorization: false },
-  },
+  // A bearer token, backed by your own environment variable (never a literal):
+  mcp: { authorization: process.env.MY_TOKEN },
+  // — or a callback identity check (governs identity only; it cannot relax the origin gate):
+  // mcp: { authorization: request => isTrusted(request) },
+  // — or the explicit default, origin-only:
+  // mcp: { authorization: false },
 })
 ```
 
+A request presents the bearer as `Authorization: Bearer <token>`, matched in constant time; a missing or wrong bearer gets `401` with a `WWW-Authenticate: Bearer` challenge. The origin gate always runs first, so a disallowed origin is `403` regardless of the credential. Widen the origin allow-list for a tunnel/LAN reach with `mcp: { authorization: process.env.MY_TOKEN, allowedOrigins: ['https://tunnel.example.com'] }`.
+
 Never place the token in a URL, in `__connection.json`, in the instance registry, in logs, or on the command line — it belongs only in configuration and the `Authorization` header.
 
 ### Hosted bridges
@@ -71,7 +66,7 @@ devframeViteBridge(myDevframe, { mcp: true })
 createDevframeNextHandler(myDevframe, { mcp: true })
 ```
 
-Both honor the same authorization contract: `mcp: true` requires the `DEVFRAME_MCP_AUTH_TOKEN` bearer, or pass `mcp: { authorization }` explicitly.
+Both honor the same contract: `mcp: true` is origin-only; add `mcp: { authorization }` to harden.
 
 ## Custom host frameworks
 
@@ -84,8 +79,8 @@ const mcp = createMcpFetchHandler(ctx, {
   serverName: 'my-tool (devframe)',
   serverVersion: '1.0.0',
   exposeSharedState: true,
-  // Required: the identity policy — a bearer token, a callback, or `false`.
-  authorization: process.env.DEVFRAME_MCP_AUTH_TOKEN!,
+  // Optional identity check on top of the origin gate; omit for origin-only.
+  // authorization: process.env.MY_TOKEN,
 })
 // route every method on /__mcp to mcp.fetch(request)
 ```
@@ -109,6 +104,6 @@ Two gateway tools (`devframe:connect:*` ids — see [tool ids and wire names](/g
 
 Discovery reads the **instance registry**: every `createDevServer` writes `~/.devframe/instances/<pid>-<port>.json`, dialed with a loopback origin. In-process host frameworks register via `registerDevframeInstance` (`devframe/node`). `--port <n>` probes a port; `DEVFRAME_INSTANCES_DIR` relocates the registry, `DEVFRAME_DISABLE_INSTANCE_REGISTRY=1` opts out.
 
-The connector reads `DEVFRAME_MCP_AUTH_TOKEN` and presents it as the bearer to each instance's authenticated route (never a CLI flag — command-line arguments are visible to other processes). An instance whose route requires a different bearer reports auth-required rather than being reached; connect to a fleet with distinct credentials by driving `startConnectServer` with a per-instance `authToken` resolver.
+Most instances trust same-machine callers, so the connector reaches them with no credential. For an instance you *hardened* with a bearer, the connector reads `DEVFRAME_MCP_AUTH_TOKEN` and presents it (never a CLI flag — command-line arguments are visible to other processes). Connect to a fleet with distinct credentials by driving `startConnectServer` with a per-instance `authToken` resolver.
 
 See [Agent-Native](/guide/agent-native) for the API and safety model.
@@ -42,7 +42,7 @@ Devframe spawns a separate RPC + WS server and registers Vite middleware at `<ba
 | `host` | `def.cli?.host ?? 'localhost'` | Bind host for a pinned side-car. |
 | `flags` | — | To `def.setup(ctx, { flags })`. |
 | `auth` | gated (interactive OTP) | `false` to opt out, or a `DevframeAuthHandler` for a custom scheme. |
-| `mcp` | `def.cli?.mcp` | Expose the MCP route at `<base>__mcp`. `true` requires the `DEVFRAME_MCP_AUTH_TOKEN` bearer; `McpRouteOptions` carries an explicit `authorization`. |
+| `mcp` | `def.mcp` | Expose the MCP route at `<base>__mcp`. `true` is origin-only (trusts same-machine callers); `McpRouteOptions` can add an `authorization` identity check. |
 
 ## `devframeVite` — convenience wrapper
 
 
@@ -48,7 +48,7 @@ export const GET = handler.fetch
 | `port` | from `def.cli?.port` | Side-car port. |
 | `flags` | — | Passed to `def.setup(ctx, { flags })`. |
 | `auth` | `false` | `true` for the OTP gate, or a handler. |
-| `mcp` | `def.cli?.mcp` | Expose the MCP route. `true` requires the `DEVFRAME_MCP_AUTH_TOKEN` bearer; `McpRouteOptions` carries an explicit `authorization`. |
+| `mcp` | `def.mcp` | Expose the MCP route. `true` is origin-only (trusts same-machine callers); `McpRouteOptions` can add an `authorization` identity check. |
 | `key` | `@devframes/next:<id>:<base>` | `globalThis` memoization key. |
 
 ## Hosting a hub
@@ -125,7 +125,7 @@ export const POST = (req: Request) => hub.handler(req)
 export const DELETE = (req: Request) => hub.handler(req)
 ```
 
-The aggregate MCP route is off by default — it exposes privileged agent tools. Opt in with an authorization policy: `mcp: true` (requiring the `DEVFRAME_MCP_AUTH_TOKEN` bearer) or `mcp: { authorization }`.
+The aggregate MCP route is off by default. Opt in with `mcp: true` (origin-only, trusting same-machine callers), or `mcp: { authorization }` to add an identity check when the app is reachable beyond localhost.
 
 No native hub UI provider here, so this scope stays quiet; `createDevframeNextHost()` is the low-level `DevframeHost`.
 
 
@@ -0,0 +1,33 @@
+---
+title: 'DF8005: Devframe MCP Ignored While Hub MCP Is Off'
+description: 'Devframe "{id}" requests an MCP route, but the hub''s aggregate MCP is off — its tools are not exposed over MCP.'
+---
+
+## Message
+
+> Devframe "`{id}`" requests an MCP route, but the hub's aggregate MCP is off — its tools are not exposed over MCP.
+
+## Cause
+
+A hub exposes **one aggregate MCP endpoint** over every mounted devframe (tool ids are already namespaced per plugin), so a mounted devframe's own `mcp` setting is ignored — the hub's own `mcp` governs the route. This warning fires when a devframe is mounted with `mcp` enabled (top-level `mcp`, or the deprecated `cli.mcp`) while the hub itself has no `mcp` configured, so that devframe's tools are not reachable over MCP.
+
+## Example
+
+```ts
+initHub({
+  base: DEVFRAMES_HUB_BASE,
+  // No `mcp` here → no aggregate route…
+  devframes: [
+    myDevframe, // …but this devframe declares `mcp: true` → DF8005
+  ],
+})
+```
+
+## Fix
+
+- Enable the hub's own aggregate MCP so the devframe's tools are surfaced: pass `mcp` to `initHub` (`mcp: true` for the loopback origin gate, or `mcp: { authorization }` to add an identity check).
+- Or drop `mcp` from the mounted devframe to silence the warning — it has no effect inside a hub.
+
+## Source
+
+- [`packages/hub/src/node/initiate.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/initiate.ts) — `initHub()` emits this while mounting each devframe when the hub has no MCP but the devframe requests one.
@@ -92,6 +92,7 @@ Emitted by `@devframes/hub` while assembling and mounting the unified surface.
 | [DF8002](/errors/DF8002) | error | Both devframes and context Passed to initHub |
 | [DF8003](/errors/DF8003) | error | connectionMeta() Before Hub Instance Ready |
 | [DF8004](/errors/DF8004) | error | Devframe Id Is Not a Mountable URL Segment |
+| [DF8005](/errors/DF8005) | warning | Devframe MCP Ignored While Hub MCP Is Off |
 
 ## Hub — docks & mounting (DF81xx)
 
 
@@ -17,20 +17,18 @@ export default defineDevframe({
   icon: 'ph:folder-open-duotone',
   basePath: BASE_PATH,
   clientAssets: distDir,
+  // Serve the agent surface over the dev server's `/__mcp` route and register
+  // the instance for `devframe connect` discovery. This demo binds to loopback
+  // (`localhost:9876`), so `mcp: true` (the loopback origin gate, trusting
+  // same-machine callers) is enough - no bearer plumbing. A network-reachable
+  // tool would harden it with `mcp: { authorization: process.env.MY_TOKEN }`.
+  mcp: true,
   cli: {
     command: 'devframe-files-inspector',
     port: 9876,
     // Single-user localhost demo - skip the trust handshake so the served
     // SPA can call RPC without an OTP round-trip.
     auth: false,
-    // Serve the agent surface over the dev server's `/__mcp` route and
-    // register the instance for `devframe connect` discovery. This demo binds
-    // to loopback (`localhost:9876`), so it takes the origin-only opt-out
-    // (`authorization: false`) rather than requiring a bearer - the MCP route
-    // stays reachable to `devframe connect` on the same machine without token
-    // plumbing. A network-reachable tool would set a real bearer instead
-    // (e.g. `authorization: process.env.DEVFRAME_MCP_AUTH_TOKEN`).
-    mcp: { authorization: false },
   },
   setup(ctx) {
     // A scoped context auto-namespaces every registered id with `NAMESPACE:`.
 
@@ -217,11 +217,9 @@ export async function nextDevframeHub(
     // for a bearer token. See `docs/content/1.guide/13.security.md`.
     // The aggregate MCP endpoint at `/__devframes/__mcp` - the hub's agent
     // surface (agent-flagged commands, plugin tools, `devframe:state:read`)
-    // over the same catch-all route as the SPAs. `mcp: true` is the
-    // environment-backed policy: it reads the required bearer from
-    // `DEVFRAME_MCP_AUTH_TOKEN`, so startup fails (DF0077) unless that is set -
-    // the route is never mounted unauthenticated. An MCP client presents that
-    // token as `Authorization: Bearer <token>` alongside a loopback Origin.
+    // over the same catch-all route as the SPAs. `mcp: true` mounts it with
+    // the loopback origin gate (trusting same-machine callers); harden it with
+    // `mcp: { authorization }` when the app is reachable beyond localhost.
     mcp: true,
     // This host renders its own React UI in `app/page.tsx`, so skip the
     // default `@devframes/hub-ui` standalone/embedded slot.