@nifrajs/mcp 2.4.0 → 2.6.0

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,OAAO,EAEb,MAAM,eAAe,CAAA;AACtB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;IACnC,6FAA6F;IAC7F,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,SAAS,EAAE,CAAA;IACvC,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,WAAW,EAAE,CAAA;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,SAAS,EAAE,CAAA;IACvC,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,sDAAsD;IACtD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;IACtD,qGAAqG;IACrG,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC1C,mGAAmG;IACnG,MAAM,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAA;CACjE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,SAAS,CAwBvE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,OAAO,EAEb,MAAM,eAAe,CAAA;AACtB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,OAAO,EAAE,CAAA;IACnC,6FAA6F;IAC7F,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,SAAS,EAAE,CAAA;IACvC,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,WAAW,EAAE,CAAA;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,SAAS,EAAE,CAAA;IACvC,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,sDAAsD;IACtD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,wGAAwG;IACxG,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B;uEACmE;IACnE,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC5C;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;IACtD,qGAAqG;IACrG,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC1C,mGAAmG;IACnG,MAAM,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAA;CACjE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,SAAS,CA0BvE"}

package/dist/server.js

@@ -32,6 +32,7 @@ export function createMcpServer(opts) {
         ...(resources.length > 0 ? { resources } : {}),
         ...(opts.prompts !== undefined ? { prompts: opts.prompts } : {}),
         ...(widgets.length > 0 ? { ui: { mimeTypes: [UI_MIME] } } : {}),
+        ...(opts.instructions !== undefined ? { instructions: opts.instructions } : {}),
     };
     return {
         tools,
@@ -41,6 +42,7 @@ export function createMcpServer(opts) {
             features,
             ...(opts.health !== undefined ? { health: opts.health } : {}),
             ...(opts.maxBodyBytes !== undefined ? { maxBodyBytes: opts.maxBodyBytes } : {}),
+            ...(opts.allowedOrigins !== undefined ? { allowedOrigins: opts.allowedOrigins } : {}),
         }),
         handle: (message) => handleRpc(message, tools, serverInfo, features),
     };

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,EACL,SAAS,EAOT,OAAO,GACR,MAAM,eAAe,CAAA;AA4BtB,MAAM,UAAU,eAAe,CAAC,IAA4B;IAC1D,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAA;IACrC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAA;IAClC,sGAAsG;IACtG,gDAAgD;IAChD,MAAM,SAAS,GAAkB,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,CAAA;IAC/F,MAAM,UAAU,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAA;IAC7D,MAAM,QAAQ,GAAsB;QAClC,GAAG,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChE,CAAA;IACD,OAAO;QACL,KAAK;QACL,QAAQ;QACR,UAAU;QACV,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE,CACjB,cAAc,CAAC,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE;YACzC,QAAQ;YACR,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7D,GAAG,CAAC,IAAI,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChF,CAAC;QACJ,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,CAAC;KACrE,CAAA;AACH,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,EACL,SAAS,EAOT,OAAO,GACR,MAAM,eAAe,CAAA;AAiCtB,MAAM,UAAU,eAAe,CAAC,IAA4B;IAC1D,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAA;IACrC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAA;IAClC,sGAAsG;IACtG,gDAAgD;IAChD,MAAM,SAAS,GAAkB,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,CAAA;IAC/F,MAAM,UAAU,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAA;IAC7D,MAAM,QAAQ,GAAsB;QAClC,GAAG,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,GAAG,CAAC,IAAI,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChF,CAAA;IACD,OAAO;QACL,KAAK;QACL,QAAQ;QACR,UAAU;QACV,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE,CACjB,cAAc,CAAC,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE;YACzC,QAAQ;YACR,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7D,GAAG,CAAC,IAAI,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/E,GAAG,CAAC,IAAI,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACtF,CAAC;QACJ,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,CAAC;KACrE,CAAA;AACH,CAAC"}

package/dist/tool.d.ts

@@ -6,7 +6,7 @@
  * `widget` is passed, the tool advertises it via `_meta.ui.resourceUri` on both `tools/list` and each
  * `tools/call` result, so the host knows to render the widget - see {@link ../protocol.ts}.
  */
