Registry / ai-ml / mcp-grpc-transport

mcp-grpc-transport

library0.2.0jsnpmunverified

Pluggable gRPC transport for Model Context Protocol (MCP) servers, built on @modelcontextprotocol/sdk (peer dep ^1.27.0). Current stable version 0.2.0 (pre-1.0, wire format may evolve). Exposes three protobuf service surfaces: grpc.health.v1.Health for Kubernetes probes, model_context_protocol.Mcp (unary/streaming RPCs like ListTools, CallTool) aligned with the community mcp-python-sdk-grpc-poc reference, and optional mcp.transport.v1.Mcp.Session for JSON-RPC over gRPC. Requires Node >=22 and ESM-only. TypeScript types included. Optional gRPC server reflection via ENABLE_GRPC_REFLECTION=1.

ai-ml devops

npm install mcp-grpc-transport

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MCP-GRPC-TRANSPORT

mcp-grpc-transport

ai-mljavascriptv0.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

McpServerTransport

✓ import { McpServerTransport } from 'mcp-grpc-transport'

✗ const { McpServerTransport } = require('mcp-grpc-transport')

ESM-only since v0.1.0; CommonJS require() will fail with ERR_REQUIRE_ESM.

createHealthService

✓ import { createHealthService } from 'mcp-grpc-transport'

✗ import { HealthService } from 'mcp-grpc-transport'

The export is a factory function, not a class. HealthService is the internal implementation.

McpDef

✓ import { McpDef } from 'mcp-grpc-transport'

TypeScript type definition for the model_context_protocol.Mcp service. Only useful for gRPC client codegen scenarios.

McpServerTransportOptions

✓ import type { McpServerTransportOptions } from 'mcp-grpc-transport'

✗ import { McpServerTransportOptions } from 'mcp-grpc-transport'

TypeScript-only export; bundlers will emit a warning if used at runtime.

Creates a gRPC server with health checking and connects an MCP server from @modelcontextprotocol/sdk.

import { McpServerTransport, createHealthService } from 'mcp-grpc-transport'; import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; const healthService = createHealthService({ grpc: { maxConcurrentStreams: 10 }, }); const transport = new McpServerTransport({ service: healthService, host: '0.0.0.0', port: 50051, credentials: grpc.ServerCredentials.createInsecure(), // for dev only }); const server = new McpServer({ name: 'my-mcp-server', version: '1.0.0', }); server.connect(transport); process.on('SIGTERM', () => { transport.close(); });

Debug

Known issues

breakingRequires Node.js >=22 (engine.strict). Older versions will fail to install or run.

fix

Upgrade Node.js to v22 or later.

affects: <22

breakingESM-only package. Using require() throws ERR_REQUIRE_ESM.

fix

Use import syntax or dynamic import() in CommonJS files.

affects: >=0.1.0

deprecatedPeer dependency @modelcontextprotocol/sdk ^1.27.0 — expect major version changes to alter the transport interface.

fix

Check CHANGELOG.md before upgrading @modelcontextprotocol/sdk beyond ^1.x.

affects: >=0.1.0

gotchaClients must send MCP protocol version as metadata (metadata key 'mcp-protocol-version'). Missing metadata causes 'missing metadata: mcp-protocol-version' error.

fix

Set metadata: { 'mcp-protocol-version': '2024-11-05' } (or other supported version string).

affects: >=0.1.0

gotchagRPC reflection is disabled by default. Without it, grpcurl cannot list services unless you set ENABLE_GRPC_REFLECTION=1.

fix

Set environment variable ENABLE_GRPC_REFLECTION=1 before starting the server.

affects: >=0.1.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/mcp-grpc-transport/src/index.ts from /path/to/your-file.js not supported.

Package is ESM-only, but user is using require() or the project is set to CommonJS.

fix

Change to import syntax (e.g., import { McpServerTransport } from 'mcp-grpc-transport') or use dynamic import() in CommonJS files.

TypeError: Cannot destructure property 'McpServerTransport' of 'require(...)' as it is undefined.

Using require() on an ESM-only package that does not export a CommonJS wrapper.

fix

Use import() or switch to ESM in your project (type: module in package.json).

Error: 12 UNIMPLEMENTED: Service 'grpc.health.v1.Health' is not implemented.

ENABLE_GRPC_REFLECTION not set, or the health service was not passed to McpServerTransport.

fix

Set ENABLE_GRPC_REFLECTION=1 in environment and/or ensure createHealthService() is called and passed as service option.

Error: missing metadata: mcp-protocol-version

gRPC client did not send the required metadata key on calls to MCP service.

fix

Add metadata { 'mcp-protocol-version': '2024-11-05' } to gRPC invocation. Use exact strings from @modelcontextprotocol/sdk's supportedProtocolVersions.

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

@modelcontextprotocol/sdkrequiredPeer dependency — provides core MCP server/transport abstractions that mcp-grpc-transport wraps with gRPC

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/danielsmithdevelopment/ClawQL ↗

packagemcp-grpc-transport ↗

homepagehttps://github.com/danielsmithdevelopment/ClawQL/tree/main/packages/mcp-grpc-transport#readme ↗