MCP server gRPC

Setting up gRPC clients at module scope

Create gRPC channels (clients) once at module startup, not inside tool handlers. A gRPC channel maintains a connection pool and handles reconnection automatically — creating a new channel per tool call bypasses the pool and introduces connection overhead on every call:

// grpc-clients.ts — shared gRPC client instances
import * as grpc from '@grpc/grpc-js';
import * as protoLoader from '@grpc/proto-loader';
import { fileURLToPath } from 'node:url';
import { join, dirname } from 'node:path';

const __dirname = dirname(fileURLToPath(import.meta.url));

// Load proto definitions at startup
const documentsDef = protoLoader.loadSync(
  join(__dirname, '../proto/documents.proto'),
  { keepCase: true, longs: String, enums: String, defaults: true, oneofs: true }
);
const searchDef = protoLoader.loadSync(
  join(__dirname, '../proto/search.proto'),
  { keepCase: true, longs: String, enums: String, defaults: true, oneofs: true }
);

const documentsProto = grpc.loadPackageDefinition(documentsDef) as any;
const searchProto = grpc.loadPackageDefinition(searchDef) as any;

// Create one channel per service — reused across all tool calls
export const documentsClient = new documentsProto.documents.DocumentsService(
  process.env.DOCUMENTS_SERVICE_ADDR ?? 'localhost:50051',
  grpc.credentials.createInsecure()
);

export const searchClient = new searchProto.search.SearchService(
  process.env.SEARCH_SERVICE_ADDR ?? 'localhost:50052',
  grpc.credentials.createInsecure()
);

// Graceful shutdown — close channels before process exit
export function closeGrpcClients() {
  documentsClient.close();
  searchClient.close();
}

Use grpc.credentials.createSsl() in production for services on separate hosts. For internal Kubernetes pod-to-pod calls on the same cluster network without external exposure, createInsecure() is acceptable — TLS is handled at the service mesh layer (Istio, Linkerd) if required.

Tool handler with gRPC call and error mapping

Wrap gRPC calls in a promisified helper that maps gRPC status codes to MCP error patterns. gRPC uses a callback-based API in @grpc/grpc-js, so promisify at the call site or write a thin wrapper:

// grpc-call.ts — promisified gRPC call with error mapping
import * as grpc from '@grpc/grpc-js';

export interface GrpcResult<T> {
  data?: T;
  isError: boolean;
  errorText?: string;
  retryable: boolean;
}

export function grpcCall<T>(
  fn: (metadata: grpc.Metadata, callback: (err: grpc.ServiceError | null, res: T) => void) => void,
  metadata: grpc.Metadata
): Promise<GrpcResult<T>> {
  return new Promise((resolve) => {
    fn(metadata, (err, res) => {
      if (!err) {
        resolve({ data: res, isError: false, retryable: false });
        return;
      }

      // Map gRPC status codes to MCP error semantics
      const retryable = [
        grpc.status.UNAVAILABLE,
        grpc.status.DEADLINE_EXCEEDED,
        grpc.status.RESOURCE_EXHAUSTED,
      ].includes(err.code ?? -1);

      resolve({
        isError: true,
        errorText: `${err.message} (gRPC ${err.code})${retryable ? ' — transient, retry in a few seconds' : ''}`,
        retryable,
      });
    });
  });
}

// Tool handler using the wrapper
server.tool(
  'search_documents',
  'Full-text search across all documents',
  { query: z.string().min(1), limit: z.number().int().min(1).max(50).default(10) },
  async (args, extra) => {
    const meta = new grpc.Metadata();
    meta.set('mcp-session-id', extra.meta?.sessionId ?? '');
    meta.set('x-request-id', contextStore.getStore()?.requestId ?? '');

    const result = await grpcCall<SearchResponse>(
      (m, cb) => searchClient.search({ query: args.query, limit: args.limit }, m, cb),
      meta
    );

    if (result.isError) {
      return { isError: true, content: [{ type: 'text', text: result.errorText! }] };
    }

    return { content: [{ type: 'text', text: JSON.stringify(result.data!.results) }] };
  }
);

The metadata forwarding (mcp-session-id and x-request-id) propagates the MCP session correlation ID into the gRPC service's logs, enabling end-to-end trace reconstruction across the MCP adapter and the gRPC microservice.

gRPC status code to MCP error mapping

gRPC has 17 status codes. Not all require the same MCP handling:

The key distinction: UNAVAILABLE and DEADLINE_EXCEEDED are transient — return isError: true with a retry hint so the AI client can retry without human intervention. INTERNAL is unexpected state that signals a bug in the gRPC service — let it propagate as an unhandled exception so your global exception handler logs it at error level and AliveMCP's tool-error-rate alert fires.

Monitoring a gRPC-backed MCP server

AliveMCP probes initialize + tools/list — both succeed even when downstream gRPC services are down. This means AliveMCP correctly reports the MCP server as up when gRPC backends are degraded. To monitor end-to-end health (MCP layer + gRPC dependencies), add a dedicated health_check tool that probes all dependencies and configure AliveMCP or a synthetic monitor to call it:

server.tool(
  'health_check',
  'Check the health of all downstream gRPC dependencies',
  {},
  async () => {
    const checks = await Promise.allSettled([
      grpcCall((m, cb) => documentsClient.ping({}, m, cb), new grpc.Metadata()),
      grpcCall((m, cb) => searchClient.ping({}, m, cb), new grpc.Metadata()),
    ]);

    const results = checks.map((r, i) => ({
      service: ['documents', 'search'][i],
      healthy: r.status === 'fulfilled' && !r.value.isError,
      error: r.status === 'rejected' ? String(r.reason) :
             r.value.isError ? r.value.errorText : undefined,
    }));

    const allHealthy = results.every(r => r.healthy);
    return {
      isError: !allHealthy,
      content: [{ type: 'text', text: JSON.stringify({ status: allHealthy ? 'ok' : 'degraded', checks: results }) }],
    };
  }
);

Configure AliveMCP to call health_check on a schedule using the tool-call probe feature. A failing health_check tool result (with isError: true) changes the server's status to degraded in the AliveMCP dashboard and triggers your configured alerts — alerting you to a gRPC backend failure before users hit tool errors.

Related questions

Further reading

• MCP server error handling — isError vs thrown exceptions and retry classification
• MCP server timeout — deadline propagation from MCP to gRPC calls
• MCP server streaming — using progress notifications for gRPC server-streaming responses
• MCP server logging — propagating session_id into gRPC metadata for end-to-end tracing
• MCP server health check — adding dependency health to the probe surface
• AliveMCP — uptime monitoring for MCP servers with gRPC backend dependency tracking