@mastra/mcp-docs-server 1.2.27-alpha.11 → 1.2.27-alpha.15

package/.docs/reference/tools/mcp-server.md

@@ -51,6 +51,12 @@ const server = new MCPServer({
 })
 ```
 
+## Tool schemas and structured results
+
+MCP tool input and output schemas are advertised as JSON Schema 2020-12, the dialect the `2026-07-28` revision assumes, with the dialect declared in `$schema`. Advertised Mastra tool schemas preserve supported references, composition keywords, and tuple (`prefixItems`) shapes.
+
+A tool with an `outputSchema` can return any JSON value, including an object, array, string, number, boolean, or `null`. The value is sent as `structuredContent` without wrapping it in an object. The server validates successful structured output against the tool's output schema before returning it.
+
 ### Configuration Properties
 
 The constructor accepts an `MCPServerConfig` object with the following properties:
@@ -386,32 +392,27 @@ async startHTTP({
   httpPath,
   req,
   res,
-  options = { sessionIdGenerator: () => randomUUID() },
+  options,
 }: {
   url: URL;
   httpPath: string;
   req: http.IncomingMessage;
   res: http.ServerResponse<http.IncomingMessage>;
-  options?: StreamableHTTPServerTransportOptions;
+  options?: MCPServerHTTPRequestOptions;
 }): Promise<void>
 ```
 
-#### Options with `protocolVersion: '2026-07-28'`
+Every request is self-contained: there is no session to create or resume, so `options` only carries request guards.
 
-The `2026-07-28` protocol uses one shared stateless handler instead of a transport configured for each request. `startHTTP()` handles legacy transport options as follows:
+| Option                         | Behavior                                                                                                                                                                                                                                              |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enableDnsRebindingProtection` | When `true`, the `Host` header is checked against `allowedHosts` and the `Origin` header against `allowedOrigins` before the request is handled. A check only runs when its list is non-empty. A rejected request receives a `403` JSON-RPC error.    |
+| `allowedHosts`                 | Hostnames accepted in the `Host` header. Matching is port-agnostic: `localhost:3000` in the list allows any port on `localhost`. Write IPv6 addresses with brackets (`[::1]`).                                                                        |
+| `allowedOrigins`               | Origins accepted in the `Origin` header. Only the hostname is compared, so `https://app.example.com:8443` allows every scheme and port on `app.example.com`. Requests without an `Origin` header pass because non-browser MCP clients don't send one. |
 
-| Options                                                                              | Behavior                                                                                                                                |
-| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `serverless: true`, `serverlessStreaming: true`, `sessionIdGenerator: undefined`     | Accepted because the modern handler already provides stateless requests and automatic request-scoped streaming.                         |
-| `allowedHosts`, `allowedOrigins`, `enableDnsRebindingProtection`                     | Enforced before the request reaches the modern handler. Host and origin lists are active when `enableDnsRebindingProtection` is `true`. |
-| `sessionIdGenerator` with a function, session callbacks, or `eventStore`             | Rejected because the modern protocol doesn't create HTTP sessions.                                                                      |
-| `enableJsonResponse`, `retryInterval`, `keepAliveMs`, or `supportedProtocolVersions` | Rejected because these values configure a shared handler and can't vary between requests.                                               |
-| `serverless: false` or `serverlessStreaming: false`                                  | Rejected because these values request behavior that differs from the modern handler.                                                    |
-| Unknown options                                                                      | Rejected instead of being ignored.                                                                                                      |
+Omit `options` when you don't need request guards.
 
-Omit `options` when you don't need request guards or compatibility declarations.
-
-Here's an example of how you might use `startHTTP` within an HTTP server request handler. In this example an MCP client could connect to your MCP server at `http://localhost:1234/http`:
+Here's an example of how you might use `startHTTP` within an HTTP server request handler. In this example an MCP client could connect to your MCP server at `http://localhost:1234/mcp`:
 
 ```typescript
 import http from 'http'
@@ -422,9 +423,6 @@ const httpServer = http.createServer(async (req, res) => {
     httpPath: `/mcp`,
     req,
     res,
-    options: {
-      sessionIdGenerator: () => randomUUID(),
-    },
   })
 })
 
@@ -433,7 +431,7 @@ httpServer.listen(PORT, () => {
 })
 ```
 
