# bld402 — Build & Deploy Web Apps

bld402 lets you build and deploy complete web apps for a user who described what they want.
Your job: handle ALL technical details silently. Only ask the user about what the app should DO (features, look, behavior). Never ask about databases, API keys, deployments, wallets, or infrastructure.

## Install (pick one)

### Option A: MCP plugin (recommended)
Add to your MCP config:
```json
{ "mcpServers": { "run402": { "command": "npx", "args": ["run402-mcp"] } } }
```

For Claude Code, run:
```
claude mcp add run402 -- npx -y run402-mcp
```

IMPORTANT: The MCP server provides 52 tools. Your environment may only load a subset initially. If a tool listed below is not in your palette, search for it (e.g. ToolSearch "deploy_function") to load its schema before calling it.

Available tools by category:

**Setup & billing:** init, set_tier, tier_status, status, check_balance, allowance_create, allowance_status, allowance_export, request_faucet, create_checkout, billing_history
**Projects:** provision_postgres_project, project_info, project_keys, project_use, list_projects, get_schema, get_usage, archive_project, pin_project
**Database:** run_sql, setup_rls, rest_query
**Deployment:** deploy_site, get_deployment, bundle_deploy
**Subdomains:** claim_subdomain, delete_subdomain, list_subdomains
**Functions:** deploy_function, invoke_function, list_functions, delete_function, get_function_logs, set_secret, list_secrets, delete_secret
**Storage:** upload_file, download_file, list_files, delete_file
**Apps:** publish_app, get_app, browse_apps, fork_app, list_versions, update_version, delete_version
**Other:** generate_image, send_message, set_agent_contact, get_quote

### Option B: CLI
```
npx run402-mcp          # start MCP server
```

### Option C: Website workflow (no install needed)
Start at https://bld402.com/build/step/1 and follow the guided steps.

## What you can build

Any client-side web app with: database tables, user auth (email/password), file uploads, static hosting, serverless functions, AI image generation. Default tier is Prototype ($0.10 on testnet = free for the user).

Examples: todo lists, recipe books, expense splitters, landing pages, trivia games, workout trackers, gift registries, flash card apps, voting polls, micro-blogs.

13 ready-made templates available — browse at https://bld402.com/templates/

## How to build an app

1. Figure out what the user wants (ask product questions only — "What should the app do? Who will use it?")
2. Install run402-mcp if not already installed (Option A or B above)
3. Use `set_tier` with tier=prototype. If it says "already subscribed" or returns a payment error, that's OK — check with `tier_status` to confirm your tier is active.
4. Use `provision_postgres_project` with a name for your app. This returns a project_id and saves credentials to the local key store. Then call `project_info` with the project_id to get the anon_key, service_key, and REST API URL — you need these for the frontend.
5. Use `run_sql` to create tables and seed data.
6. **Apply RLS (required for public apps).** Use `setup_rls` with template=public_read_write and the table names. Without this, the anon key cannot read or write data and your app's API calls will return 401.
7. **Deploy functions (if needed).** For server-side logic (password hashing, secret matching, etc.), use `deploy_function` with the function code. Use `set_secret` for environment variables (requires redeploy to take effect). Test with `invoke_function` before building the frontend.
8. Build the HTML/CSS/JS frontend. Use the anon_key from step 4. REST API calls from the frontend need this header: `apikey: <anon_key>`. The gateway auto-forwards it as `Authorization: Bearer` to PostgREST. Call functions via `https://api.run402.com/functions/v1/<function_name>` with the same `apikey` header.
9. Use `deploy_site` to deploy the frontend. This returns a `deployment_id` and a CDN URL.
10. Use `claim_subdomain` with the `deployment_id` from step 9 (not project_id) to get a clean URL like myapp.run402.com.
11. Show the user their live URL — done!
12. If they want changes: update SQL/files and redeploy.

For the full API reference, see: https://run402.com/llms.txt

## Critical rules

- NEVER ask the user about technical details (databases, API keys, deployments, hosting, wallets)
- NEVER show the user raw API responses, keys, or error traces
- NEVER use jargon in the app UI (see banned words below)
- Handle wallet creation, payments, and infrastructure silently
- If something fails, fix it yourself or explain in plain language what went wrong
- The user should only ever see: their app idea → a live URL they can share

## Banned words in app UI

Never show these to users in the app you build:
API, endpoint, schema, payload, query, webhook, middleware, database, server, cluster, deployment, container, embedding, vector, tokenize, inference, LLM, GPT.

Rewrite: "Querying the database..." → "Loading your data..."

## Capabilities

| Feature | Details |
|---------|---------|
| Database | Postgres (tables, columns, indexes, SQL) |
| REST API | Full CRUD with filtering, pagination (PostgREST) |
| Auth | Email/password + Google OAuth, JWT tokens |
| Row-level security | user_owns_rows, public_read, public_read_write |
| File storage | Upload, download, signed URLs (S3-backed) |
| Static hosting | Deploy HTML/CSS/JS, get shareable URL |
| Functions | Node.js serverless functions |
| AI images | $0.03/image generation |
| Subdomains | myapp.run402.com (free) |
| Testnet | Base Sepolia — completely free via faucet |

## Limitations

| Not possible | Alternative |
|---|---|
| Custom domains (myapp.com) | Use myapp.run402.com subdomain |
| WebSocket / real-time | Polling (fetch every 3-10s) |
| Email / SMS / push notifications | In-app notifications |
| OAuth providers other than Google | Google OAuth + email/password auth (built in) |
| Payment processing | Track balances in the database |
| Files over 50 MB per deploy | Optimize images, split deploys |
| More than 100 req/sec sustained | Client-side caching |

## Source code

Open source (MIT): https://github.com/kychee-com/run402-mcp

## Powered by

run402.com — full-stack infrastructure for AI agents. For the full API reference, see https://run402.com/llms.txt