-import type { McpContentBlock, McpTool, McpToolContext } from "./protocol.js";
+import type { McpContentBlock, McpTool, McpToolAnnotations, McpToolContext } from "./protocol.js";
 import type { InferOutput, StandardSchemaV1 } from "./standard.js";
 import type { McpWidget } from "./widget.js";
 /** The ergonomic result an MCP-tool handler may return (coerced to the protocol's {@link McpToolResult}). */
@@ -45,6 +45,9 @@ export interface DefineMcpToolOptions<S extends StandardSchemaV1 = UntypedArgs>
      * whose schemas carry no JSON Schema, so the agent still sees real parameter docs.
      */
     readonly inputSchema?: Record<string, unknown>;
+    /** MCP tool safety hints (`readOnlyHint`/`destructiveHint`/…) surfaced in `tools/list`. Hosts use
+     * them to decide confirmation UX, and connector directory reviews expect every tool to carry them. */
+    readonly annotations?: McpToolAnnotations;
     /** Link a widget so the tool's result renders as interactive UI in MCP Apps hosts (iframe). */
     readonly widget?: McpWidget;
     /** Render-intent for generative hosts that build their own themed UI from `structuredContent`. Lands

package/dist/tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,EAAiB,MAAM,eAAe,CAAA;AAC5F,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAElE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C,6GAA6G;AAC7G,MAAM,MAAM,oBAAoB,GAC5B,MAAM,GACN;IACE,yFAAyF;IACzF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,kDAAkD;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,eAAe,EAAE,CAAA;IAC7C,gFAAgF;IAChF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAC3B,CAAA;AAEL;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACnB,OAAO,GACP,MAAM,GACN,OAAO,GACP,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEjB,6FAA6F;AAC7F,KAAK,WAAW,GAAG,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAErE,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,gBAAgB,GAAG,WAAW;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IAClB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9C,+FAA+F;IAC/F,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;IAC3B;;0CAEsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B,QAAQ,CAAC,OAAO,EAAE,CAChB,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EACpB,OAAO,EAAE,cAAc,KACpB,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;CAC1D;AAgCD,wBAAgB,aAAa,CAAC,CAAC,SAAS,gBAAgB,GAAG,WAAW,EACpE,IAAI,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC5B,OAAO,CA2BT"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,OAAO,EACP,kBAAkB,EAClB,cAAc,EAEf,MAAM,eAAe,CAAA;AACtB,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAElE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C,6GAA6G;AAC7G,MAAM,MAAM,oBAAoB,GAC5B,MAAM,GACN;IACE,yFAAyF;IACzF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,kDAAkD;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,eAAe,EAAE,CAAA;IAC7C,gFAAgF;IAChF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAC3B,CAAA;AAEL;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACnB,OAAO,GACP,MAAM,GACN,OAAO,GACP,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEjB,6FAA6F;AAC7F,KAAK,WAAW,GAAG,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAErE,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,gBAAgB,GAAG,WAAW;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IAClB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9C;0GACsG;IACtG,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAA;IACzC,+FAA+F;IAC/F,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;IAC3B;;0CAEsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B,QAAQ,CAAC,OAAO,EAAE,CAChB,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EACpB,OAAO,EAAE,cAAc,KACpB,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;CAC1D;AAgCD,wBAAgB,aAAa,CAAC,CAAC,SAAS,gBAAgB,GAAG,WAAW,EACpE,IAAI,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC5B,OAAO,CA4BT"}

package/dist/tool.js

@@ -46,6 +46,7 @@ export function defineMcpTool(opts) {
         inputSchema: opts.inputSchema ??
             (input !== undefined ? jsonSchemaOf(input) : undefined) ??
             EMPTY_OBJECT_SCHEMA,
+        ...(opts.annotations !== undefined ? { annotations: opts.annotations } : {}),
         ...(meta !== undefined ? { _meta: meta } : {}),
         handler: async (args, context) => {
             let validated = args;

package/dist/tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/mcp",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "Build MCP servers - and MCP Apps (interactive `ui://` widgets, SEP-1865) - for a nifra app. The transport-agnostic JSON-RPC core (also used by `@nifrajs/cli`'s dev MCP), a Streamable-HTTP handler you mount at `POST /mcp`, and `defineMcpWidget`/`defineMcpTool` for tool results that render real UI in MCP hosts.",
   "keywords": [
     "bun",

package/src/http.ts

@@ -10,15 +10,45 @@
 import {
   handleRpc,
   type JsonRpcRequest,
+  type JsonRpcResponse,
+  MCP_ERROR,
   type McpServerFeatures,
   type McpTool,
+  modernVersionOf,
   rpcError,
 } from "./protocol.ts"
 
-const CORS: Record<string, string> = {
-  "access-control-allow-origin": "*",
+// Headers on every response. `access-control-allow-headers` lists the request headers a browser MCP client
+// (claude.ai, ChatGPT) actually sends: `mcp-protocol-version` (required per POST since 2025-06-18),
+// `mcp-method`/`mcp-name` (the 2026-07-28 request-metadata mirror), `authorization` (OAuth-protected hosts),
+// plus `accept`/`last-event-id`. Omit any and the CORS preflight fails, so the connector never loads.
+const CORS_BASE: Record<string, string> = {
   "access-control-allow-methods": "POST, GET, OPTIONS",
-  "access-control-allow-headers": "content-type",
+  "access-control-allow-headers":
+    "content-type, authorization, mcp-protocol-version, mcp-session-id, mcp-method, mcp-name, accept, last-event-id",
+  "access-control-expose-headers": "mcp-protocol-version, mcp-session-id",
+  "access-control-max-age": "86400",
+}
+
+/**
+ * Resolve the CORS/Origin headers for one request against the host's `allowedOrigins` policy, or `null`
+ * when the request's `Origin` is present but not allowed - the caller then answers 403, per the
+ * Streamable-HTTP DNS-rebinding rule ("Servers MUST validate the `Origin` header ... respond with 403").
+ * With no policy (the default) every origin is allowed and reflected as `*` - correct for a public,
+ * secret-free, unauthenticated server, whose browser clients send arbitrary origins we can't enumerate.
+ */
+function corsFor(
+  request: Request,
+  allowedOrigins: readonly string[] | undefined,
+): Record<string, string> | null {
+  if (allowedOrigins === undefined) return { ...CORS_BASE, "access-control-allow-origin": "*" }
+  const origin = request.headers.get("origin")
+  // A caller with no Origin (curl, server-to-server) can't mount a DNS-rebinding attack - allow it.
+  if (origin === null) return { ...CORS_BASE, vary: "Origin" }
+  if (allowedOrigins.includes(origin)) {
+    return { ...CORS_BASE, "access-control-allow-origin": origin, vary: "Origin" }
+  }
+  return null
 }
 
 const DEFAULT_MAX_BODY_BYTES = 1_000_000
