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

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