-For **serverless environments** (Supabase Edge Functions, Cloudflare Workers, Vercel Edge, etc.), use `serverless: true` to enable stateless operation on the legacy protocol path. Servers configured with `protocolVersion: '2026-07-28'` are already stateless and may omit this option.
+Because every request is self-contained, nothing needs to persist between invocations, so `startHTTP` works in serverless environments (Supabase Edge Functions, Cloudflare Workers, Vercel Edge, AWS Lambda, Deno Deploy). The method still takes Node-style `http.IncomingMessage` and `http.ServerResponse` objects, so a Fetch-based runtime has to convert its `Request` with an adapter such as `fetch-to-node` and turn the result back into a `Response`:
 
 ```typescript
 // Supabase Edge Function example
@@ -456,15 +454,7 @@ serve(async req => {
     // Convert Deno Request to Node.js-compatible format
     const { req: nodeReq, res: nodeRes } = toReqRes(req)
 
-    await server.startHTTP({
-      url,
-      httpPath: '/mcp',
-      req: nodeReq,
-      res: nodeRes,
-      options: {
-        serverless: true, // ← Enable stateless mode for serverless
-      },
-    })
+    await server.startHTTP({ url, httpPath: '/mcp', req: nodeReq, res: nodeRes })
 
     return toFetchResponse(nodeRes)
   }
@@ -473,50 +463,7 @@ serve(async req => {
 })
 ```
 
-> **When to use serverless: true:** Use `serverless: true` when deploying to environments where each request runs in a fresh, stateless execution context:
->
-> - Supabase Edge Functions
-> - Cloudflare Workers
-> - Vercel Edge Functions
-> - Netlify Edge Functions
-> - AWS Lambda
-> - Deno Deploy
->
-> Use the default session-based mode (without `serverless: true`) for:
->
-> - Long-lived Node.js servers
-> - Docker containers
-> - Traditional hosting (VPS, dedicated servers)
->
-> The serverless mode disables session management and creates fresh server instances per request, which is necessary for stateless environments where memory doesn't persist between invocations.
->
-> By default, serverless mode buffers each request into a single JSON response, so `notifications/progress` sent by a tool never reach the client. Set `serverlessStreaming: true` to handle the request with request-scoped SSE streaming instead, which delivers progress notifications before the final result:
->
-> ```typescript
-> await server.startHTTP({
->   url,
->   httpPath: '/mcp',
->   req: nodeReq,
->   res: nodeRes,
->   options: {
->     serverless: true,
->     serverlessStreaming: true, // ← Stream request-scoped notifications/progress
->   },
-> })
-> ```
->
-> This is still stateless: no `mcp-session-id` is required or persisted. It only enables notifications scoped to the current request (such as progress). The session-dependent features below remain unavailable.
->
-> On the legacy protocol path, the following MCP features require session state or persistent connections and **won't work** in serverless mode (including with `serverlessStreaming: true`):
->
-> - **Elicitation** - Interactive user input requests during tool execution require session management to route responses back to the correct client
-> - **Resource subscriptions** - `resources/subscribe` and `resources/unsubscribe` need persistent connections to maintain subscription state
-> - **Resource update notifications** - `resources.notifyUpdated()` requires active subscriptions and persistent connections to notify clients
-> - **Prompt list change notifications** - `prompts.notifyListChanged()` requires persistent connections to push updates to clients
-> - **Tool list change notifications** - `toolActions.notifyListChanged()` requires persistent connections to push updates to clients
-> - **Server log notifications** - `sendLoggingMessage()` requires persistent connections to push log messages to clients
->
-> These features work normally in long-lived server environments (Node.js servers, Docker containers, etc.).
+Request-scoped features (`input_required` rounds, progress, per-request logs) stream inside the request that triggered them. Notifications that outlive a request (`resources.notifyUpdated()`, `prompts.notifyListChanged()`, `toolActions.notifyListChanged()`) are delivered on the `subscriptions/listen` stream a client keeps open, so they only reach clients while that stream is served by a running instance.
 
 Here are the details for the values needed by the `startHTTP` method:
 
