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, 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:

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:

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