feat!: move the MCP implementation into the optional @devframes/agentic peer

The MCP implementation, the connect gateway, and the MCP SDK behind them
move out of devframe into the new @devframes/agentic package, an optional
peer of devframe and @devframes/hub. devframe stays slim; installing the
peer is what turns the agent surface on. Users never import agentic:
devframe/adapters/mcp stays the user-facing API and loads the peer lazily.

- @devframes/agentic ships /mcp and /connect entries consumed by devframe's
  loaders; the bare root throws. Signatures are typed against devframe's own
  contract, so no SDK type leaks and the SDK stays swappable.
- The mcp enable matrix: 'auto' mounts iff the agent surface is non-empty
  AND the peer resolves (missing peer: one DF0078 warning per process); an
  explicit setting - or importing devframe/adapters/mcp - throws DF0079
  without the peer; false stays silent.
- devframe/adapters/mcp keeps its exports unchanged, built in its own graph
  so its top-level await cannot reshape the server chunking.
- The peer probe routes through resolveServicePackage (an opaque-parameter
  createRequire), not a literal createRequire(import.meta.url).resolve,
  which turbopack rewrites into a throwing stub inside a bundled Next hub.
- Pure agent projections (to-json-schema, stringify) stay in devframe under
  src/agent/, shared by browser WebMCP and agentic via devframe/internal.
- devframe drops @modelcontextprotocol/server (dep) and /client (optional
  peer); DF0046 now points at @devframes/agentic. The reference hubs install
  the peer, as any consumer wanting MCP now does.

Author: antfubot

alias.ts

