# Runtype for Coding Agents

You are reading the agent-facing setup script served by `https://runtype.ai`. Your objective is to connect the live hosted Runtype MCP server in this coding harness, then build the user's AI product.

## Setup decision tree

1. **If your MCP client supports browser OAuth**, connect the live hosted MCP server first. It will ask the user to sign in or sign up in-browser.
2. **If OAuth is not available from this harness, or the user explicitly wants agent-first signup before MCP**, use the agent-first signup API below to create a pre-claim API key, then claim it with the user's email.
3. **After signup/auth, connect the live hosted MCP server.** Use `https://api.runtype.com/v1/mcp/protocol` and complete browser OAuth in the MCP client; this is the normal onboarding path.
4. **If live MCP OAuth cannot be completed yet**, use the Runtype CLI with `RUNTYPE_API_KEY` as a temporary stand-in, then return to live MCP as soon as the harness can authenticate it.
5. **Before building anything with MCP**, call `get_build_instructions({ "task": "build-product", "description": "..." })` from the live MCP server.

## Install platform knowledge

Install the Runtype agent skills so your harness has the platform mental model, examples, CLI commands, and build recipes:

```
npx skills add runtypelabs/skills
```

This works with Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini, and 25+ more agents via [skills.sh](https://skills.sh). The router skill activates specialists for product building, account operations, Persona embeds, template packaging, and SDK/CLI usage.

## Preferred: live hosted MCP with OAuth

Use the live Runtype MCP server whenever your harness can open a browser OAuth flow for the user. This is the same direction we use in dashboard onboarding and on the website.

Claude Code:

```
claude mcp add --transport http runtype https://api.runtype.com/v1/mcp/protocol
```

Generic MCP config:

```json
{
  "mcpServers": {
    "runtype": {
      "url": "https://api.runtype.com/v1/mcp/protocol"
    }
  }
}
```

On first use, the MCP client should prompt the user to authenticate in-browser. If the user does not have an account yet, they can sign up during that flow.

## Agent-first signup API

Use this when you need to sign up before MCP OAuth is available. The canonical protocol is also documented at `https://runtype.com/auth.md` and advertised from `https://api.runtype.com/.well-known/oauth-authorization-server` under `agent_auth`.

Two identity types are supported. If your runtime holds an identity assertion, use it: registration completes in one request with no email ceremony. Otherwise use anonymous registration plus the email claim flow.

### Register with an identity assertion (one step, preferred when available)

If your runtime can mint an ID-JAG (Identity Assertion JWT Authorization Grant, assertion type `urn:ietf:params:oauth:token-type:id-jag`) from a trusted agent identity provider such as WorkOS (`https://auth.workos.bot`), exchange it directly for a full-access API key. The assertion must carry a verified email and be addressed to `https://api.runtype.com/agent/auth` (or `https://api.runtype.com`).

```
export RUNTYPE_ID_JAG="<id-jag-jwt>"
ASSERTION_BODY=$(node -e 'process.stdout.write(JSON.stringify({type: "identity_assertion", assertion_type: "urn:ietf:params:oauth:token-type:id-jag", assertion: process.env.RUNTYPE_ID_JAG, requested_credential_type: "api_key"}))')

REGISTRATION_JSON=$(curl -sS -X POST https://api.runtype.com/agent/auth \
  -H 'Content-Type: application/json' \
  -d "$ASSERTION_BODY")

export RUNTYPE_API_KEY=$(REGISTRATION_JSON="$REGISTRATION_JSON" node -e 'process.stdout.write(JSON.parse(process.env.REGISTRATION_JSON).credential)')
```

The returned key is already full-access (no claim step, no 24-hour expiry). If the response is `email_already_registered`, the asserted email already owns a Runtype account: ask the user to sign in with live hosted MCP OAuth or create an API key at `https://use.runtype.com/settings/api-keys`. If the response is `untrusted_issuer` or `invalid_assertion`, fall back to anonymous registration below.

### 1. Register anonymously

```
REGISTRATION_JSON=$(curl -sS -X POST https://api.runtype.com/agent/auth \
  -H 'Content-Type: application/json' \
  -d '{"type":"anonymous","requested_credential_type":"api_key"}')

export RUNTYPE_API_KEY=$(REGISTRATION_JSON="$REGISTRATION_JSON" node -e 'process.stdout.write(JSON.parse(process.env.REGISTRATION_JSON).credential)')
export RUNTYPE_AGENT_CLAIM_TOKEN=$(REGISTRATION_JSON="$REGISTRATION_JSON" node -e 'process.stdout.write(JSON.parse(process.env.REGISTRATION_JSON).claim_token)')
```

The returned pre-claim key expires after 24 hours. It can build and run with scoped access, but it cannot manage secrets, API keys, integrations, schedules, webhooks, messaging, A2A, or deletes.

### 2. Verify the pre-claim key

Run a safe read before continuing so you know the credential works without dumping account data into the transcript:

```
curl -sS -o /tmp/runtype-profile.json -w 'HTTP %{http_code}
'   -H "Authorization: Bearer $RUNTYPE_API_KEY"   https://api.runtype.com/v1/users/profile
```

Expect `HTTP 200`. If you get `401`, discard the key and register again.

### 3. Claim the account with the user's email

Ask the user which email address should own the account, then run:

```
export RUNTYPE_EMAIL="user@example.com"
CLAIM_BODY=$(node -e 'process.stdout.write(JSON.stringify({claim_token: process.env.RUNTYPE_AGENT_CLAIM_TOKEN, email: process.env.RUNTYPE_EMAIL}))')

curl -sS -X POST https://api.runtype.com/agent/auth/claim \
  -H 'Content-Type: application/json' \
  -d "$CLAIM_BODY"
```

The user receives a 6-digit one-time code by email. Ask the user for that code.

### 4. Complete the claim and replace the key

```
export RUNTYPE_OTP="123456"
COMPLETE_BODY=$(node -e 'process.stdout.write(JSON.stringify({claim_token: process.env.RUNTYPE_AGENT_CLAIM_TOKEN, otp: process.env.RUNTYPE_OTP}))')

CLAIMED_JSON=$(curl -sS -X POST https://api.runtype.com/agent/auth/claim/complete \
  -H 'Content-Type: application/json' \
  -d "$COMPLETE_BODY")

export RUNTYPE_API_KEY=$(CLAIMED_JSON="$CLAIMED_JSON" node -e 'process.stdout.write(JSON.parse(process.env.CLAIMED_JSON).credential)')
```

Important: claim completion revokes the pre-claim key and returns a fresh full-access key. Save the new `RUNTYPE_API_KEY` for CLI fallback only, then connect the live hosted MCP server with browser OAuth:

```
claude mcp add --transport http runtype https://api.runtype.com/v1/mcp/protocol
```

If `email_already_registered` is returned, do not keep retrying agent-first signup. Ask the user to sign in with live hosted MCP OAuth, run `runtype auth login`, or create an API key at `https://use.runtype.com/settings/api-keys`.

## CLI stand-in before live MCP auth

The CLI is useful when live MCP is not connected yet or your harness can only run shell commands. This is a temporary fallback, not a replacement for connecting the live MCP server:

```
npm install -g @runtypelabs/cli
runtype auth login
runtype auth whoami
export RUNTYPE_API_KEY=$(runtype auth export-key)
```

If you already have a post-claim agent-first key in `RUNTYPE_API_KEY`, CLI commands will use it without a stored login. Useful commands: `runtype agents list`, `runtype flows list`, `runtype dispatch`, `runtype records create`, `runtype products init`, `runtype validate-product`, and `runtype --help`.

## Build workflow after live MCP connects

1. Call `get_build_instructions` first:

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

2. Use `get_platform_documentation` for exact schemas and catalogs, especially `surface-types`, `flow-step-types`, `product-schema`, `types-fpo`, `builtin-tools`, `agent-skills`, `persona-embed`, and `sdk-reference`.
3. Create or update resources with MCP tools. Validate before sharing or shipping: `validate_flow`, `validate_product`, or the relevant product/flow validation tool.
4. Test the result with a real run (`run_flow`, `execute_agent`, dispatch, or the surface-specific test tool) and report concrete IDs/URLs back to the user.

## What you can build

Once connected to the live hosted MCP server, MCP exposes tools for:

- Creating agents, flows, products, records, secrets, evals, and surfaces
- Running prompt chains, transforms, conditionals, loops, retrieval, and dispatch flows
- Attaching built-in tools, external HTTP tools, MCP tools, flow tools, and subagents
- Shipping chat widgets, APIs, MCP surfaces, webhooks, Slack/email/SMS/Telegram/Discord/WhatsApp/iMessage surfaces, schedules, and hosted pages
- Packaging and validating full product objects (FPOs) and reusable templates

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