@mastra/mcp-docs-server 1.2.8-alpha.2 → 1.2.8-alpha.23

package/.docs/docs/agent-builder/integrations.md

@@ -37,9 +37,7 @@ import { MastraEditor } from '@mastra/editor'
 import { ComposioToolProvider } from '@mastra/editor/composio'
 
 export const mastra = new Mastra({
-  agents: {
-    /* your agents */
-  },
+  agents: {/* your agents */},
   editor: new MastraEditor({
     toolProviders: {
       composio: new ComposioToolProvider({

package/.docs/docs/agents/overview.md

@@ -44,17 +44,31 @@ export const weatherTool = createTool({
     location: z.string().describe('City name'),
   }),
   outputSchema: z.object({
-    output: z.string(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
   execute: async ({ location }) => {
     return {
-      output: `The weather in ${location} is sunny`,
+      location,
+      temperatureCelsius: 21,
+      conditions: 'sunny',
     }
   },
 })
 ```
 
-If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. The constructor takes `{ id, name, instructions, model }`. The `model` property is a string in Mastra's model router format: `provider/model`, for example `openai/gpt-5.5`. For OpenAI models, use `openai/<model>`, not `openai:<model>`, and don't pass a provider object. No provider import is needed for this format. Don't install any AI SDK package unless Mastra's documentation says otherwise.
+If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. The constructor takes `{ id, name, instructions, model }`. The `model` property is a string in Mastra's model router format. No provider import is needed for this format. Don't install any AI SDK package unless Mastra's documentation says otherwise.
+
+By defining the model using `provider/model` format Mastra automatically looks for environment variables for the given provider. The defined model requires an environment variable to be set for the provider. OpenAI: `OPENAI_API_KEY`. Anthropic: `ANTHROPIC_API_KEY`. Google: `GOOGLE_API_KEY`. Example: Any `openai/<model>` requires the `OPENAI_API_KEY` environment variable. Go to <https://mastra.ai/models/environment-variables> for a full list of supported providers and their environment variable names.
+
+Short list of known model IDs are:
+
+- `openai/gpt-5.5`, `openai/gpt-5-mini`
+- `anthropic/claude-sonnet-4-6`, `anthropic/claude-opus-4-7`, `anthropic/claude-haiku-4-5`
+- `google/gemini-2.5-flash`
+
+Go to <https://mastra.ai/models> for a full list of supported models.
 
 Add a tool an agent by importing the tool and passing it to the agent constructor as a tools object.
 
@@ -83,16 +97,6 @@ export const weatherAgent = new Agent({
 })
 ```
 
-By defining the model using `provider/model` format Mastra automatically looks for environment variables for the given provider. The defined model requires an environment variable to be set for the provider. OpenAI: `OPENAI_API_KEY`. Anthropic: `ANTHROPIC_API_KEY`. Google: `GOOGLE_API_KEY`. Example: Any `openai/<model>` requires the `OPENAI_API_KEY` environment variable. Go to <https://mastra.ai/models/environment-variables> for a full list of supported providers and their environment variable names.
-
-Short list of known model IDs are:
-
-- `openai/gpt-5.5`, `openai/gpt-5-mini`
-- `anthropic/claude-sonnet-4-6`, `anthropic/claude-opus-4-7`, `anthropic/claude-haiku-4-5`
-- `google/gemini-2.5-flash`
-
-Go to <https://mastra.ai/models> for a full list of supported models.
-
 Create a Mastra entry point at `src/mastra/index.ts` and register the agent:
 
 ```ts

package/.docs/docs/agents/skills.md

@@ -85,9 +85,7 @@ export const agent = new Agent({
   skills: [
     './skills/code-review', // path to a SKILL.md directory
     './skills/testing', // another filesystem skill
-    createSkill({
-      /* ... */
-    }), // inline skill
+    createSkill({/* ... */}), // inline skill
   ],
 })
 ```

package/.docs/docs/agents/structured-output.md

@@ -197,9 +197,9 @@ If your tools aren't being called when structured output is enabled, or you rece
 
 When your model doesn't support tools and structured output together, you have three options:
 
-1. **Use `jsonPromptInjection: true`** - Injects the schema into the prompt instead of using the API's `response_format` parameter
-2. **Use a separate structuring model** - Pass a `model` to `structuredOutput` to use a second LLM for structuring
-3. **Use `prepareStep`** - Handle tools and structured output in separate steps
+1. **Use `jsonPromptInjection`**: Set it to `'auto'` to select native structured output when supported and inline prompt injection otherwise, or choose an explicit injection mode
+2. **Use a separate structuring model**: Pass a `model` to `structuredOutput` to use a second LLM for structuring
+3. **Use `prepareStep`**: Handle tools and structured output in separate steps
 
 Each approach is detailed in the sections below.
 
@@ -209,9 +209,7 @@ Structured output support varies across LLMs due to differences in their APIs. T
 
 ### `jsonPromptInjection`
 
-By default, Mastra passes the schema to the model provider using the `response_format` API parameter. Most model providers have built-in support for this, which reliably enforces the schema.
-
-If your model provider doesn't support `response_format`, you'll get an error from the API. When this happens, set `jsonPromptInjection: true`. This adds the schema to the system prompt instead, instructing the model to output JSON. This is less reliable than the API parameter approach.
+By default, Mastra passes the schema to the model provider using the `response_format` API parameter. Set `jsonPromptInjection: 'auto'` to let Mastra choose the mode from its model capability data. Mastra uses native structured output for supported models and inline prompt injection for unsupported models or models without capability data.
 
 ```typescript
 import { z } from 'zod'
@@ -224,13 +222,20 @@ const response = await testAgent.generate('Help me plan my day.', {
         activities: z.array(z.string()),
       }),
     ),
-    jsonPromptInjection: true,
+    jsonPromptInjection: 'auto',
   },
 })
 
 console.log(response.object)
 ```
 
+Use an explicit mode when you need to override the capability-based choice:
+
+- `false` or omitted: Use the provider's native structured output.
+- `'inline'`: Add the schema instructions to the latest user message.
+- `true` or `'system'`: Add the schema instructions to the system message.
+- `'auto'`: Use native structured output when the model supports it. Otherwise, use inline prompt injection.
+
 > **Gemini 2.5 with tools:** Gemini 2.5 models don't support combining `response_format` (structured output) with function calling (tools) in the same API call. If your agent has tools and you're using `structuredOutput` with a Gemini 2.5 model, you must set `jsonPromptInjection: true` to avoid the error `Function calling with a response mime type: 'application/json' is unsupported`.
 >
 > ```typescript
@@ -246,6 +251,8 @@ console.log(response.object)
 
 When `model` is provided to the `structuredOutput` property, Mastra uses a separate internal agent to handle the structured output. The main agent will handle all of the steps (including tool calling) and the structured output model will handle only the generation of structured output.
 
+**For AI agents:** The `model` property is a string in Mastra's model router format: `provider/model`, for example `openai/gpt-5.5`, `openai/gpt-5-mini`, `anthropic/claude-sonnet-4-6` or `google/gemini-2.5-pro`. Use `/` and not `:` as a separator. Example: `openai/<model>`, not `openai:<model>`, and don't pass a provider object. No provider import is needed for this format. Don't install any AI SDK package unless Mastra's documentation says otherwise. By defining the model using `provider/model` format Mastra automatically looks for environment variables for the given provider. The defined model requires an environment variable to be set for the provider. OpenAI: `OPENAI_API_KEY`. Anthropic: `ANTHROPIC_API_KEY`. Google: `GOOGLE_API_KEY`.
+
 ```typescript
 const response = await testAgent.generate('Tell me about TypeScript.', {
   structuredOutput: {

package/.docs/docs/agents/using-tools.md

@@ -14,7 +14,7 @@ Use tools when an agent needs additional context or information from remote reso
 
 Import [`createTool`](https://mastra.ai/reference/tools/create-tool) from `@mastra/core/tools` and define a tool with an `id`, `description`, `inputSchema`, `outputSchema`, and `execute` function.
 
-This example shows how to create a tool that fetches weather data from an API. When the agent calls the tool, it provides the required input as defined by the tool's `inputSchema`. The tool accesses this data through its `inputData` parameter, which in this example includes the `location` used in the weather API query.
+This example creates a tool that fetches weather data from an API. The `execute` function receives input validated against `inputSchema` as its first argument and an optional execution context as its second. You can destructure the input fields directly in the function signature.
 
 ```typescript
 import { createTool } from '@mastra/core/tools'
@@ -27,15 +27,21 @@ export const weatherTool = createTool({
     location: z.string(),
   }),
   outputSchema: z.object({
-    weather: z.string(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
-  execute: async inputData => {
-    const { location } = inputData
-
-    const response = await fetch(`https://wttr.in/${location}?format=3`)
-    const weather = await response.text()
+  execute: async ({ location }, { abortSignal }) => {
+    const response = await fetch(`https://wttr.in/${location}?format=j1`, {
+      signal: abortSignal,
+    })
+    const data = await response.json()
 
-    return { weather }
+    return {
+      location,
+      temperatureCelsius: Number(data.current_condition[0].temp_C),
+      conditions: data.current_condition[0].weatherDesc[0].value,
+    }
   },
 })
 ```
@@ -76,10 +82,12 @@ export const weatherTool = createTool({
     location: z.string(),
   }),
   outputSchema: z.object({
-    weather: z.string(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
-  execute: async inputData => {
-    // Fetch weather data
+  execute: async ({ location }) => {
+    return { location, temperatureCelsius: 21, conditions: 'sunny' }
   },
 })
 ```
@@ -101,11 +109,13 @@ export const weatherTool = createTool({
   ),
   outputSchema: toStandardJsonSchema(
     v.object({
-      weather: v.string(),
+      location: v.string(),
+      temperatureCelsius: v.number(),
+      conditions: v.string(),
     }),
   ),
-  execute: async inputData => {
-    // Fetch weather data
+  execute: async ({ location }) => {
+    return { location, temperatureCelsius: 21, conditions: 'sunny' }
   },
 })
 ```
@@ -123,10 +133,12 @@ export const weatherTool = createTool({
     location: 'string',
   }),
   outputSchema: type({
-    weather: 'string',
+    location: 'string',
+    temperatureCelsius: 'number',
+    conditions: 'string',
   }),
-  execute: async inputData => {
-    // Fetch weather data
+  execute: async ({ location }) => {
+    return { location, temperatureCelsius: 21, conditions: 'sunny' }
   },
 })
 ```
@@ -195,40 +207,44 @@ export const researchAgent = new Agent({
 
 ## Share tools across agents
 
-Direct imports are the simplest choice when one tool is used by one or a small number of agents. Each agent imports the tool and adds it to its `tools` record, as shown in the quickstart above.
+Direct imports are the best choice when one tool is used by multiple agents. Each agent imports the tool and adds it to its `tools` record. Dependencies remain explicit and each agent can be used independently.
 
-For tools shared across agents or retrieved elsewhere from the Mastra instance, register them once with `new Mastra({ tools })`. A function-based Agent `tools` callback can then resolve entries from that registry.
+```typescript
+import { createTool } from '@mastra/core/tools'
+
+export const weatherTool = createTool({
+  id: 'weather-tool',
+  // Rest of the tool definition...
+})
+```
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
-import { Mastra } from '@mastra/core/mastra'
-import { weatherTool } from './tools/weather-tool'
+import { weatherTool } from '../tools/weather-tool'
 
-export const sharedWeatherAgent = new Agent({
-  id: 'shared-weather-agent',
-  name: 'Shared Weather Agent',
-  instructions: `
-    You are a helpful weather assistant.
-    Use the weatherTool to fetch current weather data.`,
+export const weatherAgent = new Agent({
+  id: 'weather-agent',
+  name: 'Weather Agent',
+  instructions: 'Answer questions about current weather.',
   model: 'openai/gpt-5.5',
-  tools: ({ mastra }) => {
-    if (!mastra) {
-      throw new Error('Mastra instance is required to resolve shared tools')
-    }
-
-    return { weatherTool: mastra.getTool('weather') }
-  },
+  tools: { weatherTool },
 })
+```
 
-export const mastra = new Mastra({
-  tools: { weather: weatherTool },
-  agents: { sharedWeatherAgent },
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { weatherTool } from '../tools/weather-tool'
+
+export const travelAgent = new Agent({
+  id: 'travel-agent',
+  name: 'Travel Agent',
+  instructions: 'Help users plan trips.',
+  model: 'openai/gpt-5.5',
+  tools: { weatherTool },
 })
 ```
 
-Register the tool and Agent on the same Mastra instance. The Agent can then retrieve the shared tool by its registration key in the `tools` callback and return it under the name the model should use. Keep the `mastra` guard because it's optional in the callback type.
-
-For API details, see [`Mastra.getTool()`](https://mastra.ai/reference/core/getTool), [`Mastra.getToolById()`](https://mastra.ai/reference/core/getToolById), [`Mastra.listTools()`](https://mastra.ai/reference/core/listTools), and the [`Agent` reference](https://mastra.ai/reference/agents/agent).
+If you need to access tools from the Mastra instance, see [`Mastra.getTool()`](https://mastra.ai/reference/core/getTool), [`Mastra.getToolById()`](https://mastra.ai/reference/core/getToolById), [`Mastra.listTools()`](https://mastra.ai/reference/core/listTools), and the [`Agent` reference](https://mastra.ai/reference/agents/agent).
 
 ## Shape output for the model
 
@@ -242,8 +258,8 @@ export const weatherTool = createTool({
 
     return {
       location,
-      temperature: data.current_condition[0].temp_F,
-      condition: data.current_condition[0].weatherDesc[0].value,
+      temperatureCelsius: Number(data.current_condition[0].temp_C),
+      conditions: data.current_condition[0].weatherDesc[0].value,
       weatherIconUrl: data.current_condition[0].weatherIconUrl[0].value,
       source: data,
     }
@@ -254,7 +270,7 @@ export const weatherTool = createTool({
       value: [
         {
           type: 'text',
-          text: `${output.location}: ${output.temperature}F and ${output.condition}`,
+          text: `${output.location}: ${output.temperatureCelsius}°C and ${output.conditions}`,
         },
         { type: 'image-url', url: output.weatherIconUrl },
       ],
@@ -358,23 +374,24 @@ export const weatherTool = createTool({
   id: 'weather-tool',
   description: 'Get weather information',
   inputSchema: z.object({
-    city: z.string(),
+    location: z.string(),
   }),
   outputSchema: z.object({
-    temperature: z.number(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
     conditions: z.string(),
   }),
   // Called when the complete input is available
   onInputAvailable: ({ input, toolCallId }) => {
-    console.log(`Weather requested for: ${input.city}`)
+    console.log(`Weather requested for: ${input.location}`)
   },
-  execute: async input => {
-    const weather = await fetchWeather(input.city)
+  execute: async ({ location }) => {
+    const weather = await fetchWeather(location)
     return weather
   },
   // Called after successful execution
   onOutput: ({ output, toolName }) => {
-    console.log(`${toolName} result: ${output.temperature}°F, ${output.conditions}`)
+    console.log(`${toolName} result: ${output.temperatureCelsius}°C, ${output.conditions}`)
   },
 })
 ```

package/.docs/docs/browser/agent-browser.md

@@ -105,5 +105,6 @@ This adds `browser_record` and `browser_record_caption` to the agent's toolset.
 
 - [Browser overview](https://mastra.ai/docs/browser/overview)
 - [Stagehand](https://mastra.ai/docs/browser/stagehand)
+- [Firecrawl](https://mastra.ai/docs/browser/firecrawl)
 - [Browser recording (alpha)](https://mastra.ai/docs/browser/recording)
 - [AgentBrowser reference](https://mastra.ai/reference/browser/agent-browser)

package/.docs/docs/browser/firecrawl.md

@@ -0,0 +1,129 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Firecrawl
+
+The `@mastra/browser-firecrawl` package provides browser automation using the [Firecrawl Browser Sandbox](https://docs.firecrawl.dev/features/browser). It provisions remote browser sessions through the Firecrawl API and drives them with the same deterministic, accessibility-first tools as [AgentBrowser](https://mastra.ai/docs/browser/agent-browser).
+
+`FirecrawlBrowser` extends `AgentBrowser`, so agents get the same toolset (`browser_goto`, `browser_snapshot`, `browser_click`, and so on) while the browser itself runs in Firecrawl's hosted infrastructure. No local Chromium install is needed.
+
+## When to use Firecrawl
+
+Use Firecrawl when you need:
+
+- Hosted browser sessions without managing local Chromium binaries
+- Browser automation in environments that can't launch a local browser
+- Per-thread sandbox isolation with automatic session cleanup
+- Named Firecrawl profiles that persist cookies and login state between sessions
+
+## Quickstart
+
+Install the package:
+
+**npm**:
+
+```bash
+npm install @mastra/browser-firecrawl
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/browser-firecrawl
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/browser-firecrawl
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/browser-firecrawl
+```
+
+Set your Firecrawl API key:
+
+```bash
+FIRECRAWL_API_KEY=fc-...
+```
+
+Create a browser instance and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { FirecrawlBrowser } from '@mastra/browser-firecrawl'
+
+const browser = new FirecrawlBrowser({
+  apiKey: process.env.FIRECRAWL_API_KEY,
+})
+
+export const firecrawlAgent = new Agent({
+  id: 'firecrawl-agent',
+  name: 'Firecrawl Agent',
+  model: 'openai/gpt-5.5',
+  browser,
+  instructions: `You are a web automation assistant.
+
+When interacting with pages:
+1. Use browser_snapshot to get the current page state and element refs
+2. Use the refs (like @e1, @e2) to target elements for clicks and typing
+3. After actions, take another snapshot to verify the result`,
+})
+```
+
+If `apiKey` is omitted, the provider reads `FIRECRAWL_API_KEY` from the environment.
+
+## Session scope
+
+`FirecrawlBrowser` follows the same `scope` option as `AgentBrowser`:
+
+- `'thread'` (default): Each conversation thread gets its own Firecrawl sandbox session. Sessions are deleted when the thread's browser closes.
+- `'shared'`: One Firecrawl sandbox session is shared across all threads and deleted when the browser closes.
+
+```typescript
+const browser = new FirecrawlBrowser({
+  scope: 'shared',
+})
+```
+
+## Session options
+
+Pass Firecrawl-specific session options under the `firecrawl` key. These map to the Firecrawl `browser()` API:
+
+```typescript
+const browser = new FirecrawlBrowser({
+  firecrawl: {
+    ttl: 600,
+    activityTtl: 120,
+    profile: {
+      name: 'my-profile',
+      saveChanges: true,
+    },
+  },
+})
+```
+
+- `ttl`: Maximum session lifetime in seconds.
+- `activityTtl`: Idle timeout in seconds before Firecrawl recycles the session.
+- `profile`: Named Firecrawl profile that persists cookies and login state. Set `saveChanges: true` to save profile changes when the session ends.
+
+> **Note:** The nested `firecrawl.profile` option refers to a profile stored in Firecrawl's infrastructure. It's different from the top-level `profile` option inherited from `AgentBrowser`, which is a local Playwright user-data directory path.
+
+## Self-hosted Firecrawl
+
+To use a self-hosted Firecrawl API, set `apiUrl`:
+
+```typescript
+const browser = new FirecrawlBrowser({
+  apiUrl: 'https://firecrawl.internal.example.com',
+})
+```
+
+## Related
+
+- [Browser overview](https://mastra.ai/docs/browser/overview)
+- [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
+- [Browser recording (alpha)](https://mastra.ai/docs/browser/recording)
+- [FirecrawlBrowser reference](https://mastra.ai/reference/browser/firecrawl-browser)

package/.docs/docs/browser/overview.md

@@ -4,10 +4,11 @@
 
 Browser support enables agents to navigate websites, interact with page elements, fill forms, and extract data. Mastra provides browser capabilities through SDK providers that wrap browser automation libraries and a CLI provider for agents that drive browsers through command-line tools.
 
-Mastra supports two SDK providers and one CLI provider:
+Mastra supports three SDK providers and one CLI provider:
 
 - [**AgentBrowser**](https://mastra.ai/docs/browser/agent-browser): A Playwright-based provider with accessibility-first element targeting. Best for general web automation and scraping.
 - [**Stagehand**](https://mastra.ai/docs/browser/stagehand): A Browserbase provider with AI-powered element detection. Best for complex interactions that benefit from natural language selectors.
+- [**FirecrawlBrowser**](https://mastra.ai/docs/browser/firecrawl): A Firecrawl Browser Sandbox provider that runs AgentBrowser tools against hosted browser sessions. Best for running automation on hosted browser sessions without managing local browser infrastructure.
 - [**BrowserViewer**](https://mastra.ai/docs/browser/browser-viewer): A CLI provider that launches Chrome and injects CDP URLs into CLI tools like agent-browser, browser-use, and browse. Best for workspace agents that drive browsers through shell commands.
 - [**Browser recording (alpha)**](https://mastra.ai/docs/browser/recording): An opt-in tool layer that saves browser sessions as Motion-JPEG AVI videos with optional captions.
 
@@ -86,7 +87,19 @@ The agent automatically receives all browser tools from the provider.
 
 ## Cloud providers
 
-Both SDK providers support connecting to cloud browser services instead of launching a local browser.
+All SDK providers support connecting to cloud browser services instead of launching a local browser.
+
+### Firecrawl Browser Sandbox (FirecrawlBrowser native)
+
+FirecrawlBrowser provisions hosted sessions through the Firecrawl API:
+
+```typescript
+import { FirecrawlBrowser } from '@mastra/browser-firecrawl'
+
+const browser = new FirecrawlBrowser({
+  apiKey: process.env.FIRECRAWL_API_KEY,
+})
+```
 
 ### Browserbase (Stagehand native)
 
@@ -167,6 +180,7 @@ const browser = new AgentBrowser({
 
 - [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
 - [Stagehand](https://mastra.ai/docs/browser/stagehand)
+- [Firecrawl](https://mastra.ai/docs/browser/firecrawl)
 - [Browser recording (alpha)](https://mastra.ai/docs/browser/recording)
 - [BrowserViewer](https://mastra.ai/docs/browser/browser-viewer)
 - [MastraBrowser reference](https://mastra.ai/reference/browser/mastra-browser)

package/.docs/docs/capabilities/channels/slack.md

@@ -63,7 +63,59 @@ Create the Slack app from a manifest:
 2. Select **Create an app**.
 3. Select **From a manifest**.
 4. Choose the workspace where the agent should run.
-5. Paste this manifest, then select **Create**:
+5. Paste this manifest, then select **Create**. Slack accepts JSON or YAML, so use whichever tab matches the format shown in the app creation modal:
+
+**JSON**:
+
+```json
+{
+  "display_information": {
+    "name": "mastra-agent"
+  },
+  "features": {
+    "app_home": {
+      "home_tab_enabled": false,
+      "messages_tab_enabled": true,
+      "messages_tab_read_only_enabled": false
+    },
+    "bot_user": {
+      "display_name": "mastra-agent",
+      "always_online": true
+    }
+  },
+  "oauth_config": {
+    "scopes": {
+      "bot": [
+        "im:write",
+        "app_mentions:read",
+        "channels:history",
+        "channels:read",
+        "chat:write",
+        "users:read",
+        "im:read",
+        "im:history"
+      ]
+    },
+    "pkce_enabled": false
+  },
+  "settings": {
+    "event_subscriptions": {
+      "request_url": "https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook",
+      "bot_events": ["app_mention", "message.channels", "message.im"]
+    },
+    "interactivity": {
+      "is_enabled": true,
+      "request_url": "https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook"
+    },
+    "org_deploy_enabled": false,
+    "socket_mode_enabled": false,
+    "token_rotation_enabled": false,
+    "is_mcp_enabled": false
+  }
+}
+```
+
+**YAML**:
 
 ```yaml
 display_information:
@@ -211,12 +263,70 @@ Mention the bot in the channel:
 
 The agent responds in the thread. Response content depends on the model, instructions, memory, and tools configured on the agent.
 
+## Authentication
+
+The Slack adapter has no built-in user allowlist. Once the app is installed, anyone in the workspace can talk to the agent by sending it a direct message or mentioning it in a channel where it's a member. Slack verifies each request with the signing secret, and Mastra runs the agent for every valid message the webhook receives.
+
+The main mechanism for controlling access is channel membership. The bot only receives events from direct messages and from channels it has been invited to, so the set of channels the bot belongs to defines who can reach it. Keep the bot out of channels where it shouldn't respond, and remove it from a channel to cut off access.
+
+For finer control, gate on the sender's identity. Every request carries the sender's Slack user ID in the channel [request context](#request-context), so you can allow or deny specific users in an input processor or tool before the agent acts.
+
+### Server authentication
+
+The Slack webhook route is exempt from Mastra's [server authentication](https://mastra.ai/docs/server/auth). Slack can't send a bearer token, so Mastra registers the channel webhook as a public route and verifies each request with the Slack signing secret instead. This holds even when you enable a provider like [`MastraAuthSimple`](https://mastra.ai/docs/server/auth/simple-auth): the rest of your API stays protected, but the webhook route relies on the signing secret rather than your server auth. Keep `SLACK_SIGNING_SECRET` set so the adapter can reject requests that Slack didn't sign.
+
+### External channels
+
+Shared channels ([Slack Connect](https://slack.com/connect)) let people from other workspaces join a conversation. If a workspace member adds the bot to a shared channel, everyone in that channel can talk to the agent, including external members outside your organization. Anyone who can reach the agent can also reach the tools and data it has access to.
+
+Treat adding the bot to a shared or external channel as granting those participants access to the agent. Before you do, confirm the agent's tools and data are safe to expose to outside members, and gate on the sender's user ID when you need to restrict who the agent responds to.
+
+## Request context
+
+On every message, Mastra places a channel context object on the [request context](https://mastra.ai/docs/server/request-context) under the `channel` key. It carries the sender's Slack display name and user ID, the bot's own identity, and details about where the message came from. Read it from an input processor or a tool to identify the user or branch on the conversation type:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import type { ChannelContext } from '@mastra/core/channels'
+import { z } from 'zod'
+
+export const whoami = createTool({
+  id: 'whoami',
+  description: 'Return the Slack identity of the current user',
+  inputSchema: z.object({}),
+  execute: async (_input, context) => {
+    const channel = context?.requestContext?.get('channel') as ChannelContext | undefined
+
+    return {
+      platform: channel?.platform,
+      userId: channel?.userId,
+      userName: channel?.userName,
+      isDM: channel?.isDM,
+    }
+  },
+})
+```
+
+The channel context includes:
+
+- `botMention`, `botUserId`, and `botUserName`: The bot's own identity on Slack.
+- `channelId` and `threadId`: The Slack channel and thread the message arrived on.
+- `isDM`: Whether the message is a direct message.
+- `platform`: The platform identifier, `slack` for this adapter.
+- `userId` and `userName`: The sender's Slack user ID and display name.
+
+Mastra also turns this context into a short system message. The agent learns the platform and its own identity, plus whether the conversation is a direct message or a public channel. See [thread context](https://mastra.ai/docs/capabilities/channels/overview) in the channels overview for how to change that behavior.
+
 ## Production deployment
 
 When you deploy the Mastra server, update both request URLs in the Slack app settings to the production webhook URL. The tunnel URL used for local development is temporary and changes when the tunnel restarts.
 
 Channels on serverless platforms may need `waitUntil` and shared pub/sub configuration so background responses and thread leases work across short-lived instances. See [serverless deployment](https://mastra.ai/docs/capabilities/channels/overview) in the channels overview.
 
+### Idle servers
+
+Platform servers scale down to idle when they aren't receiving traffic, and that's fine for Slack. The next event, such as a mention or direct message, wakes the server by delivering its webhook request, and the server resumes handling requests. The first response after the server has been idle can take a little longer while it starts up, which is expected. Slack expects a `200` acknowledgement within 3 seconds and retries the event up to three times when delivery fails or times out, so a very slow cold start may take a retry before the agent responds. Subsequent messages respond at normal speed while the server stays warm.
+
 ## Related
 
 - [Channels overview](https://mastra.ai/docs/capabilities/channels/overview)