Node and custom

Run bitmcp on Node, embed in an existing app, and operate stateless replicas.

OpenAIOpen in ChatGPTAnthropicOpen in Claude

bitmcp build emits dist/server.js with a Web-standard fetch handler plus GET, POST, and OPTIONS. Use that file on Node or any Fetch runtime.

Node

pnpm build
BITMCP_STATE_KEY=... pnpm start

bitmcp start loads dist/server.js and listens on Streamable HTTP.

Default listen address: http://127.0.0.1:3000/mcp

Override with --port or MCP_PORT, MCP_HOST, and MCP_PATH. GET /health is also served.

Set deploy: "node" in bitmcp.config.ts (this is the default).

Set BITMCP_STATE_KEY in production. Configure http.allowedHosts and http.cors in bitmcp.config.ts for public HTTP.

Embed in an existing app

dist/server.js already exports GET, POST, OPTIONS, and default.fetch. Point a platform entry at that file, or call app.fetch yourself:

import app from "../dist/server.js";

export const GET = (request: Request) => app.fetch(request);
export const POST = GET;
export const OPTIONS = GET;

createApp escape hatch

The CLI uses createApp.fromDir() internally. You rarely need this in application code, but it is useful for tests and custom servers:

import { createApp } from "bitmcp";

const app = createApp({
  name: "my-server",
  version: "0.0.1",
  tools: [myTool],
});

await app.stdio();
await app.http({ port: 3000 });
const response = await app.fetch(request);
MethodDescription
stdio()Start stdio transport
http(options?)Start Streamable HTTP on Node
fetch(request)Web-standard handler
const app = await createApp.fromDir("/path/to/project");

Loads tools from src/tools/ using the same discovery rules as the compiler.

Stateless replicas

Every request builds a fresh MCP server. There is no Mcp-Session-Id.

  • Pass handles and ids in tool arguments
  • Store job state behind a HandleStore (KV, Redis, D1)
  • View HTML is content-addressed. Every replica serves the same hash for the same build

Host and Origin guards

localhost bindings include Host and Origin checks. Production app.fetch only enforces hosts you put in allowedHosts.

See also

Vercel and Cloudflare for platform-specific scaffold and config.

PreviousCloudflareNextServer card