@hyperdrift-io/mcp-service-kit

Provider-neutral infrastructure for Hyperdrift MCP services.

The package owns transport, request safety, bearer authentication, rate limiting, structured tool results, stdio startup, and bounded telemetry. Consumers own environment loading, provider credentials, provider authorization, API contracts, workflows, and deployment.

Exports

• @hyperdrift-io/mcp-service-kit/auth
• @hyperdrift-io/mcp-service-kit/http
• @hyperdrift-io/mcp-service-kit/results
• @hyperdrift-io/mcp-service-kit/stdio
• @hyperdrift-io/mcp-service-kit/telemetry

HTTP

import { authenticateBearer } from "@hyperdrift-io/mcp-service-kit/auth";
import {
  createMcpHttpServer,
  listenMcpHttpServer,
} from "@hyperdrift-io/mcp-service-kit/http";

const server = createMcpHttpServer({
  port: 3014,
  requestBaseUrl: "http://127.0.0.1:3014",
  allowedOrigins: [],
  service: "example-mcp",
  version: "0.1.0",
  authenticate: (request) => authenticateBearer(request.headers, process.env.MCP_BEARER_TOKEN!),
  createServer: () => createExampleMcpServer(),
  health: () => ({ provider_mode: "fixture" }),
});

await listenMcpHttpServer(server, { port: 3014 });

The server factory has no import-time side effects. It exposes GET /health, accepts only POST /mcp, limits request bodies to one MiB by default, and creates one MCP server per request. It resolves MCP requests against requestBaseUrl rather than an incoming Host header. Requests without an Origin header are accepted for native MCP clients; browser-origin requests require an exact allowedOrigins entry.

listenMcpHttpServer installs process signal handlers because the caller explicitly asks it to own the standalone process lifecycle. Embedded hosts should call createMcpHttpServer and manage the returned Node server directly.

Stdio

import { runStdioServer } from "@hyperdrift-io/mcp-service-kit/stdio";

await runStdioServer(() => createExampleMcpServer());

The stdio runner writes startup errors to stderr and never writes logs to stdout.

Results

import { structuredToolResult } from "@hyperdrift-io/mcp-service-kit/results";

return structuredToolResult({ items }, (value) => `Found ${value.items.length} items.`);

Telemetry

import { createTelemetryEmitter } from "@hyperdrift-io/mcp-service-kit/telemetry";

const emit = createTelemetryEmitter({
  deliveryId: "mcp-maker-000-example",
  service: "example-mcp",
});

emit("mcp_tool_called", { tool: "example_list_items", outcome: "success" });

Telemetry accepts only bounded lifecycle and tool metadata. Unknown fields are dropped. Do not pass provider records or raw tool inputs as telemetry metadata.