@@ -18,14 +18,16 @@ await createMcpServer(myDevframe, { transport: 'stdio' })
 
 ## Route-based server
 
-The dev server exposes the same MCP API over HTTP, live. Enable with the top-level `mcp`:
+The dev server exposes the same MCP API over HTTP, live. Enable it with `cli.mcp` (or pass `mcp` to `createDevServer` / `initDevframe` / `initHub` when you host it programmatically):
 
 ```ts
 import { defineDevframe } from 'devframe'
 
 export default defineDevframe({
   // …
-  mcp: true,
+  cli: {
+    mcp: true,
+  },
 })
 ```
 
@@ -41,12 +43,14 @@ The **origin gate** guards every request: `Origin` must be loopback (or allow-li
 
 ```ts
 export default defineDevframe({
-  // 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 },
+  cli: {
+    // 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 },
+  },
 })
 ```
 
 
@@ -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.mcp` | Expose the MCP route at `<base>__mcp`. `true` is origin-only (trusts same-machine callers); `McpRouteOptions` can add an `authorization` identity check. |
+| `mcp` | `def.cli?.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.mcp` | Expose the MCP route. `true` is origin-only (trusts same-machine callers); `McpRouteOptions` can add an `authorization` identity check. |
+| `mcp` | `def.cli?.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
 
@@ -17,18 +17,19 @@ 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 `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,
   },
   setup(ctx) {
     // A scoped context auto-namespaces every registered id with `NAMESPACE:`.
 
@@ -95,9 +95,9 @@ export function resolveMcpConfig(mcp: boolean | McpRouteOptions | undefined): Re
 
 /**
  * Resolve the `mcp` entry a `__connection.json` should advertise for a dev
- * server started with the given `mcp` option (falling back to `def.mcp`, then
- * the deprecated `def.cli?.mcp`, exactly like `createDevServer`), or
- * `undefined` when the route is disabled.
+ * server started with the given `mcp` option (falling back to `def.cli?.mcp`,
+ * exactly like `createDevServer`), or `undefined` when the route is
+ * disabled.
  *
  * Hosted bridges that hand-roll their connection meta pass the side-car
  * `port`: the advertised path becomes absolute (the side-car mounts at `/`)
@@ -110,7 +110,7 @@ export function resolveMcpConnectionMeta(
   mcp: boolean | McpRouteOptions | undefined,
   port?: number,
 ): ConnectionMeta['mcp'] {
-  const config = resolveMcpConfig(mcp ?? def.mcp ?? def.cli?.mcp)
+  const config = resolveMcpConfig(mcp ?? def.cli?.mcp)
   if (!config)
     return undefined
   const route = withoutLeadingSlash(config.path ?? DEVFRAME_MCP_ROUTE)
 
@@ -70,9 +70,8 @@ export function createCac(d: DevframeDefinition, options: CreateCacOptions = {})
     .option('--no-auth', 'Disable the interactive authentication gate')
     // Only `--mcp` is declared: CAC's `--no-*` auto-negation would inject a
     // `true` default, silently enabling MCP. Declaring just `--mcp` yields the
-    // opt-in tri-state — absent → `undefined` (falls through to the
-    // definition's `mcp`), `--mcp` → `true`, `--no-mcp` → `false` (handled by
-    // CAC's `--no-` prefix).
+    // opt-in tri-state — absent → `undefined` (falls through to `cli.mcp`),
+    // `--mcp` → `true`, `--no-mcp` → `false` (handled by CAC's `--no-` prefix).
     .option('--mcp', 'Expose an MCP server over HTTP at /__mcp (use --no-mcp to disable)')
 
   // Register typed flags from the definition ahead of `cli.configure`
@@ -96,7 +95,7 @@ export function createCac(d: DevframeDefinition, options: CreateCacOptions = {})
     const port = (flags.port as number | undefined) ?? await resolveDevServerPort(d, { host, defaultPort })
     // `--mcp` / `--no-mcp` map to a boolean override; when neither is
     // passed CAC leaves `mcp` undefined so `createDevServer` falls through
-    // to the definition's `mcp` (top-level, then the deprecated `cli.mcp`).
+    // to `def.cli?.mcp`.
     const mcp = flags.mcp as boolean | undefined
     await createDevServer(d, {
       host,
 
@@ -92,9 +92,9 @@ export interface CreateDevServerOptions {
   auth?: boolean | DevframeAuthHandler
   /**
    * Expose a route-based MCP server on the dev server (Streamable-HTTP).
-   * Overrides the definition's `mcp` (top-level, then the deprecated
-   * `cli.mcp`); `undefined` falls through to it. `false` disables the route
-   * regardless of the definition default. See {@link McpRouteOptions}.
+   * Overrides `def.cli?.mcp`; `undefined` falls through to it. `false`
+   * disables the route regardless of the definition default. See
+   * {@link McpRouteOptions}.
    */
   mcp?: boolean | McpRouteOptions
   /**
 
@@ -89,9 +89,8 @@ export interface InitDevframeOptions {
   auth?: boolean | DevframeAuthHandler
   /**
    * Expose a route-based MCP server (Streamable-HTTP) at `<base>__mcp` and
-   * advertise it in `__connection.json`. Overrides the definition's `mcp`
-   * (top-level, then the deprecated `cli.mcp`); `undefined` falls through to
-   * it. See {@link McpRouteOptions}.
+   * advertise it in `__connection.json`. Overrides `def.cli?.mcp`;
+   * `undefined` falls through to it. See {@link McpRouteOptions}.
    */
   mcp?: boolean | McpRouteOptions
   /**
@@ -309,7 +308,7 @@ export function initDevframe(
       // only pulled in (dynamically) when the route is enabled. The resolved
       // config trusts same-machine callers by default (origin-only); an object
       // config can opt into a bearer/callback identity check.
-      const mcpConfig = resolveMcpConfig(options.mcp ?? def.mcp ?? def.cli?.mcp)
+      const mcpConfig = resolveMcpConfig(options.mcp ?? def.cli?.mcp)
       let mcpMeta: ConnectionMeta['mcp']
       let mcpDispose: (() => Promise<void>) | undefined
       if (mcpConfig) {
 
@@ -106,7 +106,7 @@ export type McpAuthorization
 
 /**
  * Configuration for the route-based MCP server mounted alongside the dev
- * server (opt-in via {@link DevframeDefinition.mcp}). The endpoint speaks
+ * server (opt-in via {@link DevframeCliOptions.mcp}). The endpoint speaks
  * the MCP Streamable-HTTP transport over the same origin as the SPA,
  * exposing the definition's `ctx.agent` tools + shared-state resources to
  * external MCP clients connected to the *running* server.
@@ -184,11 +184,20 @@ export interface DevframeCliOptions {
    */
   auth?: boolean | DevframeAuthHandler
   /**
-   * Expose a route-based MCP server alongside the dev server.
+   * Expose a route-based MCP server alongside the standalone dev server,
+   * speaking the MCP Streamable-HTTP transport at `/__mcp` (relative to the
+   * base path). It surfaces the same `ctx.agent` tools + shared-state
+   * resources as the stdio `mcp` command, but against the live server.
    *
-   * @deprecated Moved to the top-level {@link DevframeDefinition.mcp}. Set
-   * `mcp` on the definition instead. This field is still read as a fallback
-   * when the top-level `mcp` is unset, so existing definitions keep working.
+   * - `false` / omitted (default) — no MCP route is mounted.
+   * - `true` — mount at the default `__mcp` route with the loopback origin
+   *   gate (trusting same-machine callers).
+   * - {@link McpRouteOptions} — customise the route path, origin allow-list,
+   *   and opt into an {@link McpAuthorization} identity check.
+   *
+   * The `--mcp` / `--no-mcp` CLI flags override this per run. Whether to expose
+   * MCP is a hosting decision, so programmatic hosts pass it to
+   * `initDevframe` / `initHub` / `createDevServer` instead.
    */
   mcp?: boolean | McpRouteOptions
   /**
@@ -416,22 +425,6 @@ export interface DevframeDefinition {
    * {@link DevframeCliOptions.distDir} is read as a fallback.
    */
   clientAssets?: StaticAssetsSource
-  /**
-   * Expose a route-based MCP server alongside the running dev server, speaking
-   * the MCP Streamable-HTTP transport at `/__mcp` (relative to the base path).
-   * It surfaces the same `ctx.agent` tools + shared-state resources as the
-   * stdio `mcp` command, but against the live server.
-   *
-   * - `false` / omitted (default) — no MCP route is mounted.
-   * - `true` — mount at the default `__mcp` route with the loopback origin
-   *   gate (trusting same-machine callers).
-   * - {@link McpRouteOptions} — customise the route path, origin allow-list,
-   *   and opt into an {@link McpAuthorization} identity check.
-   *
-   * The `--mcp` / `--no-mcp` CLI flags override this per run. When unset, the
-   * deprecated {@link DevframeCliOptions.mcp} is read as a fallback.
-   */
-  mcp?: boolean | McpRouteOptions
   /** RPC-level configuration for this devframe (see {@link DevframeRpcOptions}). */
   rpc?: DevframeRpcOptions
   /** Server-side setup — the primary entrypoint. Runs in every runtime. */
 
@@ -324,14 +324,14 @@ describe('initHub', () => {
   it('warns (DF8005) when a mounted devframe asks for MCP but the hub MCP is off', async () => {
     const wsPort = await getPort({ port: 18235, host: '127.0.0.1' })
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
-    // The hub has no `mcp`, but `beta` declares `mcp: true` — the hub's single
-    // aggregate route governs MCP, so beta's request is a no-op and warns.
+    // The hub has no `mcp`, but `beta` declares `cli.mcp: true` — the hub's
+    // single aggregate route governs MCP, so beta's request is a no-op and warns.
     const hub = initHub({
       base: DEVFRAMES_HUB_BASE,
       auth: false,
       host: '127.0.0.1',
       ws: { port: wsPort },
-      devframes: [makeFrame('alpha'), { ...makeFrame('beta'), mcp: true }],
+      devframes: [makeFrame('alpha'), { ...makeFrame('beta'), cli: { mcp: true } }],
     })
 
     try {