How do I use mcp-honojs?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-honojs show me how to register a tool with an input schema" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-honojs

Hono.js middleware for building Model Context Protocol (MCP) servers. Create MCP-compatible APIs with a simple, fluent interface — no decorators required.

Features

Simple fluent API — server.tool(), server.resource(), server.prompt()
Multiple transports — SSE and HTTP (JSON-RPC 2.0)
Session management — Built-in session handling with automatic cleanup
Type-safe — Full TypeScript support with comprehensive types
Zero dependencies — Only peer dependency is Hono
Lightweight — Minimal footprint, perfect for edge deployments

Installation

npm install mcp-honojs hono

Quick Start

import { Hono } from 'hono';
import { McpServer } from 'mcp-honojs';

// Create MCP server
const mcp = new McpServer({
  name: 'my-mcp-server',
  version: '1.0.0',
});

// Register a tool
mcp.tool(
  {
    name: 'greet',
    description: 'Greet someone by name',
    inputSchema: {
      type: 'object',
      properties: {
        name: { type: 'string', description: 'Name to greet' },
      },
      required: ['name'],
    },
  },
  async (args) => {
    return {
      content: [{ type: 'text', text: `Hello, ${args.name}!` }],
    };
  }
);

// Create Hono app and attach MCP
const app = new Hono();
mcp.attach(app);

export default app;

Visit your endpoints:

SSE: GET /sse
HTTP: POST /mcp

API Reference

McpServer

Constructor

const mcp = new McpServer(options: McpServerOptions);

Options:

interface McpServerOptions {
  name: string;              // Server name
  version: string;           // Server version
  session?: {
    timeout?: number;        // Session timeout in ms (default: 30min)
    cleanupInterval?: number; // Cleanup interval in ms (default: 5min)
    maxSessions?: number;     // Max concurrent sessions (default: 1000)
  };
}

Methods

tool(options, handler) — Register a tool

mcp.tool(
  {
    name: 'add',
    description: 'Add two numbers',
    inputSchema: {
      type: 'object',
      properties: {
        a: { type: 'number' },
        b: { type: 'number' },
      },
      required: ['a', 'b'],
    },
  },
  async (args, context) => {
    return {
      content: [
        { type: 'text', text: `Result: ${args.a + args.b}` }
      ],
    };
  }
);

resource(options, handler) — Register a resource

mcp.resource(
  {
    uri: 'example://data',
    name: 'example-data',
    description: 'Example data resource',
    mimeType: 'application/json',
  },
  async (uri, context) => {
    return {
      contents: [
        {
          uri,
          mimeType: 'application/json',
          text: JSON.stringify({ data: 'example' }),
        },
      ],
    };
  }
);

prompt(options, handler) — Register a prompt

mcp.prompt(
  {
    name: 'welcome',
    description: 'Welcome prompt',
    arguments: [
      { name: 'username', description: 'User name', required: true }
    ],
  },
  async (args, context) => {
    return {
      messages: [
        {
          role: 'user',
          content: {
            type: 'text',
            text: `Welcome, ${args.username}!`,
          },
        },
      ],
    };
  }
);

attach(app, transportOptions?) — Attach transports to Hono app

mcp.attach(app, {
  ssePath: '/sse',    // SSE endpoint (default: /sse)
  httpPath: '/mcp',   // HTTP endpoint (default: /mcp)
});

sseMiddleware(path?) — Get SSE middleware

app.use(mcp.sseMiddleware('/custom-sse'));

httpMiddleware(path?) — Get HTTP middleware

app.use(mcp.httpMiddleware('/custom-mcp'));

Context

Both tool and resource handlers receive a McpContext object:

interface McpContext {
  sessionId?: string;        // Current session ID
  honoContext?: Context;     // Hono request context
  metadata?: Record<string, any>; // Custom metadata
}

Access the Hono context for request details:

mcp.tool({ /* ... */ }, async (args, context) => {
  const userAgent = context.honoContext?.req.header('user-agent');
  // ...
});

Type Definitions

Tool Types

interface ToolResult {
  content: ToolResultContent[];
  isError?: boolean;
}

interface ToolResultContent {
  type: 'text' | 'image' | 'resource';
  text?: string;
  data?: string;          // Base64 for images
  mimeType?: string;
  uri?: string;           // For resource references
}

Resource Types

interface ResourceResult {
  contents: ResourceContent[];
}

interface ResourceContent {
  uri: string;
  mimeType?: string;
  text?: string;
  blob?: string;          // Base64 encoded binary
}

Prompt Types

interface PromptResult {
  description?: string;
  messages: PromptMessage[];
}

interface PromptMessage {
  role: 'user' | 'assistant';
  content: PromptMessageContent;
}

JSON-RPC Protocol

The server implements MCP's JSON-RPC 2.0 protocol.

Supported Methods

initialize — Initialize connection
tools/list — List available tools
tools/call — Execute a tool
resources/list — List resources
resources/templates/list — List resource templates
resources/read — Read a resource
prompts/list — List prompts
prompts/get — Get a prompt
ping — Health check

Example Requests

Initialize:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize"
}

Call a tool:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "greet",
    "arguments": { "name": "Alice" }
  }
}

Session Management

Sessions are automatically managed:

Created on first request
Returned in x-session-id header (HTTP) or endpoint event (SSE)
Auto-expire after timeout (default: 30 minutes)
Cleaned up periodically (default: every 5 minutes)

HTTP: Pass session ID in x-session-id header SSE: Session is bound to the connection

Examples

See the examples/ directory for complete examples:

basic.ts — Simple calculator and greeting tools
More examples coming soon!

Run examples:

cd examples
npm install
npm run dev

Comparison with mcp-nestjs

Feature	mcp-honojs	mcp-nestjs
Framework	Hono.js	NestJS
API Style	Fluent/functional	Decorator-based
DI Container	❌ (not needed)	✅ (NestJS)
Auto-discovery	❌	✅
Edge-ready	✅	Depends
Bundle size	Tiny	Larger
Use case	APIs, edge, serverless	Enterprise apps

Deployment

Node.js

import { serve } from '@hono/node-server';
import app from './app';

serve({ fetch: app.fetch, port: 3000 });

Cloudflare Workers

export default app;

Deno

import { serve } from 'https://deno.land/std/http/server.ts';
serve(app.fetch);

Bun

export default {
  fetch: app.fetch,
  port: 3000,
};

mcp-honojs

mcp-honojs

Features

Installation

Quick Start

API Reference

McpServer

Constructor

Methods

Context

Type Definitions

Tool Types

Resource Types

Prompt Types

JSON-RPC Protocol

Supported Methods

Example Requests

Session Management

Examples

Comparison with mcp-nestjs

Deployment

Node.js

Cloudflare Workers

Deno

Bun

Contributing

License

Resources

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API