@mastra/mcp-docs-server 1.1.16-alpha.3 → 1.1.16-alpha.5

package/.docs/docs/server/middleware.md

@@ -104,6 +104,7 @@ Mastra provides reserved context keys that, when set by middleware, take precede
 ```typescript
 import { Mastra } from '@mastra/core'
 import { MASTRA_RESOURCE_ID_KEY } from '@mastra/core/request-context'
+import { getAuthenticatedUser } from '@mastra/server/auth'
 
 export const mastra = new Mastra({
   server: {
@@ -117,8 +118,17 @@ export const mastra = new Mastra({
       {
         path: '/api/*',
         handler: async (c, next) => {
+          const token = c.req.header('Authorization')
+          if (!token) {
+            return c.json({ error: 'Unauthorized' }, 401)
+          }
+
+          const user = await getAuthenticatedUser<{ id: string }>({
+            mastra: c.get('mastra'),
+            token,
+            request: c.req.raw,
+          })
           const requestContext = c.get('requestContext')
-          const user = requestContext.get('user')
 
           if (!user) {
             return c.json({ error: 'Unauthorized' }, 401)
@@ -136,6 +146,8 @@ export const mastra = new Mastra({
 })
 ```
 
+`server.middleware` runs before Mastra's per-route auth checks. When middleware needs the authenticated user, call `getAuthenticatedUser()` to resolve it from the configured auth provider without changing the default route auth flow.
+
 With this middleware, the server automatically:
 
 - **Filters thread listing** to only return threads owned by the user

package/.docs/docs/server/server-adapters.md

