@mastra/mcp-docs-server 1.2.13-alpha.0 → 1.2.13-alpha.11

package/README.md

@@ -4,7 +4,7 @@ Access Mastra's documentation via [Model Context Protocol (MCP)](https://modelco
 
 ## Usage
 
-Follow the [official installation](https://mastra.ai/docs/getting-started/mcp-docs-server) instructions.
+Follow the [official installation](https://mastra.ai/reference/build-with-ai#mcp-docs-server) instructions.
 
 ## Tools
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.13-alpha.0",
+  "version": "1.2.13-alpha.11",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,8 +28,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.55.0",
-    "@mastra/mcp": "^1.15.0"
+    "@mastra/core": "1.56.0-alpha.6",
+    "@mastra/mcp": "^1.15.1-alpha.1"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.14",
@@ -45,9 +45,9 @@
     "tsx": "^4.23.1",
     "typescript": "^6.0.3",
     "vitest": "4.1.10",
+    "@mastra/core": "1.56.0-alpha.6",
     "@internal/lint": "0.0.119",
-    "@internal/types-builder": "0.0.94",
-    "@mastra/core": "1.55.0"
+    "@internal/types-builder": "0.0.94"
   },
   "homepage": "https://mastra.ai",
   "repository": {

package/.docs/docs/agent-builder/access-control.md

@@ -1,99 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Access control
-
-> **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 includes with two supported roles: `admin` and `member`. Wire them through `Mastra.server.rbac`. Without an RBAC provider, every authenticated user has full Builder access; without authentication, the Builder is open to anyone who can reach the server.
-
-## Roles
-
-| Role     | Permissions         | What they can do                                                                                |
-| -------- | ------------------- | ----------------------------------------------------------------------------------------------- |
-| `admin`  | `*`                 | Full access. Create, edit, publish, and delete agents and skills. Manage every Builder surface. |
-| `member` | scoped list (below) | Open the Builder, browse agents and skills, populate pickers, and chat with the Builder agent.  |
-
-## Minimum permissions
-
-The Builder UI calls several resources on load, so a usable `member` role needs explicit grants on each. The Builder action layer (`/agent-builder/*`) is one resource. The data it reads and writes lives under separate resources.
-
-| Permission                            | Used for                                                                                                                                                    |
-| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `agent-builder:*`                     | Load Builder actions and run Builder workflows. The derived Builder actions are `agent-builder:read` and `agent-builder:execute`. The wildcard grants both. |
-| `agents:read`, `agents:execute`       | List registered agents and chat with the Builder agent                                                                                                      |
-| `stored-agents:*`                     | List, view, create, and edit agents                                                                                                                         |
-| `stored-skills:*`                     | List, view, create, and edit stored skills                                                                                                                  |
-| `stored-workspaces:*`                 | Pick a workspace when editing an agent                                                                                                                      |
-| `tools:read`, `tools:execute`         | Populate the tool picker and run tools through agents                                                                                                       |
-| `workflows:read`, `workflows:execute` | Populate the workflow picker and run workflows through agents                                                                                               |
-| `memory:read`                         | Preview memory configuration in the picker                                                                                                                  |
-| `channels:read`                       | Show Slack/channel chips on agent pages                                                                                                                     |
-| `infrastructure:read`                 | Builder diagnostics banner on the shell                                                                                                                     |
-
-Grant `:write`, `:delete`, and `:publish` on `stored-agents` and `stored-skills` for users who should create or modify agents. The `:*` wildcards in the table above cover those actions. `admin` covers everything through the `*` wildcard.
-
-## Quickstart with WorkOS
-
-`@mastra/auth-workos` provides `MastraAuthWorkos` for SSO and `MastraRBACWorkos` for role-based access. Map WorkOS organization roles to the Builder's `admin` and `member` roles via `roleMapping`:
-
-```typescript
-import { MastraAuthWorkos, MastraRBACWorkos } from '@mastra/auth-workos'
-
-export const mastraAuth = new MastraAuthWorkos({
-  redirectUri: process.env.WORKOS_REDIRECT_URI || 'http://localhost:4111/api/auth/callback',
-})
-
-export const rbacProvider = new MastraRBACWorkos({
-  roleMapping: {
-    admin: ['*'],
-    member: [
-      'agent-builder:*',
-      'agents:read',
-      'agents:execute',
-      'stored-agents:*',
-      'stored-skills:*',
-      'stored-workspaces:*',
-      'tools:read',
-      'tools:execute',
-      'workflows:read',
-      'workflows:execute',
-      'memory:read',
-      'channels:read',
-      'infrastructure:read',
-    ],
-    _default: [],
-  },
-})
-```
-
-Register both providers on the Mastra server:
-
-```typescript
-import { Mastra } from '@mastra/core/mastra'
-import { mastraAuth, rbacProvider } from './auth'
-
-export const mastra = new Mastra({
-  server: {
-    auth: mastraAuth,
-    rbac: rbacProvider,
-  },
-  // ...storage, agents, editor
-})
-```
-
-`_default` covers WorkOS roles not listed in the mapping. Omit it to deny unmapped users. Set `WORKOS_API_KEY` and `WORKOS_CLIENT_ID` in your environment.
-
-## Permission grammar
-
-Permission patterns follow `resource:action`. Wildcards are supported on either side:
-
-- `*`: Full access (every resource, every action). Used by `admin`.
-- `agent-builder:*`: Every action on the `agent-builder` resource.
-- `*:read`: `read` Across every resource.
-
-Patterns resolve through `matchesPermission()`. The first matching role permission grants the action.
-
-## Related
-
-- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Wire RBAC alongside the rest of the Builder config.
-- [Deploying](https://mastra.ai/docs/agent-builder/deploying): Auth, RBAC, and EE license setup for production.

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

@@ -1,63 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Browser
-
-> **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 can give end-user agents a browser tool driven by a registered provider. Unlike filesystems and sandboxes, **there are no built-in browser providers** and you must register one through `MastraEditor.browsers`.
-
-## Quickstart
-
-Register a browser provider on `MastraEditor`, then pin it as the Builder default through `builder.configuration.agent.browser`:
-
-```typescript
-import { MastraEditor } from '@mastra/editor'
-import { StagehandBrowser } from '@mastra/stagehand'
-
-new MastraEditor({
-  browsers: {
-    stagehand: {
-      id: 'stagehand',
-      name: 'Stagehand Browser',
-      createBrowser: config =>
-        new StagehandBrowser({
-          ...config,
-          apiKey: process.env.BROWSERBASE_API_KEY ?? '',
-          env: 'BROWSERBASE',
-          projectId: process.env.BROWSERBASE_PROJECT_ID ?? '',
-        }),
-    },
-  },
-  builder: {
-    enabled: true,
-    configuration: {
-      agent: {
-        browser: {
-          type: 'inline',
-          config: { provider: 'stagehand', headless: true },
-        },
-      },
-    },
-  },
-})
-```
-
-## Browser providers
-
-`MastraEditor.browsers` accepts a `Record<string, BrowserProvider>`. Each provider exposes:
-
-- `id`: Provider identifier, matched against `StorageBrowserConfig.provider` (e.g., `'stagehand'`).
-- `name`: Display name shown in the Builder UI.
-- `createBrowser(config)`: Hydrates a stored browser config into a runtime `MastraBrowser`. This is where you inject runtime-only credentials (API keys, project IDs) that aren't stored in the agent snapshot.
-
-Browser classes release as separate packages (e.g., `@mastra/stagehand`, `@mastra/agent-browser`). The provider entry is a plain object wrapping the class, register one entry per browser you want the Builder to expose to end users. See the [StorageBrowserRef reference](https://mastra.ai/reference/editor/storage-browser-ref) for the full `browser` field schema, including all `StorageBrowserConfig` options.
-
-## Feature toggle
-
-The `features.agent.browser` toggle controls whether end users can enable browser access per agent in the Builder UI. It defaults to `true` only when a valid `configuration.agent.browser` (with a `config.provider`) is provided. Without a registered provider matching the pinned config, the toggle is forced off.
-
-## Related
-
-- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults): The full `browser` field schema.
-- [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options): The full Builder config surface, including `features.agent.browser`.
-- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Wire `browser` alongside the rest of the Builder config.

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

@@ -1,78 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Channels
-
-> **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.
-
-Channels let Builder-created agents reach users outside the Mastra server. Register a channel provider on `Mastra.channels` and the Builder exposes the channel as an integration option for every agent.
-
-Slack is currently the only supported channel.
-
-## Quickstart
-
-Install the Slack provider:
-
-**npm**:
-
-```bash
-npm install @mastra/slack
-```
-
-**pnpm**:
-
-```bash
-pnpm add @mastra/slack
-```
-
-**Yarn**:
-
-```bash
-yarn add @mastra/slack
-```
-
-**Bun**:
-
-```bash
-bun add @mastra/slack
-```
-
-Register `SlackProvider` on `Mastra.channels`:
-
-```typescript
-import { Mastra } from '@mastra/core/mastra'
-import { MastraEditor } from '@mastra/editor'
-import { createBuilderAgent } from '@mastra/editor/ee'
-import { SlackProvider } from '@mastra/slack'
-
-export const mastra = new Mastra({
-  storage,
-  channels: {
-    slack: new SlackProvider({
-      refreshToken: process.env.SLACK_APP_CONFIG_REFRESH_TOKEN,
-      baseUrl: process.env.SLACK_BASE_URL,
-    }),
-  },
-  agents: { builderAgent: createBuilderAgent() },
-  editor: new MastraEditor({
-    builder: { enabled: true },
-  }),
-})
-```
-
-The Slack provider handles app creation, OAuth, slash commands, and message routing for every Builder-created agent that opts in.
-
-## Configuration
-
-`SlackProvider` requires one environment variable and accepts one optional override:
-
-- `SLACK_APP_CONFIG_REFRESH_TOKEN` (required): The refresh token from your Slack app configuration tokens, available under **Your App Configuration Tokens** on [api.slack.com/apps](https://api.slack.com/apps). The refresh token doesn't expire, but the access tokens it issues rotate every 12 hours and are auto-persisted to `Mastra.storage`.
-- `baseUrl` (optional): The public URL Slack should send events and OAuth callbacks to. Defaults to the running Mastra server's host and port (for example, `http://localhost:4111` in local development). Pass `baseUrl` explicitly when the public URL differs from the server's resolved address: typically a tunnel for local development (`cloudflared tunnel --url http://localhost:4111`) or a deployed URL in production.
-
-## Storage requirement
-
-`SlackProvider` requires a persistent storage backend on the `Mastra` instance. Without storage, rotated tokens and app installations are lost on restart.
-
-## Related
-
-- [Deploying](https://mastra.ai/docs/agent-builder/deploying): Set a public `baseUrl` for production deployments.
-- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Wire channel toggles into the Builder UI.

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

@@ -1,132 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Configuration
-
-> **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 is configured through `MastraEditor.builder`. Top-level keys control its behavior: `features` toggles UI visibility and `configuration` pins admin-controlled defaults onto every new agent.
-
-## Quickstart
-
-```typescript
-import { MastraEditor } from '@mastra/editor'
-
-new MastraEditor({
-  builder: {
-    enabled: true,
-    features: {
-      agent: { browser: false },
-    },
-    configuration: {
-      agent: {
-        memory: { observationalMemory: true },
-      },
-    },
-  },
-})
-```
-
-This hides the browser tab in the Builder UI and pins observational memory as the default for every Builder-created agent.
-
-## Feature toggles
-
-`builder.features.agent` controls which sections appear in the Agent Builder UI. Set a key to `false` to hide the corresponding surface.
-
-```typescript
-new MastraEditor({
-  builder: {
-    enabled: true,
-    features: {
-      agent: {
-        tools: true,
-        agents: true,
-        workflows: true,
-        scorers: true,
-        skills: true,
-        memory: true,
-        variables: true,
-        favorites: true,
-        avatarUpload: true,
-        model: true,
-        browser: true,
-      },
-    },
-  },
-})
-```
-
-The UI consumes these `AgentFeatures` keys: `tools`, `agents`, `workflows`, `scorers`, `skills`, `memory`, `variables`, `favorites`, `avatarUpload`, `model`, and `browser`. See the [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) for the full schema.
-
-## Admin defaults
-
-`builder.configuration.agent` pins admin-controlled defaults onto every agent the Builder produces.
-
-`configuration.agent` accepts `models`, `memory`, `workspace`, `browser`, `tools`, `agents`, and `workflows`. See the [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) for the full shape.
-
-## Making tools, agents, and workflows available
-
-The Builder picks from whatever you register on the `Mastra` instance. Tools registered through `Mastra({ tools })`, agents registered through `Mastra({ agents })`, and workflows registered through `Mastra({ workflows })` are all candidates for Builder-created agents.
-
-```typescript
-import { Mastra } from '@mastra/core/mastra'
-import { MastraEditor } from '@mastra/editor'
-import { createBuilderAgent } from '@mastra/editor/ee'
-import { weatherInfo } from './tools/weather-info'
-import { webSearch } from './tools/web-search'
-
-export const mastra = new Mastra({
-  tools: {
-    weatherInfo,
-    webSearch,
-    // add MCP tools or additional tools here
-  },
-  agents: {
-    builderAgent: createBuilderAgent(),
-    // add additional agents here
-  },
-  workflows: {
-    // add workflows here
-  },
-  editor: new MastraEditor({
-    builder: { enabled: true },
-  }),
-})
-```
-
-With no `configuration.agent.tools.allowed` set, both `weather-info` and `web-search` appear in the Builder's tool picker. End users can attach either tool to any agent they create.
-
-Entries match on `tool.id`, `Agent.id`, or `workflow.id`, the string the entity reports at runtime, not the export name.
-
-MCP tools work the same way: load them via `MCPClient.getTools()` and spread the result into the `tools` map.
-
-## Tool, agent, and workflow allowlists
-
-`configuration.agent.tools`, `configuration.agent.agents`, and `configuration.agent.workflows` constrain which registered entries appear in the Builder's pickers. Allowlist semantics are the same for all three:
-
-- **Omitted**: Unrestricted. The picker shows every registered entry.
-- **`allowed: []`**: Explicit lockdown. The picker is empty.
-- **`allowed: [...ids]`**: The picker shows only the listed IDs.
-
-Unknown IDs are dropped and surfaced as warnings through `getModelPolicyWarnings()` and the server logs.
-
-```typescript
-new MastraEditor({
-  builder: {
-    enabled: true,
-    configuration: {
-      agent: {
-        tools: { allowed: ['weather-info', 'web-search'] },
-        agents: { allowed: ['weather-agent'] },
-        workflows: { allowed: ['greet-workflow'] },
-      },
-    },
-  },
-})
-```
-
-## Related
-
-- [Model policy](https://mastra.ai/docs/agent-builder/model-policy): Pin the allowed models and default model.
-- [Memory](https://mastra.ai/docs/agent-builder/memory): Set the default memory shape for new agents.
-- [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options): Full property list.
-- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults): Every field on `configuration.agent`.

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

@@ -1,124 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Deploying
-
-> **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.
-
-Production deployments swap the local primitives in the Quickstart for cloud-backed equivalents. The shape of the `Mastra` and `MastraEditor` config doesn't change, only the providers behind it.
-
-## What a production deployment needs
-
-1. **EE license**: A valid `MASTRA_EE_LICENSE` so the server will start with the Builder enabled.
-2. **Hosted storage**: A shared store for agents, skills, runs, and memory.
-3. **Shared workspace filesystem**: Survives across instances. `local` is single-node only.
-4. **Cloud sandbox**: Runs agent commands safely. `local` is unsafe in shared environments.
-5. **Auth and RBAC**: Gates the Builder UI and `/agent-builder/*` routes.
-6. **Public base URL for channels**: Slack and other channel providers need a reachable URL.
-
-## EE license
-
-Set `MASTRA_EE_LICENSE` in the deployment environment. The server refuses to start when `builder.enabled` is truthy without a valid license. Treat the license key as a secret.
-
-## Storage
-
-Replace the file-backed LibSQL store with a hosted backend. LibSQL Cloud, PostgreSQL, and any other Mastra storage adapter all work.
-
-```typescript
-import { Mastra } from '@mastra/core/mastra'
-import { LibSQLStore } from '@mastra/libsql'
-
-new Mastra({
-  storage: new LibSQLStore({
-    id: 'mastra-storage',
-    url: process.env.DATABASE_URL!,
-    authToken: process.env.DATABASE_AUTH_TOKEN,
-  }),
-})
-```
-
-## Workspace filesystem and sandbox
-
-`local` filesystem works only on the node that owns the directory. For multi-instance deployments, register cloud filesystem and sandbox providers on `MastraEditor` and reference them by id in the inline workspace config.
-
-**npm**:
-
-```bash
-npm install @mastra/s3 @mastra/e2b
-```
-
-**pnpm**:
-
-```bash
-pnpm add @mastra/s3 @mastra/e2b
-```
-
-**Yarn**:
-
-```bash
-yarn add @mastra/s3 @mastra/e2b
-```
-
-**Bun**:
-
-```bash
-bun add @mastra/s3 @mastra/e2b
-```
-
-```typescript
-import { Mastra } from '@mastra/core/mastra'
-import { MastraEditor } from '@mastra/editor'
-import { s3FilesystemProvider } from '@mastra/s3'
-import { e2bSandboxProvider } from '@mastra/e2b'
-
-new Mastra({
-  editor: new MastraEditor({
-    filesystems: { [s3FilesystemProvider.id]: s3FilesystemProvider },
-    sandboxes: { [e2bSandboxProvider.id]: e2bSandboxProvider },
-    builder: {
-      enabled: true,
-      configuration: {
-        agent: {
-          workspace: {
-            type: 'inline',
-            config: {
-              name: 'builder-workspace',
-              filesystem: {
-                provider: s3FilesystemProvider.id,
-                config: {
-                  bucket: process.env.S3_BUCKET!,
-                  region: process.env.S3_REGION!,
-                },
-              },
-              sandbox: {
-                provider: e2bSandboxProvider.id,
-                config: { apiKey: process.env.E2B_API_KEY! },
-              },
-            },
-          },
-        },
-      },
-    },
-  }),
-})
-```
-
-`S3Filesystem` uses the default AWS credential chain (environment variables, `~/.aws` config, IAM roles, EC2 instance profile). For long-running deployments, use a credential provider function so credentials refresh automatically.
-
-`DockerSandbox`, `VercelSandbox`, and `VercelServerlessSandbox` are alternative cloud sandbox providers. Pick whichever matches your runtime.
-
-> **Warning:** A local sandbox can't run commands safely in a shared environment. Always register a cloud sandbox provider and reference it in the workspace config before deploying.
-
-## Auth and RBAC
-
-A production deployment without authentication exposes the Builder to the public internet. Register a `Mastra.server.auth` provider (for example, WorkOS or your own provider) and a `Mastra.server.rbac` provider to gate access.
-
-See [Access control](https://mastra.ai/docs/agent-builder/access-control) for the required role permissions and a WorkOS quickstart.
-
-## Public URL for channels
-
-Slack needs to reach your server through a public URL. Pass `baseUrl` to `SlackProvider` with the deployed URL (no trailing slash). See [Channels](https://mastra.ai/docs/agent-builder/channels) for the full setup.
-
-## Related
-
-- [Access control](https://mastra.ai/docs/agent-builder/access-control): Auth and RBAC setup.
-- [Channels](https://mastra.ai/docs/agent-builder/channels): Slack `baseUrl` and channel-specific setup.

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

@@ -1,115 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Tool providers
-
-> **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.
-
-Tool providers let Builder-created agents call tools from third-party apps such as Gmail, Slack, or GitHub. The Builder reuses the same tool providers as the editor, so any provider registered on `MastraEditor` is available in the Builder.
-
-This page covers Builder-specific connection setup, scope selection, and management. 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. In the Builder, [connect the toolkit](#connect-a-toolkit) and authorize the connection.
-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:
-
-- Register a tool provider on the `toolProviders` map of `MastraEditor` (see below).
-- Set up a Composio auth config for each toolkit you want to use (see below).
-- Configure a storage adapter on the `Mastra` instance. Connection state persists through `Mastra.storage`.
-
-## Register a tool provider
-
-The Builder reuses the editor's tool providers. Register each provider you want to expose on the `toolProviders` map of `MastraEditor`. Mastra includes providers for [Composio](https://composio.dev) and [Arcade](https://arcade.dev). Add a provider by giving it a key and an instance.
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { MastraEditor } from '@mastra/editor'
-import { ComposioToolProvider } from '@mastra/editor/composio'
-
-export const mastra = new Mastra({
-  agents: {/* your agents */},
-  editor: new MastraEditor({
-    toolProviders: {
-      composio: new ComposioToolProvider({
-        apiKey: process.env.COMPOSIO_API_KEY!,
-        allowedToolkits: ['gmail', 'googlecalendar'],
-      }),
-    },
-  }),
-})
-```
-
-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.
-
-1. Open the [Composio dashboard](https://dashboard.composio.dev) and select the toolkit you want to enable, for example **Gmail** or **GitHub**.
-2. Create an auth config for the toolkit and complete the app-specific setup. Composio's [auth config docs](https://docs.composio.dev/docs/authenticating-tools) cover the fields each app requires.
-3. Enable the auth config.
-
-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.
-
-## Connect a toolkit
-
-Once a provider is registered and its auth config is enabled, the toolkit can be connected from the Builder:
-
-1. Open the agent and add the toolkit's tools.
-2. Click **Connect** on the toolkit and complete the OAuth flow for the account you want to use.
-
-The connected account is bound to the agent, and its tools are ready to use on the next run.
-
-## 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 is routed to 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.
-
-## Related
-
-- [Tools](https://mastra.ai/docs/editor/tools): Register providers and browse toolkits in the editor.
-- [ToolProvider reference](https://mastra.ai/reference/editor/tool-provider): Provider API details.
-- [Agent Builder API reference](https://mastra.ai/reference/client-js/agent-builder): Manage connections programmatically with the `@mastra/client-js` SDK.
-- [Agent Builder overview](https://mastra.ai/docs/agent-builder/overview)