# 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](https://mastra.ai/reference/server/hono-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](https://mastra.ai/models). If you don't have a preference, use [OpenAI](https://mastra.ai/models/providers/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](https://hono.dev/docs/getting-started/basic):

**npm**:

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

**pnpm**:

```bash
pnpm create hono mastra-hono --template nodejs --install --pm npm
```

**Yarn**:

```bash
yarn create hono mastra-hono --template nodejs --install --pm npm
```

**Bun**:

```bash
bunx create-hono 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:

```bash
cd mastra-hono
```

Run [`mastra init`](https://mastra.ai/reference/cli/mastra). When prompted, choose a provider (e.g. OpenAI) and enter your key:

**npm**:

```bash
npx mastra@latest init
```

**pnpm**:

```bash
pnpm dlx mastra@latest init
```

**Yarn**:

```bash
yarn dlx mastra@latest init
```

**Bun**:

```bash
bun x 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**:

```bash
npm install @mastra/hono@latest
```

**pnpm**:

```bash
pnpm add @mastra/hono@latest
```

**Yarn**:

```bash
yarn add @mastra/hono@latest
```

**Bun**:

```bash
bun add @mastra/hono@latest
```

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

```typescript
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**:

```bash
npm run dev
```

**pnpm**:

```bash
pnpm run dev
```

**Yarn**:

```bash
yarn dev
```

**Bun**:

```bash
bun run dev
```

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

From here, you can extend the project with your own tools and logic:

- Learn more about [agents](https://mastra.ai/docs/agents/overview)
- Give your agent its own [tools](https://mastra.ai/docs/agents/using-tools)
- Add human-like [memory](https://mastra.ai/docs/agents/agent-memory) to your agent

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

- [Server Adapters](https://mastra.ai/docs/server/server-adapters)