Skip to main content
Glama

MCP Host RPC Bridge

by botanicastudios
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid
MIT License
16
1

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

Related MCP server: Toolhouse MCP Server

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

Core Concepts

Transport Modes

  1. Socket Mode (default) - Uses Unix domain sockets for high-performance local IPC

  2. 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 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
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/botanicastudios/mcp-host-rpc'

If you have feedback or need assistance with the MCP directory API, please join our Discord server