Quickstart

This guide creates one Hono application. The app mounts HookfishServer, calls it with Hookfish, and reads Gmail through https://gmail.run.tools.

Prerequisites

Node.js 20 or later
pnpm
A Google account with Gmail enabled

You do not need to create a Google OAuth application. Hookfish uses the MCP server’s OAuth discovery metadata and supported client-registration mechanism.

Scaffold and start Hookfish

npm i -g hookfish@latest
hookfish init my-broker --backend node
cd my-broker
pnpm dev

The generated src/index.ts is a Hono application with HookfishServer mounted at /api. The scaffold also registers the trusted mcp and secret providers and creates gitignored OAUTH_ENCRYPTION_KEY and HOOKFISH_API_KEY values. Leave this terminal running.

Add the Gmail route

Open another terminal, enter the generated project, and install the SDK:

cd my-broker
pnpm add @hookfish/sdk

Update the generated Hono app to match the version below. The new /inbox route is highlighted in green.

src/index.ts

import { serve } from '@hono/node-server'
import { HookfishServer } from '@hookfish/api'
import { Hookfish } from '@hookfish/sdk'
import { Hono } from 'hono'
import config from '../hookfish.config'

const apiKey = process.env.HOOKFISH_API_KEY
if (!apiKey) throw new Error('HOOKFISH_API_KEY is required')

const PORT = Number(process.env.PORT ?? 8787)
const HOSTNAME = process.env.HOST ?? '127.0.0.1'
const BACKEND_ORIGIN = `http://${HOSTNAME}:${PORT}`
const hookfishServer = await HookfishServer.init(config)
const app = new Hono()

app.route('/', hookfishServer)

const hookfish = new Hookfish({
  apiKey,
  baseUrl: `${BACKEND_ORIGIN}/api`,
})

app.get('/inbox', async () => { 
  await using mcp = await hookfish.mcp({
    connection: 'user/personal/gmail/mcp',
    url: 'https://gmail.run.tools',
  })

  const inbox = await mcp.callTool({
    name: 'Gmail_SearchEmailsByQuery',
    arguments: {
      query: 'in:inbox',
      max_results: 10,
      result_detail: 'lightweight',
    },
  })

  return new Response(JSON.stringify(inbox), {
    headers: { 'Content-Type': 'application/json' },
  })
})

serve({
  fetch: (request) => app.fetch(request, process.env),
  hostname: HOSTNAME,
  port: PORT,
})

console.log(`Hookfish backend running at ${BACKEND_ORIGIN}/api`)

Hookfish calls the mounted /api routes through the application’s URL. hookfish.mcp() creates and connects an MCP client with Hookfish-managed authentication. await using closes the client when the route handler exits. The scaffold’s watch process reloads the application after you save the file.

Authorize Gmail and read the inbox

Request the inbox:

curl http://127.0.0.1:8787/inbox

The first request returns 401 authorization_required with a fresh authorize_url. Open that URL and approve access, then run the curl command again to receive the inbox result.HookfishError preserves the failed Hookfish response through Hono. You do not need an onError handler to retain the status, error code, or authorization URL. If the MCP server later rejects the credential, Hookfish starts a fresh authorization flow and the new response bubbles through Hono in the same way.

The path user/personal/gmail/mcp has four parts:

Namespace: user/personal
Resource identity: gmail
Provider implementation: mcp
Authentication: OAuth

The final segment selects trusted provider code. The gmail identity distinguishes this generic MCP connection from other resources under the same namespace. Hookfish stores the URL on first access and rejects a later access that supplies a different URL for the same path. A concrete Gmail provider at user/personal/gmail is a different connection because its final segment is gmail.

Keep the /inbox route behind your application’s authentication before using this pattern with real users. Hookfish returns the usable MCP credential only to this trusted server code.

Next, read How Hookfish works and Application authentication.

Get started

Store secrets

Integrate

Deploy

Secure and scale

Operate

Prerequisites

​Prerequisites

Prerequisites