# Runtype for Coding Agents

You are reading the setup script served by `https://runtype.ai`. Your durable goal is to leave this coding harness connected to Runtype's hosted MCP server. Use the Runtype CLI as a bridge during this first session; do not treat it as the final integration.

Signup never requires a browser. The only things you may ask the user for are their email address and the 6-digit code Runtype emails them. Do not tell the user to open a dashboard, sign-in page, or OAuth window during signup.

## Golden path — do exactly this

If the live Runtype MCP tools are already available in this session, skip setup and go to "After MCP is active" below. Otherwise follow every step in order:

### 1. Install the CLI and check auth

```bash
npm install -g @runtypelabs/cli
runtype auth status
```

If status reports `authenticated` with `accountState: "full"`, skip to step 3. If it reports a pending signup, its `next` field tells you the exact command to resume with.

### 2. Sign the user up from the terminal

Ask the user one question: "What email address should I use for your Runtype account?" Then run:

```bash
runtype auth register --email <their-email>
```

This creates the account and emails the user a 6-digit code. Ask the user: "Runtype emailed a 6-digit code to <their-email> — what is it?" Then run:

```bash
runtype auth verify <code>
```

That completes signup. Every command in this flow prints JSON with a `next` field — follow it. Notes:

- These commands work without a TTY and never open a browser.
- `register` is safe to re-run; it resumes a pending signup instead of creating a duplicate account.
- After `register` (before `verify`) you already hold a temporary credential: CLI commands work with restricted models and quota, and `verify` upgrades the same stored login in place. Do not build anything substantial until `verify` succeeds.
- If the email already has a Runtype account, the command reports `email_already_registered`. In that case ask the user for an API key from their dashboard (Settings > API keys) and run `runtype auth login --api-key <key>` instead. This is the only path where the user touches the dashboard, and only because they already have an account.
- A wrong code returns `otp_invalid` — ask the user to re-check and run `runtype auth verify` again. An expired code returns `otp_expired` — re-send with `runtype auth claim <email>`. Codes expire after 10 minutes and lock after 5 wrong attempts, so confirm the code with the user rather than guessing; after a lockout or expiry, re-send with `runtype auth claim <email>`.

### 3. Install skills and the MCP connection

```bash
runtype install-mcp
```

This command detects the current coding harness, installs the Runtype agent skills for it, and writes the user-level hosted MCP configuration. If it asks which harness to configure, select the harness running this session. If it reports an OAuth action for the harness's own MCP connection, relay that instruction to the user for later — it happens on the harness's schedule, not during signup. That harness-side OAuth may open a browser when the user runs it; that is fine and expected — the no-browser rule above applies to Runtype signup, not to the harness's own connection ceremony.

### 4. Keep working in this session with the CLI

Do not stop just because the new MCP connection is not visible yet. Use CLI commands for useful first-session work:

```bash
runtype auth whoami
runtype agents list
runtype flows list
runtype products list
runtype --help
```

The CLI also supports dispatch, records, validation, product setup, and other account operations. Read command help before mutating resources, and report concrete IDs and URLs to the user. If you need Runtype MCP tools before the restart, the CLI bridges them: `runtype mcp tools` lists them and `runtype mcp call <tool>` invokes one — same hosted tools, no restart needed.

### 5. Tell the user to restart or reload the harness

Before finishing this session, read the final status and next steps from `runtype install-mcp`. Retry any failed skill installation. Do not call setup complete while the command reports `action-required`, `partial`, or an error.

Only after signup is verified and skills are installed, tell the user exactly what changed and ask them to restart or reload the coding harness. Use direct language such as:

> Your Runtype account is verified and the skills plus MCP connection are installed. Please restart or reload this coding agent (or start a new session) so it can activate the new MCP tools. I used the CLI to keep this first session productive; after restart I will use MCP by default.

If an action remains, report that exact action instead of using the success wording above. Do not claim the running agent can use MCP until its Runtype tools actually appear.

### 6. Switch to MCP after restart

In the next session, use Runtype MCP first. Do not fall back to the CLI just because it worked previously. Start by calling:

```json
{
  "task": "build-product",
  "description": "Describe the user's product goal here"
}
```

with `get_build_instructions`. Then use `get_platform_documentation` for exact schemas and catalogs, create or update resources with MCP tools, validate them, and test the result with a real run.

## If the install needs recovery

`runtype install-mcp` intentionally changes one confidently selected harness, not every agent config it can find. If detection is ambiguous, re-run it with one explicit id:

```bash
runtype install-mcp --agent claude
runtype install-mcp --agent codex
runtype install-mcp --agent cursor
runtype install-mcp --agent gemini
runtype install-mcp --agent opencode
runtype install-mcp --agent vscode
```

Use only the line for the current harness. Follow the command's restart instructions. Use `--force` only when the command reports that an existing MCP server named `runtype` points to a different URL and the user agrees to replace it.

## Auth reference

The signup commands wrap the agent auth protocol documented at `https://runtype.com/auth.md` (anonymous registration plus an email claim ceremony). You normally never need the raw protocol — the CLI is the supported client:

- `runtype auth register --email <email>` — create the account and send the code (one step)
- `runtype auth claim <email>` — re-send or change the email for a pending signup
- `runtype auth verify <code>` — finish signup with the 6-digit code
- `runtype auth login --api-key <key>` — existing accounts only
- `runtype auth status` / `runtype auth whoami` — inspect the current login

A user-supplied `RUNTYPE_API_KEY` environment variable also authenticates every CLI command without a stored login. Never print a credential into the transcript or write one into a committed file.

Browser login (`runtype auth login` with no flags) exists for humans running the CLI in their own interactive terminal. Do not use it from a coding harness.

## After MCP is active

- Call `get_build_instructions` before building.
- Use `get_platform_documentation` instead of inventing payload shapes.
- Let the installed Runtype skills route task-specific work: product builds, live account operations, Persona embeds, templates, and SDK/CLI workflows.
- If the user gives you a `use.runtype.com/now?...`, example, or template/FPO link, use the Runtype template skill and MCP tools rather than opening the login-gated dashboard page.
- Validate before shipping and test with a real execution.

Runtype MCP can create and operate agents, flows, products, records, secrets, evals, and surfaces; attach built-in, HTTP, MCP, flow, and subagent tools; and ship chat, API, webhook, messaging, schedule, MCP, and hosted-page experiences.

Docs: [runtype.com](https://runtype.com)
Dashboard: [use.runtype.com](https://use.runtype.com)
API: [api.runtype.com](https://api.runtype.com)