Reference
Package exports
Subpath imports, config fields, and programmatic createApp usage.
Subpath exports
| Subpath | Import | Use |
|---|---|---|
bitmcp | defineTool, defineConfig, createApp, result | Core runtime and CLI config |
bitmcp/react | useApp, AppShell | View hooks and shell |
bitmcp/server | server card, UI envelope helpers | Custom deployments |
bitmcp/oauth | jwtOAuthProvider, custom | Custom OAuth providers |
bitmcp/oauth/supabase | supabase() | Supabase OAuth |
bitmcp/oauth/auth0 | auth0() | Auth0 OAuth |
bitmcp/oauth/better-auth | betterAuth() | Better Auth OAuth |
bitmcp/auth/api-key | API key auth plugin | Dev HTTP gate |
bitmcp/analytics/posthog | posthog() | Tool-call analytics |
bitmcp/tasks | taskResult, clientSupportsTasks | Optional MCP tasks extension |
bitmcp/deploy | deploy adapters | Custom platform wiring |
bitmcp/tsconfig/react.json | tsconfig preset | App TypeScript config |
Peer dependencies: react and @modelcontextprotocol/ext-apps for bitmcp/react; posthog-node and @posthog/mcp for analytics.
defineConfig fields
| Field | Description |
|---|---|
name, version | Server identity (defaults from package.json) |
deploy | "node", "vercel", or "cloudflare" |
cacheTtlMs | View resource cache TTL |
stateKeyEnv | Env var name for MRTR state key (default built-in) |
requireStateKey | Force state key in non-production |
auth | OAuth or API key plugin |
analytics | One or more analytics plugins |
serverCard | Discovery metadata or false to disable |
http.path | MCP HTTP path (default /mcp) |
http.allowedHosts | Production host allowlist |
http.allowedOrigins | Origin allowlist |
http.cors | CORS configuration |
Environment variables: Installation.
Programmatic API
For tests and custom servers outside the file-based compiler:
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);| Method | Description |
|---|---|
stdio() | Start stdio transport |
http(options?) | Start Streamable HTTP on Node |
fetch(request) | Web-standard handler |
Load a project from disk with the same discovery rules as the CLI:
const app = await createApp.fromDir("/path/to/project");bitmcp dev uses loadProject() and watches Views. bitmcp start runs dist/server.js when built.
Tasks extension
When the client advertises io.modelcontextprotocol/tasks, you may return:
import { taskResult } from "bitmcp/tasks";
return taskResult(taskId, data);For most long-running work, Handles remain the recommended pattern.