When you finish this page, you will have a local dev server, a working hello tool, and a preview of its View.

Agent-readable docs: append .md to any doc URL, or read /llms.txt.

Create a project

npx bitmcp create my-app
cd my-app

The scaffold includes:

my-app/
  bitmcp.config.ts
  package.json
  src/tools/hello/
    tool.ts
    view.tsx
    preview.ts

Install dependencies

pnpm install

Start the dev server

pnpm dev

Open the preview URL from the terminal. The local Apps host is a View editor: it loads a fixture from preview.ts, calls your tool with that input, and renders the View in a sandbox iframe.

Set a preview fixture

hello/preview.ts

export default { name: "World" };

Save and confirm the preview reloads with that input. See Preview fixtures for named cases.

Edit the hello tool

Change the return value in tool.ts and the displayed text in view.tsx. Save both files and confirm the preview reloads.

Verify preview and health

curl http://127.0.0.1:3000/health

Expect { "ok": true }. Call the hello tool from the preview UI.

Troubleshooting

IDE shows JSX errors (`TS17004`)

If your editor reports Cannot use JSX unless the '--jsx' flag is provided:

Use bitmcp 0.1.1 or newer. Version 0.1.0 scaffolded a tsconfig that pointed at an unpublished package.
Run pnpm install so bitmcp/tsconfig/react.json resolves from node_modules.
Confirm tsconfig.json extends bitmcp/tsconfig/react.json (include the .json suffix).

The scaffold duplicates jsx and noEmit locally so Views typecheck even before install finishes. After install, the shared preset provides the full app config.

To upgrade an existing 0.1.0 project, bump bitmcp to ^0.1.2, remove any @bitmcp/typescript-config devDependency, and set:

tsconfig.json

{
  "extends": "bitmcp/tsconfig/react.json",
  "compilerOptions": { "jsx": "react-jsx", "noEmit": true },
  "include": ["src", "bitmcp.config.ts", ".bitmcp"]
}

Production checklist

Before shipping to production:

Generate BITMCP_STATE_KEY: openssl rand -hex 32
Set http.allowedHosts in bitmcp.config.ts to your public hostname
Set platform secrets (BITMCP_STATE_KEY, and MCP_URL when OAuth is enabled)
Run pnpm build locally to catch errors early
Deploy — Vercel, Cloudflare, or Node
Hit GET /health on your production URL
Connect an MCP client and call a tool
If OAuth is enabled, confirm /.well-known/oauth-authorization-server resolves
Publish your server card with the correct MCP_URL

Environment variables

Variable	When needed	How to set	Example
`BITMCP_ROOT`	CLI cwd differs from project root	Shell or `.env`	`/path/to/my-app`
`BITMCP_STATE_KEY`	Production HTTP with confirm or `ctx.ask`	Platform secret or shell	`openssl rand -hex 32`
`MCP_TRANSPORT`	Override default transport	Shell	`stdio` or `http`
`MCP_PORT`	Custom HTTP port	Shell or `--port`	`3000`
`MCP_HOST`	Custom bind address	Shell	`0.0.0.0`
`MCP_PATH`	Custom MCP path	Shell	`/mcp`
`MCP_URL`	OAuth enabled in production	Platform secret or shell	`https://mcp.example.com/mcp`
`NODE_ENV`	Production mode	Platform or shell	`production`

NODE_ENV=production requires BITMCP_STATE_KEY unless overridden in config.

bitmcp.config.ts

import { defineConfig } from "bitmcp";

export default defineConfig({
  name: "bitmcp-app",
  version: "0.0.1",
});

Field	Description
`name`	Server name (defaults to `package.json` name)
`version`	Server version (defaults to `package.json` version)
`deploy`	`"node"` (default), `"vercel"`, or `"cloudflare"`
`http.allowedHosts`	Hostnames allowed in production
`auth`	OAuth or API key provider

Full config options: Package exports.

Reference

Scripts

Script	Command	Purpose
dev	`pnpm dev`	HTTP plus local Apps preview. Rebuilds Views with esbuild
build	`pnpm build`	Build server bundle and hashed Views
start	`pnpm start`	Production Streamable HTTP

Use bitmcp dev --stdio when a desktop host should spawn the server on stdio.

CLI

Command	Description
`bitmcp create`	Scaffold a new project from the built-in template
`bitmcp dev`	esbuild watch for Views, HTTP, and a local Apps preview
`bitmcp start`	Production Streamable HTTP from `dist/server.js`
`bitmcp build`	Hashed inlined View HTML plus `dist/server.js`

Flag	Applies to	Description
`--stdio`	`dev`	Use stdio instead of HTTP plus preview
`--port N`	`dev`, `start`	Listen port
`--tunnel`	`dev`	Expose localhost via cloudflared for remote MCP clients
`--csp-widget`	`dev`	Show CSP allowlist editor in the preview host

--tunnel requires cloudflared on your PATH.

Installation