> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.runtype.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server. # Connect Runtype to coding agents > Connect Claude Code, Cursor, Codex, Gemini CLI, OpenCode, or VS Code to Runtype with the Runtype CLI. Run the following command to connect the coding agent in your current session to Runtype: **`Onboard the coding agent`** ```bash title="Onboard the coding agent" npx -y @runtypelabs/cli@latest onboard ``` The command signs you in to Runtype, configures the hosted OAuth MCP connection, installs Runtype agent skills, and prints the next steps. After you restart or reload the coding agent, use it to build and operate Products, Flows, Agents, Tools, Surfaces, and Records in your Runtype account. For Claude Desktop, see [Install Runtype in Claude Desktop](/developer-guides/integrations/runtype-mcp-server#install-runtype-in-claude-desktop). ## What onboard does The `onboard` command runs setup in the following order: 1. **Sign in to the CLI.** Onboard uses a stored CLI credential or `RUNTYPE_API_KEY`. Without either, it opens browser sign-in, but only in an interactive terminal. In a noninteractive shell, it prints sign-in instructions instead. To sign in without a browser, see [Browserless CLI authentication](#browserless-cli-authentication). 2. **Detect the coding agent.** Onboard configures the coding agent that runs it. To choose one yourself, see [Select a coding agent](#select-a-coding-agent). 3. **Configure MCP.** Onboard writes a user-level MCP server entry named `runtype` that points to `https://api.runtype.com/v1/mcp/protocol`. 4. **Authorize MCP.** Onboard starts the coding agent's MCP OAuth flow when the agent supports it. Otherwise, it prints the agent's OAuth instruction. 5. **Install skills.** Onboard installs Runtype agent skills from the public `runtypelabs/skills` repository for the coding agent. 6. **Restart or reload.** Onboard prints the restart instruction for the coding agent. You can run `onboard` again at any time. It doesn't duplicate the `runtype` entry. When it edits a configuration file directly, it backs up the file, checks the new entry, and restores the backup if the check fails. ### Select a coding agent To configure a specific coding agent, run: **`Select a coding agent`** ```bash title="Select a coding agent" runtype onboard --agent ``` Replace the following: * ``: `claude`, `codex`, `cursor`, `gemini`, `opencode`, or `vscode`. These IDs apply to `runtype onboard`. `runtype skills install --agent` uses different IDs for two agents: `gemini-cli` for Gemini CLI and `copilot` for VS Code. When skills installation fails, copy the retry command that onboard prints. ### Onboard options Use the following options to preview or limit setup: * `--dry-run`: shows the selected coding agent and the planned changes without writing them. * `--no-login`: skips browser sign-in and MCP OAuth. Onboard prints the OAuth command to run later. * `--no-skills`: skips skills installation. To install them later, run `runtype skills install`. * `--force`: replaces an existing `runtype` MCP entry that points to another URL. Use it only when onboard reports that conflict. * `--json`: prints the result as JSON. JSON mode also skips browser sign-in and MCP OAuth, as `--no-login` does. * `--print-instructions`: prints the Runtype agent onboarding instructions and exits. ## Check the result Onboard prints `Onboarding status:` followed by one of the following values. With `--json`, the same value is in the `status` field. * `ok`: you are signed in and MCP OAuth is complete. Restart or reload the coding agent. * `action-required`: MCP is configured, but you still need to sign in or finish OAuth. Follow the numbered steps that onboard prints, then restart. * `partial`: MCP OAuth or skills installation failed. The command exits with code 1. Follow the printed steps before you restart. * `planned`: you ran `--dry-run`, so nothing changed. If onboard can't read your credentials, select a coding agent, or write the MCP entry, it stops with exit code 1 and prints the error instead of a status. With `--json`, the `status` field is `error` and the `code` field names the failed stage. ## Verify the connection The coding agent session that ran onboard might not see the new MCP connection until you restart it. Until then, that session can keep using the Runtype CLI. After the restart, check that `runtype` appears in the coding agent's MCP server list, for example with `claude mcp list` in Claude Code. Then ask a read-only question such as "Which Runtype organization am I connected to?" To start building, use a prompt such as "Use Runtype to build a customer-support agent." The coding agent loads the Runtype build instructions before it builds a product or flow. Read-only questions about your account don't need them. ## Choose an organization The browser authorization screen binds the connection to one organization. If you belong to more than one organization, select the one you want on that screen before you approve. The connection then reads only that organization's flows, agents, tools, and records, and no per-request setting changes it afterward. The access token stays scoped to that organization for 90 days. When it expires, run the coding agent's MCP sign-in again, for example `claude mcp login runtype`. To move an existing connection to a different organization, run the coding agent's MCP sign-in again and select the other organization. The new token replaces the old one for that server entry. Onboard only writes the entry named `runtype`. To keep a second organization connected at the same time, add a second entry under another name with the coding agent's own CLI, then sign in and select the other organization. For example, in Claude Code: **`Add a second organization in Claude Code`** ```bash title="Add a second organization in Claude Code" claude mcp add --transport http --scope user runtype-acme https://api.runtype.com/v1/mcp/protocol claude mcp login runtype-acme ``` To disconnect, remove the server entry with the coding agent's CLI, for example `claude mcp remove runtype`. ## Browserless CLI authentication The commands in this section use the `runtype` executable. If you started with `npx`, install the CLI first, or replace `runtype` with `npx -y @runtypelabs/cli@latest` in each command: **`Install the Runtype CLI`** ```bash title="Install the Runtype CLI" npm install -g @runtypelabs/cli ``` To check for an existing sign-in or a pending signup, run `runtype auth status`. This command doesn't read `RUNTYPE_API_KEY`. If you set that variable, run `runtype auth whoami --no-tty` instead. To resume a pending signup, run the `next` command that `auth status` returns. To create an account without a browser: 1. Run `runtype auth register --email `. 2. Copy the 6-digit code from the verification email. 3. Run `runtype auth verify `. 4. Run `runtype onboard` again. To use an existing account: 1. Create an API key in the dashboard on **Settings > API**. For details, see [Managing API keys](/user-guide/settings/managing-api-keys). 2. In your own terminal, run `runtype auth login --api-key `, or set the `RUNTYPE_API_KEY` environment variable. 3. Run `runtype auth whoami --no-tty` to confirm the sign-in. 4. Run `runtype onboard` again. Don't paste an API key into a coding agent chat. MCP OAuth is a separate authorization that onboard starts after CLI sign-in. ### Approve a key for a coding agent A coding agent that is already signed in to the CLI can ask you to approve a new, narrower API key instead of receiving one from you. The agent runs the following command: **`Request an API key`** ```bash title="Request an API key" runtype api-keys request --name --scopes --reason ``` Replace the following: * ``: a name for the key, for example `support-agent-dev`. * ``: a comma-separated scope list, for example `FLOWS:READ,RECORDS:READ`. * ``: why the agent needs the key. The approver sees this text. The command opens an approval page in the browser and waits. After you approve the request, the command saves the key to a key file. If the command stops before you decide, it prints a `runtype api-keys claim` command that resumes the request. ## Use the CLI safely from a coding agent After you restart the coding agent, prefer the hosted MCP connection. When a script or the first session needs the CLI, check which endpoint and credential it uses first: **`Inspect the CLI target`** ```bash title="Inspect the CLI target" runtype config context --json ``` `config context` makes no API request. It shows the endpoint and the credential source without showing the key. `orgVerified: false` means that the CLI has not checked the saved organization against the server. To run a flow only when the CLI points at the expected endpoint and organization, run: **`Run a flow with guardrails`** ```bash title="Run a flow with guardrails" runtype --no-input --expect-api-url https://api.runtype.com --expect-org \ flows run --inputs '{"limit":5,"enabled":true}' --json ``` Replace the following: * ``: the ID of your organization. * ``: the ID of the flow to run. `--expect-org` checks the organization with the server before any API action. The CLI picks the endpoint from `--api-url`, then `RUNTYPE_API_URL`, then the `apiUrl` in the nearest `.runtype/project.json`, then the saved `apiUrl` setting, then the endpoint of the selected login, and finally production. To pin the organization instead of only checking it, pass `--org ` or link the project with `runtype link `. A saved `apiUrl` setting applies to every API command, so remove a stale one before you rely on the default. `auth claim` and `auth verify` keep the endpoint that issued the signup token and check it against `--expect-api-url`. `auth register`, `auth claim`, and `auth verify` reject `--expect-org`. `dispatch`, `flows run`, and `agents execute` accept typed JSON objects through `--inputs` or `--inputs-file `, and message arrays through `--messages-file `. Pass `-` as the file to read from stdin. Only one option can read stdin. Values from the repeatable `--variable key=value` option stay strings. The CLI rejects conflicting sources and duplicate input keys before execution. For these execution commands, `--json` prints one final JSON result. `--jsonl` prints event lines followed by an `execution_summary` event. Choose one format. Exit code 1 means failure, invalid input, authentication failure, or an incomplete stream. Exit code 2 means the execution is waiting for input or approval. It isn't a success, and the CLI never approves or restarts the execution for you. `--no-input` turns off prompts, but it doesn't give consent. Delete, bulk-delete, revoke, and reset commands also require `--yes`. Implicit sign-in doesn't prompt when stdin is piped, so set up credentials yourself before you pipe data. Marathon and `agents task` have their own headless JSON mode and reject `--no-input`. To wait for an existing batch without submitting it again, run: **`Watch a batch`** ```bash title="Watch a batch" runtype batch status --watch --timeout 600000 --interval 2000 --json ``` Replace the following: * ``: the ID of the batch to watch. Watching works without a terminal. The default timeout is 300,000 ms and the default polling interval is 2,000 ms. With `--json`, the command prints only the final result or the wait error. A timeout stops only the local watcher, not the batch. Failed, cancelled, and partially failed batches exit with a nonzero code. ## Per-agent notes Onboard uses each coding agent's own MCP configuration and OAuth flow. Use the following notes when you need to complete OAuth or restart a specific coding agent. ### Claude Code Onboard writes a user-level MCP configuration entry that matches `claude mcp add --transport http --scope user runtype https://api.runtype.com/v1/mcp/protocol`. Run `claude mcp login runtype` to complete OAuth. Onboard installs Runtype agent skills in Claude Code's global skills directory. Start a new Claude Code session or reload MCP servers. ### Cursor Onboard writes the connection to Cursor's global MCP configuration. Run `cursor-agent mcp login runtype` to authorize it. Onboard installs Runtype agent skills for Cursor. Restart Cursor or start a new Cursor agent session. ### Codex Onboard configures the same server as `codex mcp add runtype --url https://api.runtype.com/v1/mcp/protocol`. Run `codex mcp login runtype` to complete OAuth. Onboard installs Runtype agent skills for Codex. Restart Codex or start a new Codex task. ### Gemini CLI Onboard adds a user-level server that matches `gemini mcp add --scope user --transport http runtype https://api.runtype.com/v1/mcp/protocol`. In Gemini CLI, run `/mcp auth runtype`, then `/mcp reload` to authorize and reload the connection. Onboard installs Runtype agent skills for Gemini CLI. ### OpenCode Onboard configures the same server as `opencode mcp add runtype --url https://api.runtype.com/v1/mcp/protocol`. Run `opencode mcp auth runtype` to authorize it. Onboard installs Runtype agent skills for OpenCode. Restart OpenCode or start a new OpenCode session. ### VS Code Onboard registers a user-level HTTP MCP server through the VS Code `code` shell command with `code --add-mcp`. On macOS, onboard finds the command in a VS Code install under `/Applications`. Otherwise, install the command first: in VS Code, open the Command Palette and run **Shell Command: Install 'code' command in PATH**. If the `code` command on your PATH belongs to Cursor, onboard stops. Install the VS Code shell command, then retry. Onboard installs Runtype agent skills for GitHub Copilot. Approve the browser OAuth prompt the first time a chat uses Runtype. Reload the VS Code window, then start a new chat. ## Troubleshoot setup The following table lists the messages that you might see when setup can't finish, and how to fix each one. | Message | Cause | Fix | | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | `Could not detect the current coding agent.` | Onboard found no supported coding agent. | Run `runtype onboard --agent `. | | `Several coding agents were detected` | More than one coding agent is installed, and the shell can't show a prompt. | Run `runtype onboard --agent ` for the agent you use. | | `CLI (...) is not on PATH.` | The coding agent's own CLI isn't installed or isn't on your PATH. | Install the coding agent's CLI or add it to your PATH, then run onboard again. | | `An MCP server named "runtype" already points somewhere else.` | An existing `runtype` entry uses another URL. | Run onboard again with `--force` to replace it. | | `OAuth did not complete` | The MCP sign-in was closed or failed. | Run the retry command that onboard prints, for example `claude mcp login runtype`. | | `The current project resolves an MCP server named "runtype" somewhere other than ...` | A project-level or local `runtype` entry overrides your user-level entry. | Remove or rename the project or local entry, then run onboard again. | | `This account has no workspace organization yet.` | Your account setup isn't finished. | Sign in to the dashboard to finish setup, then retry the MCP sign-in. | ## Use the machine-readable resources Use these machine-readable resources when you set up Runtype for someone else: * [Runtype agent instructions](https://runtype.ai/.well-known/agent.md): setup, authentication, and usage in one document. * [Runtype text index](https://runtype.ai/llms.txt): an index of the site in plain text. * [Runtype agent onboarding site](https://runtype.ai): returns its home page as markdown to agent user agents. For the default `runtype` connection, run `runtype onboard` instead of writing MCP configuration by hand. ## Work inside an existing codebase After setup, define agents and flows in your Runtype account or in your repository. Use hosted configuration when you want to edit definitions in the dashboard, version them there, and call them from your code through the dispatch API. Use the TypeScript SDK's `FlowBuilder` when you want definitions to ship with your code and go through review. Both options run on the same platform, and you can combine them. ## Next steps Continue with one of these guides: * [Runtype MCP server](/developer-guides/integrations/runtype-mcp-server): review the hosted server and call sequence. * [Quickstart](/developer-guides/getting-started/quickstart): make your first API call. * [Manage flows as code](/user-guide/flows/manage-flows-as-code): define flows with the TypeScript SDK. * [Agent skills](/user-guide/troubleshooting-faq/agent-skills): review installed skills and update them. * [Runtype CLI reference](/developer-guides/getting-started/cli-reference): install the `runtype` CLI and look up each command group.