Integrate Mastra in your Hono project

In this guide, you'll build a tool-calling AI agent using Mastra and Hono. Using the Hono 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 Hono app (optional)

If you already have a Hono app, skip to the next step.

Run the following command to create a new Hono app:

npm create hono@latest mastra-hono -- --template nodejs --install --pm npm

This creates a project called mastra-hono, but you can replace it with any name you want.

Initialize Mastra

Navigate to your Hono project directory:

cd mastra-hono

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 Hono server adapter later.

Add server adapter

Install the Hono server adapter package:

npm install @mastra/hono@latest

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

import { serve } from '@hono/node-server'
import { Hono } from 'hono'
import { type HonoBindings, type HonoVariables, MastraServer } from '@mastra/hono'
import { mastra } from './mastra/index.js'

const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>()
const server = new MastraServer({ app, mastra })

await server.init()

app.get('/', c => {
  return c.text('Hello Hono!')
})

serve(
  {
    fetch: app.fetch,
    port: 3000,
  },
  info => {
    console.log(`Server is running on http://localhost:${info.port}`)
  },
)

The ⁠MastraServer is initialized with the existing Hono 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 Hono server:

npm run dev

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 Hono! 🎉

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

• Server Adapters