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)`

`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 usage
zod-example.js - Zod schema validation
http-express-example.js - Express.js HTTP integration
http-fastify-example.js - Fastify HTTP integration
http-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.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A server that bridges MCP tool calls to JSON-RPC function calls over socket connections, allowing external applications to expose functions as MCP tools.

Related MCP Servers

openrpc-mpc-server
shanejonas
A
security
A
license
A
quality
A Model Context Protocol (MCP) server that provides JSON-RPC functionality through OpenRPC.
Last updated -
2
10
36
JavaScript
Apache 2.0
Toolhouse MCP Server
toolhouse-community
-
security
A
license
-
quality
This MCP server allows you to connect MCP clients with Toolhouse's tools.
Last updated -
13
Python
MIT License
MCP JSON-RPC Server
melvincarvalho
-
security
A
license
-
quality
A beginner-friendly MCP-inspired JSON-RPC server built with Node.js, offering basic client-server interaction through an 'initialize' capabilities handshake and an 'echo' function.
Last updated -
4
JavaScript
MIT License
mcp-tool-chainer
thirdstrandstudio
-
security
A
license
-
quality
An MCP (Model Context Protocol) server that chains calls to other MCP tools, reducing token usage by allowing sequential tool execution with result passing
Last updated -
109
47
JavaScript
MIT License

View all related MCP servers