Tool providers

note

The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. Contact sales 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 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.

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 ships providers for Composio and Arcade; add a provider by giving it a key and an instance.

src/mastra/index.ts

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 is 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.

Set up a Composio auth config

Each toolkit a user can connect needs its own auth config in the Composio dashboard. 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 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 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. 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

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

• Tools: Register providers and browse toolkits in the editor.
• ToolProvider reference: Provider API details.
• Agent Builder API reference: Manage connections programmatically with the @mastra/client-js SDK.
• Agent Builder overview