Skip to main content
Mastra 1.0 is available 🎉 Read announcement

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
Direct link to 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)
Direct link to 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
Direct link to 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
Direct link to 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:

src/index.ts
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
Direct link to 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
Direct link to 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:

On this page