feat(mcp): add instructions to the mcp route options

The MCP initialize result can carry instructions that an MCP client adds to
the context of the coding agent. The mcp route options, createMcpServer,
createMcpFetchHandler and the Next.js host now take instructions, and both
mounts (initDevframe and initHub) send them in the initialize result.
Omitted or empty instructions send nothing.

Author: erkamyaman

docs/content/1.guide/18.hub-initiate.md

@@ -89,7 +89,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 mounts through the `'auto'` default once any mounted devframe (or an agent-flagged hub command) exposes agent tools; `mcp: true` forces it on, `mcp: false` off. It has its own origin gate, independent of this RPC Auth: the mounted route trusts same-machine callers, and `mcp: { authorization }` adds an identity check when the hub is reachable beyond loopback. `mcp: { exposeSharedState }` takes `false` or a `(key) => boolean` filter to choose which shared-state keys agents can read through `devframe_state_read` and `devframe://state/<key>`. The hub exposes one aggregate route over every mounted devframe's tools.
+The aggregate MCP route mounts through the `'auto'` default once any mounted devframe (or an agent-flagged hub command) exposes agent tools; `mcp: true` forces it on, `mcp: false` off. It has its own origin gate, independent of this RPC Auth: the mounted route trusts same-machine callers, and `mcp: { authorization }` adds an identity check when the hub is reachable beyond loopback. `mcp: { exposeSharedState }` takes `false` or a `(key) => boolean` filter to choose which shared-state keys agents can read through `devframe_state_read` and `devframe://state/<key>`. `mcp: { instructions }` sets the usage guidance that the route sends in the MCP `initialize` result. The hub exposes one aggregate route over every mounted devframe's tools.
 
 ## Singular vs hub mounting
 

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