@@ -47,7 +47,10 @@ export const alias = {
   'devframe/adapters/build': r('devframe/src/adapters/build.ts'),
   'devframe/adapters/embedded': r('devframe/src/adapters/embedded.ts'),
   'devframe/initiate': r('devframe/src/adapters/initiate.ts'),
-  'devframe/adapters/mcp': r('devframe/src/adapters/mcp/index.ts'),
+  'devframe/adapters/mcp': r('devframe/src/adapters/mcp.ts'),
+  '@devframes/agentic/mcp': r('agentic/src/mcp/index.ts'),
+  '@devframes/agentic/connect': r('agentic/src/connect/index.ts'),
+  '@devframes/agentic': r('agentic/src/index.ts'),
   '@devframes/hub/build': r('hub/src/node/build.ts'),
   '@devframes/hub/client': r('hub/src/client/index.ts'),
   '@devframes/hub/constants': r('hub/src/constants.ts'),

docs/content/1.guide/15.agent-native.md

@@ -100,7 +100,7 @@ Every `ctx.rpc.sharedState` key is exposed as a `devframe://state/<key>` resourc
 
 ## Starting the MCP server
 
-The dev server serves the agent surface over HTTP on its own: the `mcp: 'auto'` default mounts the route at `/__mcp` once anything above exists (an `agent`-flagged RPC, a registered tool or resource) - one flagged function is the whole setup. See the [MCP adapter](/adapters/mcp#route-based-server) for forcing it on or off and hardening the route.
+The dev server serves the agent surface over HTTP on its own: the `mcp: 'auto'` default mounts the route at `/__mcp` once anything above exists (an `agent`-flagged RPC, a registered tool or resource) and the optional [`@devframes/agentic`](/adapters/mcp) peer is installed - one flagged function plus one install is the whole setup. See the [MCP adapter](/adapters/mcp#route-based-server) for forcing it on or off and hardening the route.
 
 For a stdio server instead, via the CLI:
 

docs/content/2.adapters/7.mcp.md

@@ -7,18 +7,24 @@ description: 'Exposes a devframe''s agent-facing API as a Model Context Protocol
 
 Exposes a devframe's agent-facing API as a [Model Context Protocol](https://modelcontextprotocol.io) server: coding agents call flagged RPCs and read resources.
 
+The implementation (and the MCP SDK behind it) lives in **`@devframes/agentic`**, an optional peer of `devframe`: install it to enable the agent surface, and keep importing everything from `devframe/adapters/mcp` - the peer is loaded for you, never imported directly. A devframe without an agent surface ships with neither the peer nor the SDK installed:
+
+```sh
+npm install @devframes/agentic
+```
+
 ```ts
 import { createMcpServer } from 'devframe/adapters/mcp'
 import myDevframe from './my-tool'
 
 await createMcpServer(myDevframe, { transport: 'stdio' })
 ```
 
-`createMcpServer` serves `stdio` through the MCP SDK's `serveStdio`, pinning one server instance per connection.
+`createMcpServer` serves `stdio` through the MCP SDK's `serveStdio`, pinning one server instance per connection. Importing `devframe/adapters/mcp` without the peer installed throws [DF0079](/errors/DF0079).
 
 ## Route-based server
 
-The dev server exposes the same MCP API over HTTP, live. The default setting is **`'auto'`**: the route mounts once the devframe exposes an agent surface (an `agent`-flagged RPC, a registered tool or resource) - flag your first function and the agent view is on. A devframe with nothing flagged mounts no route and loads no MCP code.
+The dev server exposes the same MCP API over HTTP, live. The default setting is **`'auto'`**: the route mounts once the devframe exposes an agent surface (an `agent`-flagged RPC, a registered tool or resource) *and* `@devframes/agentic` is installed - flag your first function, install the peer, and the agent view is on. A devframe with nothing flagged mounts no route and loads no MCP code; an agent surface without the peer warns once ([DF0078](/errors/DF0078)) and mounts nothing, while an explicit `mcp` setting without the peer throws ([DF0079](/errors/DF0079)). `mcp: false` stays silent either way.
 
 Pin the behavior where you host the tool - it's a hosting decision, so pass `mcp` to `createCac` when you assemble the CLI (or to `createDevServer` / `initDevframe` / `initHub` when you host it programmatically): `true` always mounts, `false` never mounts, an object customises the route:
 
@@ -103,6 +109,8 @@ Two gateway tools (`devframe:connect:*` ids; see [tool ids and wire names](/guid
 
 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.
 
-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, since command-line arguments are visible to other processes). Connect to a fleet with distinct credentials by driving `startConnectServer` with a per-instance `authToken` resolver.
+The connector needs the same optional `@devframes/agentic` peer as the adapter; `devframe connect` without it throws [DF0046](/errors/DF0046).
+
+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, since command-line arguments are visible to other processes).
 
 See [Agent-Native](/guide/agent-native) for the API and safety model.

docs/content/6.errors/DF0046.md

@@ -1,25 +1,25 @@
 ---
-title: 'DF0046: Connector Requires the MCP SDK'
-description: 'devframe connect requires the optional peer dependency @modelcontextprotocol/client: {reason}'
+title: 'DF0046: Connector Requires @devframes/agentic'
+description: 'devframe connect requires the optional peer dependency @devframes/agentic: {reason}'
 ---
 
 ## Message
 
-> `devframe connect` requires the optional peer dependency @modelcontextprotocol/client: `{reason}`
+> `devframe connect` requires the optional peer dependency @devframes/agentic: `{reason}`
 
 ## Cause
 
-`devframe connect` was started but `@modelcontextprotocol/client` could not be imported. The client SDK is an optional peer dependency of `devframe`: only the connector dials other instances, so only it needs the package installed.
+`devframe connect` was started but `@devframes/agentic/connect` could not be imported. The connector lives in `@devframes/agentic` (together with the MCP SDK), an optional peer dependency of `devframe`: only agent-facing features need the package installed.
 
 ## Fix
 
-Install the SDK next to devframe and run the connector again:
+Install the package next to devframe and run the connector again:
 
 ```sh
-npm install @modelcontextprotocol/client
+npm install @devframes/agentic
 devframe connect
 ```
 
 ## Source
 
-- [`packages/devframe/src/cli/connect.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/cli/connect.ts): `startConnectServer()` throws this when the dynamic SDK import fails.
+- [`packages/devframe/src/cli/main.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/cli/main.ts): the `connect` subcommand throws this when the dynamic `@devframes/agentic/connect` import fails.

docs/content/6.errors/DF0078.md

@@ -0,0 +1,28 @@
+---
+title: 'DF0078: Agent Surface Without @devframes/agentic'
+description: 'This devframe exposes agent tools, but the MCP endpoint stays off: the optional peer "@devframes/agentic" is not installed.'
+---
+
+## Message
+
+> This devframe exposes agent tools, but the MCP endpoint stays off: the optional peer "@devframes/agentic" is not installed.
+
+## Cause
+
+The devframe (or hub) left a non-empty agent surface (RPC functions with an `agent` field, registered agent tools, resources, or providers) and the `mcp` setting is the omitted `'auto'` default, which would mount the MCP route. But `@devframes/agentic`, the optional peer carrying the MCP adapter and the MCP SDK, is not installed, so no route can be served.
+
+The warning is reported once per process; the instance keeps running without an MCP endpoint.
+
+## Fix
+
+Install the peer so the agent surface is served over MCP:
+
+```sh
+npm install @devframes/agentic
+```
+
+Or, if the tools should deliberately stay unexposed, set `mcp: false` to opt out silently.
+
+## Source
+
+- [`packages/devframe/src/adapters/_shared.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/_shared.ts): `loadAutoMcpAdapter()` reports this (once) when the agent surface is non-empty but the peer probe fails.

docs/content/6.errors/DF0079.md

@@ -0,0 +1,26 @@
+---
+title: 'DF0079: MCP Enabled Without @devframes/agentic'
+description: 'The mcp option is enabled, but the optional peer "@devframes/agentic" could not be loaded: {reason}'
+---
+
+## Message
+
+> The `mcp` option is enabled, but the optional peer "@devframes/agentic" could not be loaded: `{reason}`
+
+## Cause
+
+An explicit `mcp` setting (`true`, a route options object, the `--mcp` flag, or the `mcp` CLI subcommand) asked for an MCP surface - or `devframe/adapters/mcp` was imported directly - but the implementation could not be loaded from the optional `@devframes/agentic` peer, typically because it is not installed. Unlike the omitted `'auto'` default (which degrades to a one-time [DF0078](/errors/DF0078) warning), an explicit opt-in fails fast rather than silently running without MCP.
+
+## Fix
+
+Install the peer next to devframe:
+
+```sh
+npm install @devframes/agentic
+```
+
+Or remove the explicit `mcp` setting (or pass `mcp: false`) if the endpoint isn't wanted. The underlying import error is attached as `cause`.
+
+## Source
+
+- [`packages/devframe/src/node/agentic.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/agentic.ts): `importAgenticMcp()` maps a failed load of `@devframes/agentic/mcp` to this error.

docs/content/6.errors/index.md

@@ -54,7 +54,7 @@ Emitted by `devframe`: the framework-neutral host, RPC, streaming, assets, servi
 | [DF0043](/errors/DF0043) | error | Invalid RPC Argument |
 | [DF0044](/errors/DF0044) | error | Invalid RPC Return Value |
 | [DF0045](/errors/DF0045) | warn | Instance Registry Update Failed |
-| [DF0046](/errors/DF0046) | error | Connector Requires the MCP SDK |
+| [DF0046](/errors/DF0046) | error | Connector Requires @devframes/agentic |
 | [DF0047](/errors/DF0047) | warn | Agent Tool Wire-Name Collision |
 | [DF0048](/errors/DF0048) | error | Unknown Shared-State Key |
 | [DF0049](/errors/DF0049) | error | Connector Call Requires Port and Tool |
@@ -84,6 +84,8 @@ Emitted by `devframe`: the framework-neutral host, RPC, streaming, assets, servi
 | [DF0075](/errors/DF0075) | warn | No RPC Transport On This Runtime |
 | [DF0076](/errors/DF0076) | error | WebSocket Upgrade Unsupported On This Runtime |
 | [DF0077](/errors/DF0077) | error | In-Page Channel Function Not Registered |
+| [DF0078](/errors/DF0078) | warn | Agent Surface Without @devframes/agentic |
+| [DF0079](/errors/DF0079) | error | MCP Enabled Without @devframes/agentic |
 
 ## Hub: context & lifecycle (DF80xx)
 

docs/content/7.migrations/1.migration-0.9.md

@@ -5,6 +5,21 @@ description: '0.9 removes the compatibility shims deprecated across the 0.7 seri
 
 0.9 removes the compatibility shims deprecated across the 0.7 series and trims the public API of `devframe` and `@devframes/hub`. Each change has a drop-in replacement. It also moves the [MCP](/adapters/mcp) surface to the stateless [MCP 2026-07-28 protocol](https://modelcontextprotocol.io/specification/2026-07-28). The devframe API is unchanged; see [The MCP endpoints are stateless](#the-mcp-endpoints-are-stateless).
 
+Late in the 0.9 series the MCP implementation moved into the new optional peer `@devframes/agentic`; see [MCP requires `@devframes/agentic`](#mcp-requires-devframesagentic).
+
+## MCP requires `@devframes/agentic`
+
+The MCP implementation and the MCP SDK moved out of `devframe` into `@devframes/agentic`, an **optional peer**: install it to serve agent tools over MCP, skip it for a slimmer install without an MCP surface. Your imports do not change - `devframe/adapters/mcp` stays the user-facing API and loads the peer for you; `@devframes/agentic` is never imported directly.
+
+> [!WARNING]
+> This is a behavior change within the 0.9 series: `devframe` no longer depends on the MCP SDK, so MCP now requires `@devframes/agentic` to be installed. Without it, the omitted `'auto'` default warns once ([DF0078](/errors/DF0078)) and mounts nothing; an explicit `mcp` setting - and importing `devframe/adapters/mcp` itself - throws ([DF0079](/errors/DF0079)); `mcp: false` stays silent.
+
+```sh
+npm install @devframes/agentic
+```
+
+The `devframe/adapters/mcp` exports are unchanged: `createMcpServer`, `createMcpFetchHandler`, `mountMcpHttp`, and their option types (the types are also importable from `devframe/types`). `devframe connect` needs the peer too and throws [DF0046](/errors/DF0046) without it, replacing the former `@modelcontextprotocol/client` optional peer.
+
 ## `devframe/adapters/cli` is removed
 
 The `devframe/adapters/cli` entry is gone; import from `devframe/adapters/cac`:

examples/custom-hub-next/package.json

@@ -12,6 +12,7 @@
   },
   "dependencies": {
     "@antfu/design": "catalog:frontend",
+    "@devframes/agentic": "workspace:*",
     "@devframes/hub": "workspace:*",
     "@devframes/json-render": "workspace:*",
     "@devframes/json-render-ui": "workspace:*",

examples/custom-hub-vite/package.json

@@ -12,6 +12,7 @@
   },
   "dependencies": {
     "@antfu/design": "catalog:frontend",
+    "@devframes/agentic": "workspace:*",
     "@devframes/hub": "workspace:*",
     "@devframes/json-render": "workspace:*",
     "@devframes/json-render-ui": "workspace:*",