@@ -341,7 +341,7 @@ app.listen(port, () => {
 Calling `init()` runs three steps in order. Understanding this flow helps when you need to insert your own middleware at specific points.
 
 1. `registerContextMiddleware()`: Attaches the Mastra instance, request context, tools, and abort signal to every request. This makes Mastra available to all subsequent middleware and route handlers.
-2. `registerAuthMiddleware()`: Adds authentication and authorization middleware, but only if `server.auth` is configured in your Mastra instance. Skipped entirely if no auth is configured.
+2. `registerAuthMiddleware()`: Runs the adapter auth hook during initialization. Official adapters enforce auth inline when Mastra registers built-in routes and `registerApiRoute()` routes, so raw framework routes should use the adapter's exported `createAuthMiddleware()` helper when they need Mastra auth.
 3. `registerRoutes()`: Registers all Mastra API routes for agents, workflows, and other features. Also registers MCP routes if MCP servers are configured.
 
 ### Manual initialization
@@ -359,7 +359,6 @@ server.registerContextMiddleware();
 // Middleware that needs Mastra context
 app.use(customMiddleware);
 
-server.registerAuthMiddleware();
 await server.registerRoutes();
 
 // Routes after Mastra
@@ -374,6 +373,8 @@ You can add your own routes to the app alongside Mastra's routes.
 
 - Routes added **before** `init()` won't have Mastra context available.
 - Routes added **after** `init()` have access to the Mastra context (the Mastra instance, request context, authenticated user, etc.).
+- When you want Mastra-managed auth and route metadata such as `requiresAuth`, prefer `registerApiRoute()`.
+- When you mount routes directly on the framework app, use the adapter's exported `createAuthMiddleware()` helper if those routes need Mastra auth.
 
 > **Info:** Visit "Adding custom routes" for [Express](https://mastra.ai/reference/server/express-adapter) and [Hono](https://mastra.ai/reference/server/hono-adapter) for more information.
 

package/.docs/models/index.md

@@ -232,7 +232,11 @@ Your users never experience the disruption - the response comes back with the sa
 
 Mastra also supports local models like `gpt-oss`, `Qwen3`, `DeepSeek` and many more that you run on your own hardware. The application running your local model needs to provide an OpenAI-compatible API server for Mastra to connect to. We recommend using [LMStudio](https://lmstudio.ai/) (see [Running the LMStudio server](https://lmstudio.ai/docs/developer/core/server)).
 
-For a custom provider the `id` (`${providerId}/${modelId}`) is required but it will only be used for display purposes. The `modelId` needs to be the actual model you want to use. An example would be: `custom/my-qwen3-model`.
+For custom OpenAI-compatible endpoints, `id` is the routing form that Mastra sends through the model router.
+
+Use `provider/model` when the remote behaves like a direct provider and expects a bare model name such as `llama3.2`.
+
+Use `gateway/provider/model` when the remote behaves like a model gateway and the upstream model namespace includes the provider, such as `mastra/google/gemini-2.5-flash` or `openrouter/google/gemini-2.5-flash`.
 
 For the `url` it's **important** that you use the base URL of the OpenAI-compatible endpoint with Mastra's `model` setting and not the individual chat endpoints.
 
@@ -250,6 +254,22 @@ const agent = new Agent({
 })
 ```
 
+If the remote behaves like a model gateway, include the gateway prefix in `id`:
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: {
+    id: "mastra/google/gemini-2.5-flash",
+    url: "http://your-custom-openai-compatible-endpoint.com/v1"
+  }
+})
+```
+
 ### Example: LMStudio
 
 After starting the LMStudio server, the local server is available at `http://localhost:1234` and it provides endpoints like `/v1/models`, `/v1/chat/completions`, etc. The `url` will be `http://localhost:1234/v1`. For the `id` you can use (`lmstudio/${modelId}`) which will be displayed in the LMStudio interface.

package/.docs/reference/server/express-adapter.md

@@ -110,6 +110,29 @@ app.listen(4111)
 
 > **Tip:** Routes added before `init()` run without Mastra context. Add routes after `init()` to access the Mastra instance and request context.
 
+When you want Mastra-managed auth and route metadata such as `requiresAuth`, prefer [`registerApiRoute()`](https://mastra.ai/reference/server/register-api-route). For raw Express routes mounted directly on `app`, use `createAuthMiddleware()`:
+
+```typescript
+import express from 'express'
+import { createAuthMiddleware, MastraServer } from '@mastra/express'
+import { mastra } from './mastra'
+
+const app = express()
+app.use(express.json())
+
+const server = new MastraServer({ app, mastra })
+await server.init()
+
+app.get('/custom/protected', createAuthMiddleware({ mastra }), (req, res) => {
+  const user = res.locals.requestContext.get('user')
+  res.json({ user })
+})
+
+app.get('/custom/public', createAuthMiddleware({ mastra, requiresAuth: false }), (req, res) => {
+  res.json({ ok: true })
+})
+```
+
 ## Accessing context
 
 In Express middleware and routes, access Mastra context via `res.locals`:

package/.docs/reference/server/fastify-adapter.md

@@ -75,6 +75,34 @@ app.listen({ port: 3000 }, (err, address) => {
 
 **mcpOptions** (`MCPOptions`): MCP transport options. Set \`serverless: true\` for stateless environments like Cloudflare Workers or Vercel Edge.
 
+## Protecting raw routes
+
+When you want Mastra-managed auth and route metadata such as `requiresAuth`, prefer [`registerApiRoute()`](https://mastra.ai/reference/server/register-api-route). For raw Fastify routes mounted directly on the app, use `createAuthMiddleware()`:
+
+```typescript
+import Fastify from 'fastify'
+import { createAuthMiddleware, MastraServer } from '@mastra/fastify'
+import { mastra } from './mastra'
+
+const app = Fastify()
+const server = new MastraServer({ app, mastra })
+
+await server.init()
+
+app.get('/custom/protected', { preHandler: createAuthMiddleware({ mastra }) }, async request => {
+  const user = request.requestContext.get('user')
+  return { user }
+})
+
+app.get(
+  '/custom/public',
+  { preHandler: createAuthMiddleware({ mastra, requiresAuth: false }) },
+  async () => {
+    return { ok: true }
+  },
+)
+```
+
 ## Manual initialization
 
 For custom middleware ordering, call each method separately instead of `init()`. See [manual initialization](https://mastra.ai/docs/server/server-adapters) for details.

package/.docs/reference/server/hono-adapter.md

@@ -94,6 +94,28 @@ app.get('/custom', c => {
 
 > **Tip:** Routes added before `init()` run without Mastra context. Add routes after `init()` to access the Mastra instance and request context.
 
+When you want Mastra-managed auth and route metadata such as `requiresAuth`, prefer [`registerApiRoute()`](https://mastra.ai/reference/server/register-api-route). For raw Hono routes mounted directly on `app`, use `createAuthMiddleware()`:
+
+```typescript
+import { Hono } from 'hono'
+import { createAuthMiddleware, HonoBindings, HonoVariables, MastraServer } from '@mastra/hono'
+import { mastra } from './mastra'
+
+const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>()
+const server = new MastraServer({ app, mastra })
+
+await server.init()
+
+app.get('/custom/protected', createAuthMiddleware({ mastra }), c => {
+  const user = c.get('requestContext').get('user')
+  return c.json({ user })
+})
+
+app.get('/custom/public', createAuthMiddleware({ mastra, requiresAuth: false }), c => {
+  return c.json({ ok: true })
+})
+```
+
 ## Accessing context
 
 In Hono middleware and route handlers, access Mastra context via `c.get()`:

package/.docs/reference/server/koa-adapter.md

@@ -112,6 +112,29 @@ const mastra = new Mastra({
 
 When `init()` is used, a global error-handling middleware is also registered as a safety net. Errors that reach this middleware are emitted via `ctx.app.emit('error', err, ctx)` following the standard Koa convention.
 
+## Protecting raw routes
+
+When you want Mastra-managed auth and route metadata such as `requiresAuth`, prefer [`registerApiRoute()`](https://mastra.ai/reference/server/register-api-route). For raw Koa routes mounted directly on the app, use `createAuthMiddleware()`:
+
+```typescript
+import Koa from 'koa'
+import { createAuthMiddleware, MastraServer } from '@mastra/koa'
+import { mastra } from './mastra'
+
+const app = new Koa()
+const server = new MastraServer({ app, mastra })
+
+await server.init()
+
+app.use(createAuthMiddleware({ mastra }))
+app.use(async ctx => {
+  if (ctx.path !== '/custom/protected') return
+
+  const user = ctx.state.requestContext.get('user')
+  ctx.body = { user }
+})
+```
+
 ## Manual initialization
 
 For custom middleware ordering, call each method separately instead of `init()`. See [manual initialization](https://mastra.ai/docs/server/server-adapters) for details.

package/.docs/reference/server/mastra-server.md

@@ -69,7 +69,7 @@ abstract registerContextMiddleware(): void
 
 ### `registerAuthMiddleware()`
 
-Register authentication and authorization middleware.
+Run the adapter auth hook during initialization. Official adapters may implement this as a no-op when auth is enforced per-route.
 
 ```typescript
 abstract registerAuthMiddleware(): void
@@ -266,7 +266,8 @@ export class MyServer extends MastraServer<MyApp, MyRequest, MyResponse> {
   registerAuthMiddleware(): void {
     const auth = this.mastra.getServer()?.auth
     if (!auth) return
-    // Implement auth
+    // Register global auth middleware, or leave this empty and
+    // enforce auth when routes are registered.
   }
 
   async registerRoute(app, route, { prefix }) {

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.1.16-alpha.4
+
+### Patch Changes
+
+- Updated dependencies [[`7dbd611`](https://github.com/mastra-ai/mastra/commit/7dbd611a85cb1e0c0a1581c57564268cb183d86e), [`41aee84`](https://github.com/mastra-ai/mastra/commit/41aee84561ceebe28bad1ecba8702d92838f67f0)]:
+  - @mastra/core@1.16.0-alpha.1
+
 ## 1.1.16-alpha.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.16-alpha.3",
+  "version": "1.1.16-alpha.5",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/core": "1.16.0-alpha.0",
+    "@mastra/core": "1.16.0-alpha.1",
     "@mastra/mcp": "^1.3.1"
   },
   "devDependencies": {
@@ -46,9 +46,9 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "4.0.18",
+    "@internal/lint": "0.0.73",
     "@internal/types-builder": "0.0.48",
-    "@mastra/core": "1.16.0-alpha.0",
-    "@internal/lint": "0.0.73"
+    "@mastra/core": "1.16.0-alpha.1"
   },
   "homepage": "https://mastra.ai",
   "repository": {