---
title: "Express | Frameworks"
description: "Get started with Mastra and Express"
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

# 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](/reference/v1/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](/models/v1). If you don't have a preference, use [OpenAI](/models/v1/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:

<Tabs>
<TabItem value="https" label="HTTPS">

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

</TabItem>
<TabItem value="ssh" label="SSH">

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

</TabItem>
</Tabs>

## Initialize Mastra

Inside your Express project directory, run [`mastra init`](/reference/v1/cli/mastra#mastra-init).

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

```bash
npx mastra@beta 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:

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

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

```typescript {2-3,11-12} title="src/index.ts"
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](/docs/v1/agents/overview)
- Give your agent its own [tools](/docs/v1/agents/using-tools)
- Add human-like [memory](/docs/v1/agents/agent-memory) to your agent

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

- [Server Adapters](/docs/v1/server/server-adapters)
