# Integrate Mastra in your Express project

In this guide, you'll build a tool-calling AI agent using Mastra and Express. Using the [Express server adapter](https://mastra.ai/reference/server/express-adapter), you can expose your agents as HTTP endpoints without writing the routing yourself or running a separate Mastra server.

## Before you begin

- You'll need an API key from a supported [model provider](https://mastra.ai/models). If you don't have a preference, use [OpenAI](https://mastra.ai/models/providers/openai).
- Install Node.js `v22.13.0` or later

## Create a new Express app (optional)

If you already have an Express app, skip to the next step.

Clone this [boilerplate repository](https://github.com/mastra-ai/express-ts-boilerplate) and install dependencies:

**HTTPS**:

**npm**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
npm install
```

**pnpm**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
pnpm install
```

**Yarn**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
yarn install
```

**Bun**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
bun install
```

**SSH**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
npm install
```

**Tab 3**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
pnpm install
```

**Tab 4**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
yarn install
```

**Tab 5**:

```bash
git clone https://github.com/mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
bun install
```

**Tab 6**:

**npm**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
npm install
```

**pnpm**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
pnpm install
```

**Yarn**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
yarn install
```

**Bun**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
bun install
```

**Tab 7**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
npm install
```

**Tab 8**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
pnpm install
```

**Tab 9**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
yarn install
```

**Tab 10**:

```bash
git clone git@github.com:mastra-ai/express-ts-boilerplate.git
cd express-ts-boilerplate
bun install
```

## Initialize Mastra

Inside your Express project directory, run [`mastra init`](https://mastra.ai/reference/cli/mastra).

When prompted, choose a provider (e.g. OpenAI) and enter your key:

```bash
npx mastra@latest init
```

This creates a `src/mastra` folder with an example weather agent and the following files:

- `index.ts` - Mastra config, including memory
- `tools/weather-tool.ts` - a tool to fetch weather for a given location
- `agents/weather-agent.ts`- a weather agent with a prompt that uses the tool

You'll pass the `src/mastra/index.ts` file to the Express server adapter later.

## Add server adapter

Install the Express server adapter package:

**npm**:

```bash
npm install @mastra/express@latest
```

**pnpm**:

```bash
pnpm add @mastra/express@latest
```

**Yarn**:

```bash
yarn add @mastra/express@latest
```

**Bun**:

```bash
bun add @mastra/express@latest
```

Open the Express entry file at `src/index.ts` and add the required import and initialization code:

```typescript
import express, { type Request, type Response } from "express";
import { MastraServer } from "@mastra/express";
import { mastra } from "./mastra";

const app = express();
const PORT = process.env.PORT || 3000;

// Middleware
app.use(express.json());

const server = new MastraServer({ app, mastra });
await server.init();

// Routes
app.get("/", (_req: Request, res: Response) => {
  res.json({ message: "Hello, World!" });
});

// Start server
app.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`);
});
```

The ⁠`MastraServer` is initialized with the existing Express `app` and the root ⁠`mastra` instance. Calling `⁠init()` registers the Mastra middleware and exposes all available Mastra endpoints.

## Test your agent

By default, Mastra's endpoints are added under the `/api` subpath and use your agent/workflow IDs. The default `weather-agent` created by `mastra init` is available at `/api/agents/weather-agent`.

Start your Express server:

```bash
npm run start
```

In a separate terminal window, use `curl` to ask the weather agent:

```bash
curl -X POST http://localhost:3000/api/agents/weather-agent/generate -H "Content-Type: application/json" -d "{\"messages\":[{\"role\":\"user\",\"content\":\"What is the weather like in Seoul?\"}]}"
```

## Next steps

Congratulations on building your Mastra agent with Express! 🎉

From here, you can extend the project with your own tools and logic:

- Learn more about [agents](https://mastra.ai/docs/agents/overview)
- Give your agent its own [tools](https://mastra.ai/docs/agents/using-tools)
- Add human-like [memory](https://mastra.ai/docs/agents/agent-memory) to your agent

When you're ready, read more about how Mastra integrates with Express:

- [Server Adapters](https://mastra.ai/docs/server/server-adapters)