> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Mastra

> Build an agent with Mastra and enable it to use 1000+ tools with Composio.

The Mastra provider transforms Composio tools into [Mastra's tool format](https://mastra.ai/en/docs/tools-mcp/overview#creating-tools) with built-in execution. Pass the wrapped tools to a Mastra `Agent`, and the agent calls them automatically. Each tool gets both an input and an output schema, so Mastra can validate tool results as well as arguments.

**1. Install**

**Install**

```bash npm theme={null}
npm install @composio/core @composio/mastra @mastra/core @ai-sdk/openai
```

```bash pnpm theme={null}
pnpm add @composio/core @composio/mastra @mastra/core @ai-sdk/openai
```

```bash yarn theme={null}
yarn add @composio/core @composio/mastra @mastra/core @ai-sdk/openai
```

```bash bun theme={null}
bun add @composio/core @composio/mastra @mastra/core @ai-sdk/openai
```

**2. Configure API Keys**

**Configure API Keys**

> [!NOTE]
>
> Set `COMPOSIO_API_KEY` with your API key from [Settings](https://dashboard.composio.dev/~/project/settings/api-keys?utm_source=docs\&utm_medium=content\&utm_campaign=docs-providers-mastra) and `OPENAI_API_KEY` with your [OpenAI API key](https://platform.openai.com/api-keys).

```txt .env theme={null}
COMPOSIO_API_KEY=xxxxxxxxx
OPENAI_API_KEY=xxxxxxxxx
```

**3. Create session and run**

**Create session and run**

```typescript theme={null}
import { Composio } from "@composio/core";
import { MastraProvider } from "@composio/mastra";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";

const composio = new Composio({
  provider: new MastraProvider(),
});

// Create a session for your user
const session = await composio.create("user_123");
const tools = await session.tools();

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  instructions: "You are a helpful assistant.",
  model: openai("gpt-5.2"),
  tools,
});

const { text } = await agent.generate([
  { role: "user", content: "Send an email to john@example.com with the subject 'Hello' and body 'Hello from Composio!'" },
]);

console.log(text);
```

## Provider specifics

**Strict mode.** Pass `strict: true` to normalize each tool's input schema for OpenAI structured outputs before Mastra compiles it: every object lists all of its properties in `required` and is closed, and optional properties stay available but accept `null`. A `null` is dropped before the tool runs unless the tool's own schema accepts `null` for that parameter, so nullable fields still receive an explicit `null`. Tools whose schema cannot be expressed in strict mode, such as objects that accept arbitrary keys, `allOf`, `prefixItems`, or unresolved `$ref`s, keep their original schema and log a warning:

```typescript theme={null}
import { Composio } from "@composio/core";
import { MastraProvider } from "@composio/mastra";

const composio = new Composio({ provider: new MastraProvider({ strict: true }) });
```

> [!NOTE]
>
> The provider runs each tool's JSON Schema through Mastra's schema-compat layer and inlines internal `$ref` pointers first. A few Composio tools reference `$defs` entries that the upstream API does not emit. Rather than crash `tools.get`, the provider falls back to a permissive object schema for that property and logs one warning per tool, so the affected field validates loosely.

## Next

For Worker bindings, local secrets, and deployment steps, see the [Cloudflare Workers walkthrough](https://composio-preview.mintlify.site/examples/cloudflare-workers.md). It also links to the Mastra Worker example in the SDK repository.

> [card] [What is a session?](https://composio-preview.mintlify.site/docs/how-composio-works.md)
>
> How sessions scope users, tools, and auth, and how to reuse them across requests.
