Getting Started

Connecting to your server

Attach a host over HTTP or stdio and verify the connection works.

When you finish this page, an MCP client will call your server and receive tool results.

Pick a transport

ModeCommandUse case
HTTPpnpm devLocal Apps preview at http://127.0.0.1:3000
stdiobitmcp dev --stdioClaude Desktop, VS Code, Cursor
HTTPpnpm startProduction (bitmcp start always uses HTTP)

Default listen address: http://127.0.0.1:3000/mcp. Override with --port or MCP_PORT, MCP_HOST, and MCP_PATH. The path match is exact. /foo/mcp does not satisfy /mcp.

Environment variables: see Installation → Environment variables.

Configure your client

See stdio clients or HTTP clients below for host-specific steps.

Verify connection

For HTTP:

curl http://127.0.0.1:3000/health

Expect { "ok": true }. Call a tool from your MCP client or the local preview.

For stdio, invoke any tool from the client and confirm you receive structured content or text.

Remote dev

When a cloud MCP client must reach your laptop:

bitmcp dev --tunnel

The CLI prints a public URL that proxies to your local /mcp endpoint. Requires cloudflared on your PATH.

Preview host

pnpm dev starts a local Apps host. It loads fixtures from preview.ts, calls your tool, renders the View in a sandbox iframe, and reloads when the View hash changes. See Preview fixtures.

stdio clients

Base configuration:

{
  "command": "pnpm",
  "args": ["exec", "bitmcp", "dev", "--stdio"],
  "cwd": "/path/to/my-app"
}

Cursor

  1. Open Cursor Settings → MCP
  2. Add a new stdio server with the JSON block above (set cwd to your project path)
  3. Save and restart the MCP connection
  4. Invoke a tool from chat and confirm a response

Claude Desktop

  1. Open your Claude Desktop config file (claude_desktop_config.json)
  2. Add the server under mcpServers with the JSON block above
  3. Restart Claude Desktop
  4. Invoke a tool and confirm a response

VS Code

  1. Install an MCP extension that supports stdio servers
  2. Point it at pnpm exec bitmcp dev --stdio with your project as cwd
  3. Connect and invoke a tool

HTTP clients

Connect to the Streamable HTTP endpoint your server exposes (for example https://your-app.vercel.app/mcp in production).

Verify the endpoint:

curl https://your-app.vercel.app/health

Host and Origin guards apply on localhost. Production app.fetch only enforces hosts you put in allowedHosts. Set allowedHosts before connecting from a remote client.

How hosts render your app

Request flow:

  1. Host calls your tool over HTTP or stdio
  2. Server returns text and optional structuredContent
  3. UI-capable hosts load your hashed View HTML in a sandbox iframe
  4. The View reads results via useApp()

MRTR (Model-Required Tool Response) is the input_required result type used for confirmations and ctx.ask. Text-only hosts show the confirmation message. UI hosts may also render a preview.

When the client cannot render Apps, bitmcp strips UI metadata for that request. You still get tool text content and MRTR confirmations. Degradation order: text → MRTR → View.

UI-capable hosts advertise the extension io.modelcontextprotocol/ui and MIME type text/html;profile=mcp-app. Cursor, Claude, VS Code, and ChatGPT load your hashed HTML when supported.

App-only defineAction tools stay hidden from model lists on text-only clients.

Reference

GET /health returns { ok: true } on HTTP transports.

PreviousInstallationNextProject structure