@@ -31,6 +61,12 @@ export interface McpHttpOptions {
   readonly features?: McpServerFeatures
   /** Shown on the GET health page so each host can describe itself. */
   readonly health?: string
+  /**
+   * Origin allowlist for the DNS-rebinding guard. Omit (the default) to allow any origin - the right
+   * choice for a public, unauthenticated docs server that can't enumerate its browser clients' origins.
+   * Set it (e.g. a localhost origin for a hardened local host) to reject any other browser origin with 403.
+   */
+  readonly allowedOrigins?: readonly string[]
 }
 
 function parseContentLength(value: string): number | undefined {
@@ -86,10 +122,69 @@ async function readJsonBounded(
   }
 }
 
+const SENTINEL_PREFIX = "=?base64?"
+const SENTINEL_SUFFIX = "?="
+
+/** Decode the Streamable-HTTP `=?base64?...?=` header sentinel (used when a name/uri isn't header-safe).
+ * A plain value passes through; a malformed sentinel is returned as-is so validation still fails closed. */
+function decodeSentinel(value: string | null): string | null {
+  if (value === null) return null
+  if (!value.startsWith(SENTINEL_PREFIX) || !value.endsWith(SENTINEL_SUFFIX)) return value
+  const encoded = value.slice(SENTINEL_PREFIX.length, value.length - SENTINEL_SUFFIX.length)
+  try {
+    return TEXT_DECODER.decode(Uint8Array.from(atob(encoded), (ch) => ch.charCodeAt(0)))
+  } catch {
+    return value
+  }
+}
+
+/** Validate a modern (2026-07-28) request's mirrored headers against its body: `MCP-Protocol-Version`,
+ * `Mcp-Method`, and - for name-bearing methods - `Mcp-Name` MUST match, else a `HeaderMismatch` the caller
+ * returns as 400. Stops an intermediary from routing on a header while the server acts on a different body. */
+function modernHeaderMismatch(
+  request: Request,
+  message: JsonRpcRequest,
+  bodyVersion: string,
+): JsonRpcResponse | null {
+  const rid = message.id ?? null
+  const headerVersion = request.headers.get("mcp-protocol-version")
+  if (headerVersion === null || headerVersion !== bodyVersion) {
+    return rpcError(
+      rid,
+      MCP_ERROR.HEADER_MISMATCH,
+      "MCP-Protocol-Version header missing or mismatched",
+    )
+  }
+  const method = typeof message.method === "string" ? message.method : ""
+  const headerMethod = request.headers.get("mcp-method")
+  if (headerMethod === null || headerMethod !== method) {
+    return rpcError(rid, MCP_ERROR.HEADER_MISMATCH, "Mcp-Method header missing or mismatched")
+  }
+  if (method === "tools/call" || method === "resources/read" || method === "prompts/get") {
+    const bodyName = method === "resources/read" ? message.params?.uri : message.params?.name
+    const headerName = decodeSentinel(request.headers.get("mcp-name"))
+    if (headerName === null || typeof bodyName !== "string" || headerName !== bodyName) {
+      return rpcError(rid, MCP_ERROR.HEADER_MISMATCH, "Mcp-Name header missing or mismatched")
+    }
+  }
+  return null
+}
+
+/** HTTP status for a modern request's dispatch result: 400 for version/header errors, 404 for an unknown
+ * method, 200 otherwise (in-band tool errors are ordinary JSON-RPC results and stay 200). */
+function modernErrorStatus(response: JsonRpcResponse): number {
+  if (!("error" in response)) return 200
+  const { code } = response.error
+  if (code === MCP_ERROR.UNSUPPORTED_VERSION || code === MCP_ERROR.HEADER_MISMATCH) return 400
+  return code === -32601 ? 404 : 200
+}
+
 /**
  * Handle one MCP request over HTTP against the given `tools`/`features`. POST a JSON-RPC body → JSON-RPC
  * response; GET → a plain-text health page; OPTIONS → CORS preflight. Never throws - a bad body becomes a
- * JSON-RPC parse error. The dispatch is the shared, transport-agnostic {@link handleRpc}.
+ * JSON-RPC parse error. Dual-era: a modern (2026-07-28) POST that mirrors its method/name/version into
+ * headers is validated against the body before dispatch and gets spec HTTP statuses; legacy requests are
+ * served unchanged. The dispatch is the shared, transport-agnostic {@link handleRpc}.
  */
 export async function respondMcpHttp(
   request: Request,
@@ -97,18 +192,33 @@ export async function respondMcpHttp(
   serverInfo: { name: string; version: string },
   options: McpHttpOptions = {},
 ): Promise<Response> {
-  if (request.method === "OPTIONS") return new Response(null, { status: 204, headers: CORS })
+  const cors = corsFor(request, options.allowedOrigins)
+  if (cors === null) {
+    // Origin present but not allowlisted: reject before the body is ever read (DNS-rebinding guard). No
+    // `id` (no request parsed) and no CORS headers - a disallowed origin gets nothing to work with.
+    return Response.json(rpcError(null, -32600, "origin not allowed"), { status: 403 })
+  }
+  if (request.method === "OPTIONS") return new Response(null, { status: 204, headers: cors })
   if (request.method === "GET") {
+    // The 2026-07-28 revision removed the GET SSE stream; a client probing for it (`Accept:
+    // text/event-stream`) gets 405 so its transport fallback fires. A plain browser/monitor GET still
+    // gets the human-readable health page.
+    if ((request.headers.get("accept") ?? "").includes("text/event-stream")) {
+      return new Response("event stream not supported", {
+        status: 405,
+        headers: { allow: "POST, GET", ...cors },
+      })
+    }
     return new Response(
       options.health ??
         "MCP server - POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call).",
-      { headers: { "content-type": "text/plain; charset=utf-8", ...CORS } },
+      { headers: { "content-type": "text/plain; charset=utf-8", ...cors } },
     )
   }
   if (request.method !== "POST") {
     return new Response("method not allowed", {
       status: 405,
-      headers: { allow: "POST, GET", ...CORS },
+      headers: { allow: "POST, GET", ...cors },
     })
   }
   const parsed = await readJsonBounded(request, options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES)
@@ -116,16 +226,27 @@ export async function respondMcpHttp(
     if (parsed.status === 413) {
       return Response.json(rpcError(null, -32000, "payload too large"), {
         status: 413,
-        headers: CORS,
+        headers: cors,
       })
     }
-    return Response.json(rpcError(null, -32700, "parse error"), { status: 400, headers: CORS })
+    return Response.json(rpcError(null, -32700, "parse error"), { status: 400, headers: cors })
   }
   const message = parsed.value as JsonRpcRequest
+  const bodyVersion = modernVersionOf(message.params)
+  // Mirror the protocol version back for intermediaries (SHOULD, 2025-06-18+); absent is fine.
+  const echoVersion = request.headers.get("mcp-protocol-version")
+  const headers = echoVersion !== null ? { ...cors, "mcp-protocol-version": echoVersion } : cors
+  if (bodyVersion !== undefined) {
+    // Modern request: header/body mirror MUST agree. Reject divergence with 400 before dispatch.
+    const headerError = modernHeaderMismatch(request, message, bodyVersion)
+    if (headerError !== null) return Response.json(headerError, { status: 400, headers })
+  }
   const response = await handleRpc(message, tools, serverInfo, options.features ?? {}, {
     signal: request.signal,
   })
-  // A notification (no id) yields null - acknowledge with 204, no body.
-  if (response === null) return new Response(null, { status: 204, headers: CORS })
-  return Response.json(response, { headers: CORS })
+  // A notification (no id) yields null - acknowledge with 202 Accepted and no body (Streamable-HTTP).
+  if (response === null) return new Response(null, { status: 202, headers })
+  // Modern requests carry spec HTTP statuses (400 version/header, 404 unknown method); legacy stays 200.
+  const status = bodyVersion !== undefined ? modernErrorStatus(response) : 200
+  return Response.json(response, { status, headers })
 }

package/src/protocol.ts

@@ -10,7 +10,28 @@
  * it is additive - a tool whose handler returns a plain `string` behaves exactly as before.
  */
 
-export const PROTOCOL_VERSION = "2024-11-05"
+/** The protocol revision this server advertises by default. A handshake-era version - the HTTP transport
+ * still uses `initialize`; current clients reach it through their backward-compatibility fallback.
+ * `initialize` echoes the client's own requested version instead when it's one this server also speaks
+ * ({@link SUPPORTED_PROTOCOL_VERSIONS}). */
+export const PROTOCOL_VERSION = "2025-06-18"
+/** The handshake-era revisions this server speaks. `initialize` echoes the client's requested
+ * `protocolVersion` when it's in this set (the smoothest negotiation), else answers {@link PROTOCOL_VERSION}. */
+const SUPPORTED_PROTOCOL_VERSIONS = new Set([
+  "2024-11-05",
+  "2025-03-26",
+  "2025-06-18",
+  "2025-11-25",
+])
+
+/** The stateless per-request revision (2026-07-28+). A request carrying its version in `_meta`
+ * (`io.modelcontextprotocol/protocolVersion`) is served in modern mode; an `initialize` request stays
+ * legacy. This server is dual-era: `handleRpc` answers both on the same dispatch, per request. */
+export const MODERN_PROTOCOL_VERSION = "2026-07-28"
+/** MCP-reserved JSON-RPC error codes (2026-07-28 error-code policy carves out -32020..-32099 for the spec). */
+export const MCP_ERROR = { HEADER_MISMATCH: -32020, UNSUPPORTED_VERSION: -32022 } as const
+const META_PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion"
+const META_SERVER_INFO = "io.modelcontextprotocol/serverInfo"
 
 /** The MIME type a UI resource MUST use so a host recognizes it as an MCP App widget (SEP-1865). */
 export const UI_MIME = "text/html;profile=mcp-app"
@@ -103,6 +124,9 @@ export interface McpServerFeatures {
   /** Advertise the MCP Apps UI extension in `initialize`. Present when the server serves `ui://` widgets;
    * `mimeTypes` defaults to `[UI_MIME]`. */
   readonly ui?: { readonly mimeTypes?: readonly string[] }
+  /** Natural-language guidance for LLMs on how to use this server. Surfaced in the modern
+   * `server/discover` result (2026-07-28); legacy `initialize` does not carry it. */
+  readonly instructions?: string
 }
 
 export interface JsonRpcRequest {
@@ -120,17 +144,22 @@ export interface JsonRpcNotification {
 
 export type JsonRpcResponse =
   | { jsonrpc: "2.0"; id: JsonRpcId; result: unknown }
-  | { jsonrpc: "2.0"; id: JsonRpcId; error: { code: number; message: string } }
+  | { jsonrpc: "2.0"; id: JsonRpcId; error: { code: number; message: string; data?: unknown } }
 
 export const rpcResult = (id: JsonRpcId, value: unknown): JsonRpcResponse => ({
   jsonrpc: "2.0",
   id,
   result: value,
 })
-export const rpcError = (id: JsonRpcId, code: number, message: string): JsonRpcResponse => ({
+export const rpcError = (
+  id: JsonRpcId,
+  code: number,
+  message: string,
+  data?: unknown,
+): JsonRpcResponse => ({
   jsonrpc: "2.0",
   id,
-  error: { code, message },
+  error: data !== undefined ? { code, message, data } : { code, message },
 })
 
 export interface McpProtocolState {
@@ -152,10 +181,24 @@ function requestKey(id: unknown): string | undefined {
   return typeof id === "number" && Number.isFinite(id) ? `n:${id}` : undefined
 }
 
-function progressTokenOf(params: Record<string, unknown> | undefined): ProgressToken | undefined {
+function metaObject(
+  params: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
   const meta = params?._meta
-  if (typeof meta !== "object" || meta === null || Array.isArray(meta)) return undefined
-  const token = (meta as Record<string, unknown>).progressToken
+  return typeof meta === "object" && meta !== null && !Array.isArray(meta)
+    ? (meta as Record<string, unknown>)
+    : undefined
+}
+
+/** The protocol version a modern (2026-07-28+) request declares in `_meta`, or `undefined` for a legacy
+ * request. Its presence is what puts the dispatch in modern mode for that one request. */
+export function modernVersionOf(params: Record<string, unknown> | undefined): string | undefined {
+  const version = metaObject(params)?.[META_PROTOCOL_VERSION]
+  return typeof version === "string" ? version : undefined
+}
+
+function progressTokenOf(params: Record<string, unknown> | undefined): ProgressToken | undefined {
+  const token = metaObject(params)?.progressToken
   return typeof token === "string" || (typeof token === "number" && Number.isFinite(token))
     ? token
     : undefined
@@ -191,6 +234,29 @@ function compactDescription(description: string): string {
   return `${sentence.slice(0, 117).trimEnd()}...`
 }
 
+/** Freshness hint for the static docs corpus - a modern client MAY cache list/read results this long. */
+const DEFAULT_CACHE_TTL_MS = 3_600_000
+
+/** Wrap a result in the 2026-07-28 completion envelope: `resultType`, a self-identifying `serverInfo`
+ * under `_meta`, and - for the cacheable list/read methods - a public freshness hint. Legacy results skip
+ * this entirely and keep their exact pre-2026-07-28 shape. */
+function withEnvelope(
+  value: Record<string, unknown>,
+  serverInfo: { name: string; version: string },
+  cacheable: boolean,
+): Record<string, unknown> {
+  const existingMeta =
+    typeof value._meta === "object" && value._meta !== null && !Array.isArray(value._meta)
+      ? (value._meta as Record<string, unknown>)
+      : undefined
+  return {
+    ...value,
+    resultType: "complete",
+    _meta: { ...(existingMeta ?? {}), [META_SERVER_INFO]: serverInfo },
+    ...(cacheable ? { ttlMs: DEFAULT_CACHE_TTL_MS, cacheScope: "public" } : {}),
+  }
+}
+
 /** Normalize a handler's return into the `tools/call` result object. A `string` becomes a single text
  * block (base-MCP behavior, unchanged); a {@link McpToolResult} passes `content`/`structuredContent`
  * through, and inherits the tool descriptor's `_meta` (the `ui.resourceUri` link) when it sets none. */
@@ -228,10 +294,32 @@ export async function handleRpc(
   const prompts = features.prompts ?? []
   const state = options.state ?? createMcpProtocolState()
 
+  // A request that declares its version in `_meta` is a modern (2026-07-28+) request. We speak exactly one
+  // modern revision; any other declared version is rejected so the client can retry with a supported one.
+  const requestedVersion = modernVersionOf(params)
+  const isModern = requestedVersion !== undefined
+  if (isModern && requestedVersion !== MODERN_PROTOCOL_VERSION) {
+    return rpcError(rid, MCP_ERROR.UNSUPPORTED_VERSION, "Unsupported protocol version", {
+      supported: [MODERN_PROTOCOL_VERSION],
+      requested: requestedVersion,
+    })
+  }
+  // Modern results carry the completion envelope; legacy results keep their exact prior shape. Every data
+  // case returns through `reply` so the one `isModern` decision drives the whole response shape.
+  const reply = (value: Record<string, unknown>, cacheable = false): JsonRpcResponse =>
+    rpcResult(rid, isModern ? withEnvelope(value, serverInfo, cacheable) : value)
+
   switch (method) {
-    case "initialize":
+    case "initialize": {
+      // Handshake version negotiation: answer with the client's requested version when we speak it too,
+      // otherwise our default. The client then decides whether our answer is acceptable.
+      const requested = params?.protocolVersion
+      const protocolVersion =
+        typeof requested === "string" && SUPPORTED_PROTOCOL_VERSIONS.has(requested)
+          ? requested
+          : PROTOCOL_VERSION
       return rpcResult(rid, {
-        protocolVersion: PROTOCOL_VERSION,
+        protocolVersion,
         capabilities: {
           tools: {},
           ...(resources.length > 0 ? { resources: {} } : {}),
@@ -246,6 +334,33 @@ export async function handleRpc(
         },
         serverInfo,
       })
+    }
+    case "server/discover":
+      // The modern capability/identity probe (replaces `initialize` for 2026-07-28 clients). Always
+      // enveloped and cacheable - it is a modern-only RPC.
+      return rpcResult(
+        rid,
+        withEnvelope(
+          {
+            supportedVersions: [MODERN_PROTOCOL_VERSION],
+            capabilities: {
+              tools: {},
+              ...(resources.length > 0 ? { resources: {} } : {}),
+              ...(prompts.length > 0 ? { prompts: {} } : {}),
+              ...(features.ui !== undefined
+                ? {
+                    extensions: {
+                      [UI_EXTENSION_KEY]: { mimeTypes: features.ui.mimeTypes ?? [UI_MIME] },
+                    },
+                  }
+                : {}),
+            },
+            ...(features.instructions !== undefined ? { instructions: features.instructions } : {}),
+          },
+          serverInfo,
+          true,
+        ),
+      )
     case "notifications/initialized":
       return null
     case "notifications/cancelled": {
@@ -256,8 +371,7 @@ export async function handleRpc(
     case "ping":
       return rpcResult(rid, {})
     case "tools/list":
-      return rpcResult(
-        rid,
+      return reply(
         params?.compact === true
           ? {
               tools: tools.map((t) => ({
@@ -274,12 +388,13 @@ export async function handleRpc(
                 ...(t._meta !== undefined ? { _meta: t._meta } : {}),
               })),
             },
+        true,
       )
     case "tools/describe": {
       const name = params?.name
       const tool = tools.find((t) => t.name === name)
       if (!tool) return rpcError(rid, -32602, `unknown tool: ${String(name)}`)
-      return rpcResult(rid, {
+      return reply({
         tool: {
           name: tool.name,
           description: tool.description,
@@ -331,16 +446,16 @@ export async function handleRpc(
         })
         if (controller.signal.aborted) throw new DOMException("cancelled", "AbortError")
         reportProgress(1, 1)
-        return rpcResult(rid, toolCallResult(result, tool))
+        return reply(toolCallResult(result, tool))
       } catch (err) {
         if (controller.signal.aborted) {
-          return rpcResult(rid, {
+          return reply({
             content: [{ type: "text", text: abortMessage(controller.signal) }],
             isError: true,
           })
         }
         const msg = err instanceof Error ? err.message : String(err)
-        return rpcResult(rid, { content: [{ type: "text", text: `Error: ${msg}` }], isError: true })
+        return reply({ content: [{ type: "text", text: `Error: ${msg}` }], isError: true })
       } finally {
         cleanupAbort()
         if (key !== undefined && state.activeRequests.get(key) === controller) {
@@ -349,51 +464,60 @@ export async function handleRpc(
       }
     }
     case "resources/list":
-      return rpcResult(rid, {
-        resources: resources.map((r) => ({
-          uri: r.uri,
-          name: r.name,
-          ...(r.description !== undefined ? { description: r.description } : {}),
-          ...(r.mimeType !== undefined ? { mimeType: r.mimeType } : {}),
-          ...(r._meta !== undefined ? { _meta: r._meta } : {}),
-        })),
-      })
+      return reply(
+        {
+          resources: resources.map((r) => ({
+            uri: r.uri,
+            name: r.name,
+            ...(r.description !== undefined ? { description: r.description } : {}),
+            ...(r.mimeType !== undefined ? { mimeType: r.mimeType } : {}),
+            ...(r._meta !== undefined ? { _meta: r._meta } : {}),
+          })),
+        },
+        true,
+      )
     case "resources/read": {
       const uri = params?.uri
       const resource = resources.find((r) => r.uri === uri)
       if (!resource) return rpcError(rid, -32602, `unknown resource: ${String(uri)}`)
       try {
         const content = await resource.read()
-        return rpcResult(rid, {
-          contents: [
-            {
-              uri: resource.uri,
-              mimeType: content.mimeType ?? resource.mimeType ?? "text/plain",
-              text: content.text,
-              ...(resource._meta !== undefined ? { _meta: resource._meta } : {}),
-            },
-          ],
-        })
+        return reply(
+          {
+            contents: [
+              {
+                uri: resource.uri,
+                mimeType: content.mimeType ?? resource.mimeType ?? "text/plain",
+                text: content.text,
+                ...(resource._meta !== undefined ? { _meta: resource._meta } : {}),
+              },
+            ],
+          },
+          true,
+        )
       } catch {
         // Don't surface the raw read error - it can leak a filesystem path. Return a generic message.
         return rpcError(rid, -32000, `failed to read resource: ${String(uri)}`)
       }
     }
     case "prompts/list":
-      return rpcResult(rid, {
-        prompts: prompts.map((p) => ({
-          name: p.name,
-          description: p.description,
-          ...(p.arguments !== undefined ? { arguments: p.arguments } : {}),
-        })),
-      })
+      return reply(
+        {
+          prompts: prompts.map((p) => ({
+            name: p.name,
+            description: p.description,
+            ...(p.arguments !== undefined ? { arguments: p.arguments } : {}),
+          })),
+        },
+        true,
+      )
     case "prompts/get": {
       const name = params?.name
       const prompt = prompts.find((p) => p.name === name)
       if (!prompt) return rpcError(rid, -32602, `unknown prompt: ${String(name)}`)
       const args = (params?.arguments as Record<string, unknown>) ?? {}
       try {
-        return rpcResult(rid, {
+        return reply({
           description: prompt.description,
           messages: await prompt.handler(args),
         })

package/src/server.ts

@@ -46,6 +46,11 @@ export interface CreateMcpServerOptions {
   readonly health?: string
   /** Max JSON-RPC body size in bytes (default 1 MB). */
   readonly maxBodyBytes?: number
+  /** Natural-language guidance for LLMs, surfaced in the modern `server/discover` result (2026-07-28). */
+  readonly instructions?: string
+  /** Origin allowlist for the DNS-rebinding guard. Omit to allow any origin; set it to reject other
+   * browser origins with 403 (e.g. a hardened, non-public mount). */
+  readonly allowedOrigins?: readonly string[]
 }
 
 export interface McpServer {
@@ -69,6 +74,7 @@ export function createMcpServer(opts: CreateMcpServerOptions): McpServer {
     ...(resources.length > 0 ? { resources } : {}),
     ...(opts.prompts !== undefined ? { prompts: opts.prompts } : {}),
     ...(widgets.length > 0 ? { ui: { mimeTypes: [UI_MIME] } } : {}),
+    ...(opts.instructions !== undefined ? { instructions: opts.instructions } : {}),
   }
   return {
     tools,
@@ -79,6 +85,7 @@ export function createMcpServer(opts: CreateMcpServerOptions): McpServer {
         features,
         ...(opts.health !== undefined ? { health: opts.health } : {}),
         ...(opts.maxBodyBytes !== undefined ? { maxBodyBytes: opts.maxBodyBytes } : {}),
+        ...(opts.allowedOrigins !== undefined ? { allowedOrigins: opts.allowedOrigins } : {}),
       }),
     handle: (message) => handleRpc(message, tools, serverInfo, features),
   }