@mastra/mcp-docs-server 1.2.7-alpha.12 → 1.2.7-alpha.4

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

@@ -8,17 +8,6 @@ Tool providers let Builder-created agents call tools from third-party apps such
 
 This page covers what's specific to the Builder: setting up connections, choosing a connection scope, and managing connections. To register a provider and enable its toolkits, see [Tools](https://mastra.ai/docs/editor/tools).
 
-## Setup at a glance
-
-To connect a toolkit like Gmail and use it from a Builder agent:
-
-1. [Register a tool provider](#register-a-tool-provider) on `MastraEditor` with your Composio API key.
-2. [Set up a Composio auth config](#set-up-a-composio-auth-config) for the toolkit and enable it.
-3. [Connect the toolkit](#connect-a-toolkit) from the Builder and complete the OAuth flow.
-4. [Choose a connection scope](#connection-scope) if the default author-owned account isn't what you want.
-
-The rest of this page covers each step in detail.
-
 ## Prerequisites
 
 Before agents can use integration tools in the Builder:
@@ -53,8 +42,6 @@ export const mastra = new Mastra({
 
 Each provider's toolkits become available in the Builder once it's registered. Use `allowedToolkits` to restrict which toolkits the provider exposes — by slug, such as `gmail` or `googlecalendar`. Omit it to expose every toolkit the provider offers. To add another provider, import it and add another entry to `toolProviders`. For the full list of providers and their options, see [Tools — Integration providers](https://mastra.ai/docs/editor/tools).
 
-`ComposioToolProvider` needs a Composio **project** API key (the `x-api-key` type from a project's settings in the [Composio dashboard](https://dashboard.composio.dev)). Store it in an environment variable, as shown with `COMPOSIO_API_KEY` above.
-
 ## Set up a Composio auth config
 
 Each toolkit a user can connect needs its own auth config in the [Composio dashboard](https://dashboard.composio.dev). An auth config defines how Composio authenticates with an app — its OAuth client, scopes, and credentials. Each toolkit needs its own because requirements vary by app: some share common OAuth methods, while others need extra setup. Without an enabled config, the connection flow fails.
@@ -65,7 +52,7 @@ Each toolkit a user can connect needs its own auth config in the [Composio dashb
 
 Keep exactly one auth config enabled per toolkit. When a user connects the toolkit, the provider resolves the single enabled config for that toolkit and starts the OAuth flow against it.
 
-> **Warning:** The provider throws if a toolkit has zero enabled auth configs or more than one. With no enabled config, the connection flow fails with an error like `No ENABLED auth config for toolkit "github"` — enable one in the Composio dashboard to fix it. Enable exactly one auth config per toolkit you expose in the Builder.
+> **Warning:** The provider throws if a toolkit has zero enabled auth configs or more than one. Enable exactly one auth config per toolkit you expose in the Builder.
 
 ## Connect a toolkit
 
@@ -78,36 +65,7 @@ The connected account is bound to the agent, and its tools are ready to use on t
 
 ## Connection scope
 
-Each connection determines which account a tool call uses at runtime, and its _scope_ controls who shares that credential. A scope maps each call to a _bucket_ — the identity partition that a connected account is stored under. Scope is a tenancy decision made by you, the app author, not by the end user connecting an account — so you set it on the provider, not in the Builder UI.
-
-- `per-author` (default): the connection belongs to the agent's author. Any invoker runs the agent with the author's account. Use this for personal agents or a single shared team account.
-- `shared`: every caller uses one shared bucket, regardless of who invokes the agent. Use this for a platform-owned account that all users should share.
-- `caller-supplied`: each call is bucketed by the caller's `resourceId`, read from the request context. Use this for multi-tenant SaaS, where the host app authenticates the end user upstream and each tenant should use their own connected account.
-
-Set `defaultScope` on the provider to apply a scope to every connection authorized against it:
-
-```typescript
-const composio = new ComposioToolProvider({
-  apiKey: process.env.COMPOSIO_API_KEY!,
-  allowedToolkits: ['github'],
-  defaultScope: 'caller-supplied',
-})
-```
-
-With `caller-supplied`, the host app must forward a `resourceId` on every request so each tenant lands in its own bucket. Set `mapUserToResourceId` on the server's auth config to derive the `resourceId` from the authenticated user, so every request carries it automatically:
-
-```typescript
-export const mastra = new Mastra({
-  server: {
-    auth: {
-      authenticateToken: async token => verifyToken(token),
-      mapUserToResourceId: user => user.id,
-    },
-  },
-})
-```
-
-> **Warning:** When a `caller-supplied` connection runs without a `resourceId`, every tenant falls back to a single shared `default` bucket. All callers then share one set of credentials, which can expose one tenant's connected account to another. Always wire `mapUserToResourceId` (or otherwise set `resourceId` on the request context) for multi-tenant deployments.
+When you select a toolkit's tools for an agent, you also pin a connection. The connection determines which account each tool call uses at runtime, with a scope that controls who shares the credential. Today connections are `per-author`: the connection belongs to the agent's author, and any invoker runs the agent with the author's account.
 
 ## Related
 

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

@@ -4,9 +4,9 @@
 
 > **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.
 
-The Agent Builder lets you build, configure, and operate Mastra agents all within the UI. It runs inside your Mastra server, persists everything to `Mastra.storage`, and supports multi-tenant agent workflows with RBAC and channel integrations.
+[YouTube video player](https://www.youtube-nocookie.com/embed/AbdgIu4Z07I)
 
-> **📹 Watch:** Watch [Mastra Agent Builder overview](https://www.youtube.com/watch?v=AbdgIu4Z07I) to see how teams create and configure agents from the UI.
+The Agent Builder lets you build, configure, and operate Mastra agents all within the UI. It runs inside your Mastra server, persists everything to `Mastra.storage`, and supports multi-tenant agent workflows with RBAC and channel integrations.
 
 - [**Configuration**](https://mastra.ai/docs/agent-builder/configuration): Toggle UI sections and pin admin-controlled defaults for every new agent.
 - [**Model policy**](https://mastra.ai/docs/agent-builder/model-policy): Restrict which providers and models the Builder exposes, and pin a default.
@@ -108,5 +108,4 @@ Omitting the `builder` field has the same effect.
 
 - [Configuration](https://mastra.ai/docs/agent-builder/configuration): Toggle Builder surfaces and pin defaults for new agents.
 - [Access control](https://mastra.ai/docs/agent-builder/access-control): Gate the Builder with authentication and role-based access control.
-- [Deploying](https://mastra.ai/docs/agent-builder/deploying): Replace local development primitives with production-ready storage, filesystems, and sandboxes.
-- 📹 [Mastra Agent Builder workshop](https://www.youtube.com/watch?v=p2p_wb-rUPg\&t=666s)
+- [Deploying](https://mastra.ai/docs/agent-builder/deploying): Replace local development primitives with production-ready storage, filesystems, and sandboxes.

package/.docs/docs/agent-builder/skill-registries.md

@@ -23,7 +23,9 @@ new MastraEditor({
 })
 ```
 
-The Builder library tab now exposes a **Browse** view backed by skills.sh. End users can preview a skill, then install it into an agent. See the [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) for the full `registries` schema.
+The Builder library tab now exposes a **Browse** view backed by skills.sh. End users can preview a skill, then install it into an agent.
+
+> **Note:** See the [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) for the full `registries` schema.
 
 ## Related
 

package/.docs/docs/agent-controller/overview.md

@@ -88,7 +88,7 @@ await agentController.selectOrCreateThread()
 await agentController.sendMessage({ content: 'Hello!' })
 ```
 
-Visit the [AgentController reference](https://mastra.ai/reference/agent-controller/agent-controller-class) for the full constructor parameters and method signatures.
+> **Note:** Visit the [AgentController reference](https://mastra.ai/reference/agent-controller/agent-controller-class) for the full constructor parameters and method signatures.
 
 ## Architecture
 
@@ -128,5 +128,4 @@ Your app sends commands — send a message, switch mode, approve a tool call —
 - [Threads and state](https://mastra.ai/docs/agent-controller/threads-and-state): Manage persistent conversations
 - [Subagents](https://mastra.ai/docs/agent-controller/subagents): Delegate focused subtasks
 - [Tool approvals and permissions](https://mastra.ai/docs/agent-controller/tool-approvals): Human-in-the-loop gating
-- [API reference](https://mastra.ai/reference/agent-controller/agent-controller-class): Full constructor and method docs
-- 📹 [Mastra AgentController harness workshop](https://www.youtube.com/watch?v=tV1pSleP-LM)
+- [API reference](https://mastra.ai/reference/agent-controller/agent-controller-class): Full constructor and method docs

package/.docs/docs/agent-controller/session.md

@@ -133,7 +133,9 @@ agentController.subscribe(event => {
 })
 ```
 
-This is the recommended pattern for most UIs. Subscribe to individual typed events only when you need to react to a specific transition rather than re-render the whole view. Visit the [Session reference](https://mastra.ai/reference/agent-controller/session) for the full list of sub-objects and method signatures.
+This is the recommended pattern for most UIs. Subscribe to individual typed events only when you need to react to a specific transition rather than re-render the whole view.
+
+> **Note:** Visit the [Session reference](https://mastra.ai/reference/agent-controller/session) for the full list of sub-objects and method signatures.
 
 ## Related
 

package/.docs/docs/agents/a2a.md

@@ -261,5 +261,4 @@ Use this hook to enforce expected providers, expected endpoints, certificate-bou
 - [Agent reference](https://mastra.ai/reference/agents/agent)
 - [JavaScript client agents reference](https://mastra.ai/reference/client-js/agents)
 - [A2A core concepts](https://a2a-protocol.org/latest/topics/key-concepts/)
-- [A2A discovery guide](https://a2a-protocol.org/latest/topics/agent-discovery/)
-- 📹 [Agent-to-agent with Mastra workshop](https://www.youtube.com/watch?v=LQDzyNGm-aw)
+- [A2A discovery guide](https://a2a-protocol.org/latest/topics/agent-discovery/)

package/.docs/docs/agents/channels.md

@@ -0,0 +1,225 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Channels
+
+**Added in:** `@mastra/core@1.22.0`
+
+Channels connect your agents to messaging platforms like Slack, Discord, and Telegram. When a user sends a message on a platform, the agent receives it, processes it through the normal agent pipeline, and streams the response back to the conversation.
+
+## When to use channels
+
+Use channels when you want your agent to:
+
+- Respond to messages in Slack workspaces, Discord servers, or Telegram chats
+- Handle both direct messages and mentions in group conversations
+
+## Quickstart
+
+Configure channels directly on your agent using adapters from the [Chat SDK](https://chat-sdk.dev/adapters):
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createSlackAdapter } from '@chat-adapter/slack'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  instructions: 'You are a helpful support assistant.',
+  model: 'openai/gpt-5.5',
+  channels: {
+    adapters: {
+      slack: createSlackAdapter(),
+    },
+  },
+})
+```
+
+Register the agent in your Mastra instance with storage so channel state persists across restarts:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { LibSQLStore } from '@mastra/libsql'
+import { supportAgent } from './agents/support-agent'
+
+export const mastra = new Mastra({
+  agents: { supportAgent },
+  storage: new LibSQLStore({
+    url: process.env.DATABASE_URL,
+  }),
+})
+```
+
+Each adapter reads credentials from environment variables by default.
+
+## Platform setup
+
+Each platform requires credentials and event configuration. See the Chat SDK adapter docs for full setup: [Slack](https://chat-sdk.dev/adapters/slack), [Discord](https://chat-sdk.dev/adapters/discord), [Telegram](https://chat-sdk.dev/adapters/telegram).
+
+Mastra generates a webhook route for each platform at:
+
+```text
+/api/agents/{agentId}/channels/{platform}/webhook
+```
+
+For example: `/api/agents/support-agent/channels/slack/webhook`
+
+Point your platform's webhook or interactions URL to this path.
+
+### Local development
+
+Platform webhooks need a public URL to reach your local server. Use a tunnel to expose `localhost:4111`:
+
+```bash
+# ngrok
+ngrok http 4111
+
+# cloudflared
+npx cloudflared tunnel --url http://localhost:4111
+```
+
+Copy the generated URL and use it as the base for your webhook paths (e.g. `https://abc123.ngrok.io/api/agents/support-agent/channels/slack/webhook`).
+
+## Thread context
+
+When a user mentions the agent mid-conversation in a channel thread, the agent may not have prior context. By default, Mastra fetches the last 10 messages from the platform on the first mention.
+
+1. On the **first mention** in a thread, the agent fetches recent messages from the platform.
+2. These messages are prepended to the user's message as conversation context.
+3. After responding, the agent subscribes to the thread and has full history via Mastra's memory.
+4. Subsequent messages in that thread **don't** re-fetch from the platform.
+
+Set `threadContext: { maxMessages: 0 }` to disable this behavior. This only applies to non-DM threads.
+
+Mastra also adds a short system message telling the agent which channel and platform the request came from (DM vs public channel, platform name, bot display name). Set `threadContext: { addSystemMessage: false }` to skip it.
+
+## Tool approval
+
+Tools with `requireApproval: true` render as interactive cards with Approve and Deny buttons:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+const deleteFile = createTool({
+  id: 'delete-file',
+  description: 'Delete a file from the system',
+  inputSchema: z.object({
+    path: z.string().describe('Path to the file to delete'),
+  }),
+  requireApproval: true,
+  execute: async ({ path }) => {
+    await fs.unlink(path)
+    return { deleted: path }
+  },
+})
+```
+
+When the agent calls this tool, users see a card with the tool name, arguments, and Approve/Deny buttons. The tool only executes after approval.
+
+Set `toolDisplay: 'text'` on an adapter to render tool calls as plain text instead of interactive cards. In `'hidden'` mode the agent uses `autoResumeSuspendedTools` to let the LLM decide based on the conversation context, since hidden mode doesn't post approval buttons.
+
+## Multi-user awareness
+
+In group conversations, Mastra automatically prefixes each message with the sender's name and platform ID so the agent can distinguish between speakers:
+
+```text
+[Alice (@U123ABC)]: Can you help me with this?
+[Bob (@U456DEF)]: I have a question too.
+```
+
+## Multimodal content
+
+Models like Gemini can natively process images, video, and audio. Combine `inlineMedia` and `inlineLinks` to let users share rich content with your agent across platforms:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createDiscordAdapter } from '@chat-adapter/discord'
+import { google } from '@ai-sdk/google'
+
+export const visionAgent = new Agent({
+  id: 'vision-agent',
+  name: 'Vision Agent',
+  instructions: 'You can see images, watch videos, and listen to audio.',
+  model: google('gemini-3.1-flash-image-preview'),
+  channels: {
+    adapters: {
+      discord: createDiscordAdapter(),
+    },
+    inlineMedia: ['image/*', 'video/*', 'audio/*'],
+    inlineLinks: [
+      // Gemini treats YouTube URLs as native video file parts
+      { match: 'youtube.com', mimeType: 'video/*' },
+      { match: 'youtu.be', mimeType: 'video/*' },
+      'imgur.com', // HEAD-check imgur links; inline as file part if mimeType matches inlineMedia
+    ],
+  },
+})
+```
+
+With this configuration:
+
+- A user uploads a screenshot and the agent describes what it sees
+- A user uploads an `.mp4` clip and the agent summarizes the video
+- A user pastes a YouTube link and the agent watches and discusses the video
+- A user pastes an imgur link and the agent sees the image directly
+
+By default, only images are sent inline (`inlineMedia: ['image/*']`). Unsupported types are described as text summaries so the agent knows about the file without crashing models that reject them.
+
+> **Note:** See [Channels reference](https://mastra.ai/reference/agents/channels) for all `inlineMedia` patterns and [inlineLinks reference](https://mastra.ai/reference/agents/channels) for domain matching, HEAD detection, and forced mime types.
+
+## Serverless deployment
+
+On serverless platforms like Vercel, each request runs in a separate, short-lived instance. Channels need two things to work reliably in that environment: a way to keep the function alive while the agent responds, and a shared pub/sub so instances can coordinate.
+
+### Keep the function alive with `waitUntil`
+
+A channel webhook returns a `200` response right away, then the agent runs in the background to post its reply. On most serverless platforms the function is frozen as soon as it responds, which kills the run before the agent answers. Pass a `waitUntil` function so the platform keeps the instance alive until the run finishes.
+
+On Vercel, pass `waitUntil` from `@vercel/functions`:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createSlackAdapter } from '@chat-adapter/slack'
+import { waitUntil } from '@vercel/functions'
+
+export const agent = new Agent({
+  id: 'agent',
+  channels: {
+    adapters: {
+      slack: createSlackAdapter(),
+    },
+    waitUntil,
+  },
+})
+```
+
+Vercel and AWS Lambda require `waitUntil`, since they freeze the function as soon as the response is sent. Cloudflare Workers and Netlify Functions are detected automatically from the request context, so they don't need it. For runtimes where `waitUntil` lives on the request context but isn't detected automatically, use `resolveWaitUntil`. See the [Channels reference](https://mastra.ai/reference/agents/channels) for details.
+
+### Coordinate instances with a shared pub/sub
+
+Channels route messages through the agent's signal pipeline, and each run acquires a lease on its thread so a single run owns the conversation at a time. The default in-memory pub/sub can't cross instance boundaries, so on serverless a follow-up message can land on a different instance than the one running the agent. Without a shared pub/sub, that instance can't reach the active run and starts its own, leaving the original run untouched and the thread processed twice.
+
+Configure a shared pub/sub backed by Redis Streams on the `Mastra` instance so leases and signals coordinate across instances:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { RedisStreamsPubSub } from '@mastra/redis-streams'
+
+export const mastra = new Mastra({
+  agents: { agent },
+  pubsub: new RedisStreamsPubSub({
+    url: process.env.REDIS_URL,
+    keyPrefix: 'mastra:my-app',
+  }),
+})
+```
+
+Vercel's managed Redis integration and Upstash Redis both work well. For more on when a distributed pub/sub is needed, see the [PubSub guide](https://mastra.ai/docs/server/pubsub) and the [`RedisStreamsPubSub` reference](https://mastra.ai/reference/pubsub/redis-streams).
+
+## Related
+
+- [Guide: Building a Slack assistant](https://mastra.ai/guides/guide/slack-assistant)
+- [Agent overview](https://mastra.ai/docs/agents/overview)
+- [Tool approval](https://mastra.ai/docs/agents/agent-approval)
+- [Channels reference](https://mastra.ai/reference/agents/channels)
+- [Chat SDK adapters](https://chat-sdk.dev/adapters)

package/.docs/docs/agents/code-mode.md

@@ -94,7 +94,7 @@ For `createCodeMode()` to work well, keep these tips in mind:
 - Keep tools focused, so each does one thing well and the model composes them in code.
 - Code mode helps most when calls can be parallelized with `Promise.all`.
 
-Visit the [`createCodeMode()` reference](https://mastra.ai/reference/tools/create-code-mode) for configuration options, return values, result shape, and instructions inspection.
+> **Note:** Visit the [`createCodeMode()` reference](https://mastra.ai/reference/tools/create-code-mode) for configuration options, return values, result shape, and instructions inspection.
 
 ## Scoping tools across multiple code tools