@@ -69,6 +69,18 @@ devframeViteBridge(myDevframe, {
 })
 ```
 
+### Telling coding agents how to use the tools
+
+`instructions` on the route options is a short text that the MCP server sends in its `initialize` result (and in the `server/discover` result of the 2026-07-28 revision). An MCP client can add it to the context of the coding agent. Use it for guidance that applies to every tool, for example which tool to call first. Without `instructions`, the handshake carries none.
+
+```ts
+devframeViteBridge(myDevframe, {
+  mcp: { instructions: 'Call my-tool_list-sessions first, then pass a session id to the other tools.' },
+})
+```
+
+`createMcpServer` and `createMcpFetchHandler` take the same `instructions` option.
+
 ### Hosted bridges
 
 Both bridges forward the setting to their side-car dev server, advertising the mounted endpoint in `__connection.json`:

packages/agentic/src/mcp/__tests__/mcp-server.test.ts

@@ -13,13 +13,14 @@ function nullHost(): DevframeHost {
   }
 }
 
-async function bootPair(exposeSharedState: boolean | ((key: string) => boolean) = true) {
+async function bootPair(exposeSharedState: boolean | ((key: string) => boolean) = true, instructions?: string) {
   const ctx = await createHostContext({ cwd: process.cwd(), mode: 'dev', host: nullHost() })
 
   const server = buildMcpServerFromContext(ctx, {
     serverName: 'test',
     serverVersion: '0.0.0-test',
     exposeSharedState,
+    instructions,
   })
 
   const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair()
@@ -39,6 +40,26 @@ async function bootPair(exposeSharedState: boolean | ((key: string) => boolean)
 }
 
 describe('mcp adapter (in-memory)', () => {
+  it('sends the server instructions in the handshake', async () => {
+    const { client, cleanup } = await bootPair(true, 'Call greet first.')
+    try {
+      expect(client.getInstructions()).toBe('Call greet first.')
+    }
+    finally {
+      await cleanup()
+    }
+  })
+
+  it('sends no instructions when none are set', async () => {
+    const { client, cleanup } = await bootPair()
+    try {
+      expect(client.getInstructions()).toBeUndefined()
+    }
+    finally {
+      await cleanup()
+    }
+  })
+
   it('lists tools registered via ctx.agent.registerTool', async () => {
     const { ctx, client, cleanup } = await bootPair()
     try {

packages/agentic/src/mcp/build-server.ts

@@ -15,6 +15,8 @@ export interface BuildMcpServerOptions {
   serverName: string
   serverVersion: string
   exposeSharedState: boolean | ((k: string) => boolean)
+  /** Sent as `instructions` in the `initialize` / `server/discover` result. */
+  instructions?: string
 }
 
 /**
@@ -43,6 +45,7 @@ export function buildMcpServerFromContext(
         tools: { listChanged: true },
         resources: { listChanged: true },
       },
+      ...(options.instructions ? { instructions: options.instructions } : {}),
     },
   )
 
@@ -121,6 +124,7 @@ export async function createMcpServer(
     serverName: options.serverName ?? `${definition.id} (devframe)`,
     serverVersion: options.serverVersion ?? definition.version ?? '0.0.0',
     exposeSharedState: options.exposeSharedState ?? true,
+    instructions: options.instructions,
   }
 
   // `serveStdio` pins ONE instance for the connection's lifetime. Each pinned

packages/agentic/src/mcp/fetch.ts

@@ -77,6 +77,7 @@ export function createMcpFetchHandler(
     serverName: options.serverName,
     serverVersion: options.serverVersion,
     exposeSharedState: options.exposeSharedState,
+    instructions: options.instructions,
   }))
 
   // A single, long-lived bridge from devframe's change events onto the

packages/devframe/src/adapters/__tests__/initiate.test.ts

@@ -360,6 +360,39 @@ describe('adapters/handler', () => {
     }
   })
 
+  it('mcp: instructions reach the client in the initialize result', async () => {
+    const wsPort = await getPort({ port: 18145, host: '127.0.0.1' })
+    const devtools = initDevframe(defineTestDef('handler-mcp-instructions'), {
+      base: '/__handler-mcp-instructions/',
+      auth: false,
+      mcp: { instructions: 'Call list-pages first.' },
+      ws: { port: wsPort },
+    })
+
+    try {
+      await devtools.ready
+      const res = await devtools.handler(new Request('http://localhost:3000/__handler-mcp-instructions/__mcp', {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'accept': 'application/json, text/event-stream',
+          'origin': 'http://localhost:3000',
+        },
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          id: 1,
+          method: 'initialize',
+          params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'test', version: '0.0.0' } },
+        }),
+      }))
+      expect(res.status).toBe(200)
+      expect(await res.text()).toContain('"instructions":"Call list-pages first."')
+    }
+    finally {
+      await devtools.close()
+    }
+  })
+
   // The `'auto'` default: an omitted `mcp` mounts the route exactly when
   // `setup()` left a non-empty agent surface.
   function defineAgentTestDef(id: string) {

packages/devframe/src/adapters/_shared.ts

@@ -70,6 +70,8 @@ export interface ResolvedMcpConfig {
   allowedOrigins?: readonly string[] | false
   /** Shared-state exposure from the route options; omitted means every key. */
   exposeSharedState?: boolean | ((key: string) => boolean)
+  /** Handshake `instructions` from the route options; omitted means none. */
+  instructions?: string
   /** The resolved identity policy: a bearer token, callback, or `false`. */
   authorization: McpAuthorization
 }
@@ -99,6 +101,7 @@ export function resolveMcpConfig(mcp: McpSetting | undefined): ResolvedMcpConfig
     ...(mcp.path !== undefined ? { path: mcp.path } : {}),
     ...(mcp.allowedOrigins !== undefined ? { allowedOrigins: mcp.allowedOrigins } : {}),
     ...(mcp.exposeSharedState !== undefined ? { exposeSharedState: mcp.exposeSharedState } : {}),
+    ...(mcp.instructions !== undefined ? { instructions: mcp.instructions } : {}),
     authorization,
   }
 }

packages/devframe/src/adapters/initiate.ts

@@ -380,6 +380,7 @@ async function mountMcpRoute(
     serverName: `${def.id} (devframe)`,
     serverVersion: def.version ?? '0.0.0',
     exposeSharedState: config.exposeSharedState ?? true,
+    instructions: config.instructions,
     authorization: config.authorization,
     allowedOrigins: config.allowedOrigins,
   })

packages/devframe/src/types/devframe.ts

@@ -174,6 +174,13 @@ export interface McpRouteOptions {
    * The states themselves stay available to the UI over RPC.
    */
   exposeSharedState?: boolean | ((key: string) => boolean)
+  /**
+   * Usage guidance for the route, sent as `instructions` in the MCP
+   * `initialize` (and `server/discover`) result. An MCP client can add it to
+   * the coding agent's context, for example to say which tool to call first.
+   * Omitted or empty sends no instructions.
+   */
+  instructions?: string
 }
 
 export interface DevframeCliOptions {

packages/devframe/src/types/mcp.ts

@@ -25,6 +25,11 @@ export interface CreateMcpServerOptions {
    * - `(key) => boolean`: filter
    */
   exposeSharedState?: boolean | ((key: string) => boolean)
+  /**
+   * Usage guidance sent as `instructions` in the MCP `initialize` (and
+   * `server/discover`) result. Omitted or empty sends no instructions.
+   */
+  instructions?: string
   /** Override the name reported in the MCP handshake. */
   serverName?: string
   /** Override the version reported in the MCP handshake. Defaults to `definition.version ?? '0.0.0'`. */
@@ -44,6 +49,8 @@ export interface CreateMcpFetchHandlerOptions {
   serverVersion: string
   /** Expose shared-state keys as MCP resources; see {@link CreateMcpServerOptions.exposeSharedState}. */
   exposeSharedState: boolean | ((key: string) => boolean)
+  /** Usage guidance for the handshake; see {@link CreateMcpServerOptions.instructions}. */
+  instructions?: string
   /**
    * Optional identity check, layered on top of the origin gate and checked
    * **after** it: a bearer token string (matched in constant time against