@@ -528,21 +475,15 @@ Here are the details for the values needed by the `startHTTP` method:
 
 **res** (`http.ServerResponse`): The response object from your web server, used to send data back.
 
-**options** (`StreamableHTTPServerTransportOptions`): Optional configuration for the HTTP transport. See the options table below for more details.
-
-The `StreamableHTTPServerTransportOptions` object allows you to customize the behavior of the HTTP transport. Here are the available options:
-
-**serverless** (`boolean`): If true, runs in stateless mode without session management. Each request is handled independently with a fresh server instance. Essential for serverless environments (Cloudflare Workers, Supabase Edge Functions, Vercel Edge, etc.) where sessions cannot persist between invocations. Defaults to false.
-
-**serverlessStreaming** (`boolean`): If true, serverless requests use request-scoped SSE streaming instead of a buffered JSON response, allowing in-request notifications/progress to reach the client before the final result. Only takes effect together with serverless: true. Defaults to false (buffered JSON responses), which preserves backward-compatible behavior. It enables only request-scoped notifications such as progress; elicitation, subscriptions, and out-of-request notifications still require session state.
+**options** (`MCPServerHTTPRequestOptions`): Optional request guards. See the options table below for more details.
 
-**sessionIdGenerator** (`(() => string) | undefined`): A function that generates a unique session ID. This should be a cryptographically secure, globally unique string. Return undefined to disable session management.
+The `MCPServerHTTPRequestOptions` object carries request guards:
 
-**onsessioninitialized** (`(sessionId: string) => void`): A callback that is invoked when a new session is initialized. This is useful for tracking active MCP sessions.
+**enableDnsRebindingProtection** (`boolean`): If true, the Host and Origin headers are validated against allowedHosts and allowedOrigins before the request is handled. Defaults to false.
 
-**enableJsonResponse** (`boolean`): If true, the server will return plain JSON responses instead of using Server-Sent Events (SSE) for streaming. Defaults to false.
+**allowedHosts** (`string[]`): Hosts (host\[:port]) accepted when DNS rebinding protection is enabled.
 
-**eventStore** (`EventStore`): An event store for message resumability. Providing this enables clients to reconnect and resume message streams.
+**allowedOrigins** (`string[]`): Origins accepted when DNS rebinding protection is enabled.
 
 ### `close()`
 

package/.docs/reference/workspace/process-manager.md

@@ -68,6 +68,8 @@ const handle = await sandbox.processes.spawn('npm run dev', {
 
 **options.abortSignal** (`AbortSignal`): Signal to abort the process. When aborted, the process is killed.
 
+**options.stdinMode** (`'pipe' | 'ignore'`): How stdin is wired. 'pipe' (default) opens a writable stdin for sendStdin() and writer. 'ignore' closes stdin so commands that read it see immediate EOF. Honored by the local, Docker, and E2B providers.
+
 **Returns:** `Promise<ProcessHandle>`
 
 ### `list()`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.27-alpha.11",
+  "version": "1.2.27-alpha.15",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -23,11 +23,11 @@
   "author": "",
   "license": "Apache-2.0",
   "dependencies": {
+    "@mastra/mcp": "^1.18.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "local-pkg": "^1.1.2",
     "zod": "^4.6.4",
-    "@mastra/core": "1.68.0-alpha.5",
-    "@mastra/mcp": "^1.18.1-alpha.3"
+    "@mastra/core": "1.68.0-alpha.7"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.0",
@@ -44,7 +44,7 @@
     "vitest": "4.1.11",
     "@internal/lint": "0.0.133",
     "@internal/types-builder": "0.0.108",
-    "@mastra/core": "1.68.0-alpha.5"
+    "@mastra/core": "1.68.0-alpha.7"
   },
   "homepage": "https://mastra.ai",
   "repository": {