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, 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. If you don't have a preference, use 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 and install dependencies:

HTTPS

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

SSH

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

Initialize Mastra

Inside your Express project directory, run mastra init.

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

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 install @mastra/express@latest

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

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:

npm run start

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

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
• Give your agent its own tools
• Add human-like memory to your agent

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

• Server Adapters