Quickstart

Create a standalone Node.js broker, connect a user’s Gmail account through the remote MCP server at https://gmail.run.tools, and read their inbox from trusted server code.

Prerequisites

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

You do not need to create a Google OAuth application. The MCP provider uses the server’s authorization metadata and dynamic client registration.

Create your broker and read Gmail

Scaffold a Node.js project

Install the latest Hookfish CLI, run the initializer, and enter the generated directory.

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

The initializer installs dependencies and creates a gitignored .env with unique OAUTH_ENCRYPTION_KEY and HOOKFISH_API_KEY values.

Install the clients

Add the first-party Hookfish SDK and the MCP TypeScript client to the generated Node.js project.

pnpm add @hookfish/sdk @modelcontextprotocol/client

Add an inbox endpoint

Replace src/index.ts with this Hono API. The /gmail/inbox endpoint keeps the broker access token and Gmail access token on the server.

import { serve } from '@hono/node-server'
import { HookfishServer } from '@hookfish/api'
import { Hookfish, HookfishError } from '@hookfish/sdk'
import {
  Client as McpClient,
  StreamableHTTPClientTransport,
  UnauthorizedError,
} from '@modelcontextprotocol/client'
import { Hono } from 'hono'
import config from '../hookfish.config'

const app = new Hono()
const broker = await HookfishServer.init(config)
if (!process.env.HOOKFISH_API_KEY) throw new Error('HOOKFISH_API_KEY is required')

const hookfish = new Hookfish({
  apiKey: process.env.HOOKFISH_API_KEY,
  baseUrl: 'http://local/api',
  fetch: async (input: RequestInfo | URL, init?: RequestInit) =>
    broker.fetch(new Request(input, init), process.env),
})

// Mount Hookfish's API and OAuth callback routes.
app.all('/api/*', (ctx) =>
  broker.fetch(ctx.req.raw, process.env),
)

// Authorize Gmail when needed, then return the user's inbox.
app.get('/gmail/inbox', async (ctx) => {
  const mcpUrl = new URL('https://gmail.run.tools')

  // Ensure the remote Gmail MCP server is configured as a provider.
  try {
    await hookfish.providers.get('gmail')
  } catch (error) {
    if (!(error instanceof HookfishError) || error.status !== 404) throw error
    await hookfish.providers.put('gmail', {
      template: 'mcp',
      configuration: { resource_url: mcpUrl.href, scopes: [] },
      credentials: { mode: 'register' },
    })
  }

  let accessToken: string

  // Get a current token or return a URL that starts authorization.
  try {
    accessToken = (
      await hookfish.oauth.getToken('personal/gmail')
    ).access_token
  } catch (error) {
    if (!(error instanceof HookfishError) || error.status !== 404) throw error
    const { authorize_url } = await hookfish.oauth.authorize('gmail', {
      connectionId: 'personal/gmail',
    })
    return ctx.json({ error: 'authorization_required', authorize_url }, 401)
  }

  const mcp = new McpClient(
    { name: 'gmail-inbox-quickstart', version: '1.0.0' },
    { versionNegotiation: { mode: 'auto' } },
  )

  // Call Gmail through MCP, restarting authorization if the token is rejected.
  try {
    await mcp.connect(new StreamableHTTPClientTransport(mcpUrl, {
      authProvider: { token: async () => accessToken },
    }))
    const inbox = await mcp.callTool({
      name: 'Gmail_SearchEmailsByQuery',
      arguments: {
        query: 'in:inbox',
        max_results: 10,
        result_detail: 'lightweight',
      },
    })
    return ctx.json(inbox)
  } catch (error) {
    if (!(error instanceof UnauthorizedError)) throw error
    const { authorize_url } = await hookfish.oauth.authorize('gmail', {
      connectionId: 'personal/gmail',
    })
    return ctx.json({ error: 'authorization_required', authorize_url }, 401)
  } finally {
    await mcp.close().catch(() => undefined)
  }
})

serve({ fetch: app.fetch, port: Number(process.env.PORT ?? 8787) })

The /api/* route mounts Hookfish, including its API documentation at /api/docs.

Start the API

Start the generated backend and dashboard.

pnpm dev

Request the inbox

Call the application endpoint from another terminal.

curl --include http://127.0.0.1:8787/gmail/inbox

The first request returns 401 Unauthorized with an authorize_url. Open that URL, sign in with Google, and approve access. After Hookfish handles the callback, run the same command again. The endpoint now returns the MCP tool result for the user’s inbox.

You now have one Hono endpoint that returns an authorization URL until Gmail is connected, then returns the user’s inbox through MCP. Hookfish stores and refreshes the provider token behind that endpoint.

This quickstart leaves /gmail/inbox unauthenticated for local testing. Authenticate the application user and use a scoped broker token before you deploy it.

Understand the generated project

The default development command runs two processes:

Browser
  │
  ▼
Hookfish dashboard :5173
  │ proxies /api
  ▼
Hookfish backend :8787
  │
  ▼
PGlite data/hookfish

The generated hookfish.config.ts contains provider factories, database configuration, callback settings, and documentation visibility. The backend mounts HookfishServer.init(config).fetch below /api.

Next steps

Read How Hookfish works to understand the callback and token-refresh lifecycle.
Choose a deployment backend.
Replace the root key with a scoped broker token.
Add application authentication, then call Hookfish from your authorized server routes.

Get started

Store secrets

Integrate

Deploy

Secure and scale

Operate

Prerequisites

Create your broker and read Gmail

Understand the generated project

Next steps

​Prerequisites

​Create your broker and read Gmail

​Understand the generated project

​Next steps

Prerequisites

Create your broker and read Gmail

Understand the generated project

Next steps