MCP Host RPC Bridge
A Node.js library that bridges MCP (Model Context Protocol) tool calls to JSON-RPC function calls. Supports both Unix socket connections (default) and HTTP transport for flexible integration with any application architecture.
Features
- 🚀 Dual Transport Modes: Unix sockets for local IPC, HTTP for web integration
- 🔐 JWT Authentication: Secure context passing with cryptographic signatures
- 🔧 Framework Agnostic: Works with Express, Fastify, Next.js, or raw Node.js
- 📝 TypeScript Support: Full type definitions included
- 🎯 Zod Integration: Automatic schema conversion for type-safe tools
Installation
npm install @botanicastudios/mcp-host-rpc
Quick Start
Socket Mode (Default)
import { McpHost } from '@botanicastudios/mcp-host-rpc/host';
// Create host with Unix socket transport (default)
const host = new McpHost({ debug: true });
// Register a tool
host.registerTool('get_data', {
title: 'Get Data',
description: 'Retrieves data from the system',
functionName: 'getData',
inputSchema: {
type: 'object',
properties: {
id: { type: 'string' }
},
required: ['id']
}
}, async (context, args) => {
return { type: 'text', text: `Data for ${args.id}` };
});
// Start the server
await host.start();
// Get MCP server configuration
const config = host.getMCPServerConfig(
'my-server',
['get_data'],
{ userId: '123', permissions: ['read'] }
);
HTTP Mode
import express from 'express';
import { McpHost } from '@botanicastudios/mcp-host-rpc/host';
const app = express();
// Create host with HTTP transport
const host = new McpHost({
transport: 'http',
httpPath: '/mcp-rpc',
httpUrl: 'http://localhost:3000/mcp-rpc'
});
// Set up HTTP endpoint
app.use(express.json());
app.post('/mcp-rpc', async (req, res) => {
await host.handleHttpRequest(req, res);
});
// Register tools and start
host.registerTool(/* ... */);
await host.start();
app.listen(3000);
Documentation
- Socket Mode Guide - Detailed documentation for Unix socket transport
- HTTP Mode Guide - Complete guide for HTTP transport integration
Core Concepts
Transport Modes
- Socket Mode (default) - Uses Unix domain sockets for high-performance local IPC
- HTTP Mode - Uses HTTP POST requests for web integration and remote access
Context-Based Security
Every tool handler receives a verified context object extracted from JWT tokens:
host.registerTool('read_file', {
/* tool config */
}, async (context, args) => {
// context contains verified JWT payload
if (!context.permissions.includes('read')) {
throw new Error('Permission denied');
}
// Implement tool logic
});
Tool Registration
Tools can be registered with JSON Schema or Zod schemas:
import { z } from 'zod';
// Using Zod schema (auto-converted to JSON Schema)
const schema = z.object({
name: z.string().min(1),
age: z.number().positive()
});
host.registerTool('create_user', {
title: 'Create User',
description: 'Creates a new user',
functionName: 'createUser',
inputSchema: schema // Zod schema auto-converted
}, async (context, args) => {
// args is validated against schema
});
API Reference
new McpHost(options)
Creates a new MCP host instance.
interface McpHostOptions {
// Transport mode ('socket' or 'http')
transport?: 'socket' | 'http';
// Socket mode options
pipePath?: string;
// HTTP mode options
httpPath?: string;
httpUrl?: string;
// Common options
secret?: string;
debug?: boolean;
start?: boolean;
}
host.registerTool(name, config, handler)
Register a tool with the host.
host.getMCPServerConfig(name, tools, context, options?)
Get MCP server configuration for claude_desktop_config.json.
host.handleHttpRequest(req, res)
Handle HTTP requests (HTTP mode only).
host.start() / host.stop()
Start or stop the host server.
Examples
Check out the examples/ directory for complete examples:
simple-example.js- Basic socket mode usagezod-example.js- Zod schema validationhttp-express-example.js- Express.js HTTP integrationhttp-fastify-example.js- Fastify HTTP integrationhttp-raw-example.js- Raw Node.js HTTP server
Running Examples
# Socket mode example
npm run example
# HTTP mode examples
node examples/http-express-example.js
node examples/http-fastify-example.js
License
MIT
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.