---
title: "Using Arcade tools with Mastra"
description: "Integrate Arcade tools into your Mastra applications for basic use cases."
---

import { Steps, Tabs, Callout } from "nextra/components";

This guide shows you how to integrate and use Arcade tools within a Mastra agent. For the complete working example, check out our [GitHub repository](https://github.com/ArcadeAI/arcade-ai/tree/main/examples/mastra).

<Steps>

### Prerequisites

- [Obtain an Arcade API key](/get-started/setup/api-keys)
- Basic familiarity with TypeScript and Mastra concepts

### Create a Mastra project

Start by creating a new Mastra project using the official CLI:

```bash
# Create a new Mastra project
npx create-mastra@latest my-arcade-agent

# Navigate to the project
cd my-arcade-agent
```

For more details on setting up a Mastra project, refer to the [Mastra documentation](https://mastra.ai/docs/getting-started/installation).

### Install Arcade client

Install the Arcade client:

<Tabs items={["pnpm", "npm", "yarn"]}>

<Tabs.Tab>

```bash
pnpm add @arcadeai/arcadejs
```

</Tabs.Tab>

<Tabs.Tab>

```bash
npm install @arcadeai/arcadejs
```

</Tabs.Tab>

<Tabs.Tab>

```bash
yarn install @arcadeai/arcadejs
```

</Tabs.Tab>

</Tabs>

### Configure API keys

Set up your environment with the required API keys:

```typescript
// Set your API keys in your environment variables or .env file
process.env.ARCADE_API_KEY = "your_arcade_api_key";
process.env.ANTHROPIC_API_KEY = "your_anthropic_api_key"; // or another supported model provider
```

### Convert Arcade tools to Mastra tools

Arcade offers methods to convert tools into Zod schemas, which is essential since Mastra defines tools using Zod. The `toZodToolSet` method is particularly useful, as it simplifies this integration and makes it easier to use Arcade's tools with Mastra. Learn more about Arcade's Zod integration options [here](/guides/tool-calling/custom-apps/get-tool-definitions#get-zod-tool-definitions).

```ts
import { Arcade } from "@arcadeai/arcadejs";
import {
	executeOrAuthorizeZodTool,
	toZodToolSet,
} from "@arcadeai/arcadejs/lib";

// Initialize Arcade
const arcade = new Arcade();

// Get Gmail MCP Server
// MCP Server names can be found in the Arcade dashboard via Tools > view > MCP Server or via the CLI `arcade workers list`
const gmailToolkit = await arcade.tools.list({ toolkit: "Gmail", limit: 30 });

// Get Gmail tools
export const gmailTools = toZodToolSet({
	tools: gmailToolkit.items,
	client: arcade,
	userId: "<YOUR_USER_ID>", // Your app's internal ID for the user (an email, UUID, etc). It's used internally to identify your user in Arcade
	executeFactory: executeOrAuthorizeZodTool, // Checks if tool is authorized and executes it, or returns authorization URL if needed
});

```

### Create and configure your Mastra agent

Now create a Mastra agent that uses Arcade tools:

```typescript
import { Agent } from "@mastra/core/agent";
import { anthropic } from "@ai-sdk/anthropic";

// Create the Mastra agent with Arcade tools
export const gmailAgent = new Agent({
  name: "gmailAgent",
    instructions: `You are a Gmail assistant that helps users manage their inbox.

When helping users:
- Always verify their intent before performing actions
- Keep responses clear and concise
- Confirm important actions before executing them
- Respect user privacy and data security

Use the gmailTools to interact with various Gmail services and perform related tasks.`,
  model: anthropic("claude-3-7-sonnet-20250219"),
  tools: gmailTools,
});
```

### Interact with your agent

You can interact with your agent in two main ways:

**1. Using the Mastra Development Playground:**

Start the Mastra development server:

```bash
npm run dev
```

This will launch a local development playground, typically accessible at `http://localhost:4111`. Open this URL in your browser, select the `gmailAgent` from the list of available agents, and start chatting with it directly in the UI.

**2. Programmatically:**

Alternatively, you can interact with the agent directly in your code:

```typescript
// Generate a response from the agent
const response = await gmailAgent.generate(
  "Read my last email and summarize it in a few sentences",
);
console.log(response.text);

// Or stream the response for a more interactive experience
const stream = await gmailAgent.stream("Send an email to dev@arcade.dev with the subject 'Hello from Mastra'");

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}
```

</Steps>

<Callout type="warning" title="Initial Tool Authorization">When running your agent for the first time with tools that require user consent (like Google or Github), the agent will return an authorization reponse (e.g., `{ authorization_required: true, url: '...', message: '...' }`). Your agent's instructions should guide it to present this URL to the user. After the user visits this URL and grants permissions, the tool can be used successfully. See the [Managing user authorization](/guides/agent-frameworks/mastra/user-auth-interrupts) guide for more details on handling authentication flows.</Callout>