Connect Runtype to coding agents | Runtype Documentation

Run the following command to connect the coding agent in your current session to Runtype:

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.

What onboard does

The onboard command runs setup in the following order:

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.
Detect the coding agent. Onboard configures the coding agent that runs it. To choose one yourself, see Select a coding agent.
Configure MCP. Onboard writes a user-level MCP server entry named runtype that points to https://api.runtype.com/v1/mcp/protocol.
Authorize MCP. Onboard starts the coding agent’s MCP OAuth flow when the agent supports it. Otherwise, it prints the agent’s OAuth instruction.
Install skills. Onboard installs Runtype agent skills from the public runtypelabs/skills repository for the coding agent.
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

runtype onboard --agent <agent-id>

Replace the following:

<agent-id>: 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

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

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:

Run runtype auth register --email <email>.
Copy the 6-digit code from the verification email.
Run runtype auth verify <code>.
Run runtype onboard again.

To use an existing account:

Create an API key in the dashboard on Settings > API. For details, see Managing API keys.
In your own terminal, run runtype auth login --api-key <api-key>, or set the RUNTYPE_API_KEY environment variable.
Run runtype auth whoami --no-tty to confirm the sign-in.
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

runtype api-keys request --name <key-name> --scopes <scopes> --reason <reason>

Replace the following:

<key-name>: a name for the key, for example support-agent-dev.
<scopes>: a comma-separated scope list, for example FLOWS:READ,RECORDS:READ.
<reason>: 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

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

runtype --no-input --expect-api-url https://api.runtype.com --expect-org <org-id> \
  flows run <flow-id> --inputs '{"limit":5,"enabled":true}' --json

Replace the following:

<org-id>: the ID of your organization.
<flow-id>: 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 <org-id> or link the project with runtype link <org-id>. 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 <file>, and message arrays through --messages-file <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

runtype batch status <batch-id> --watch --timeout 600000 --interval 2000 --json

Replace the following:

<batch-id>: 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 <agent-id>`.
`Several coding agents were detected`	More than one coding agent is installed, and the shell can’t show a prompt.	Run `runtype onboard --agent <agent-id>` 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: setup, authentication, and usage in one document.
Runtype text index: an index of the site in plain text.
Runtype agent onboarding site: 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: review the hosted server and call sequence.
Quickstart: make your first API call.
Manage flows as code: define flows with the TypeScript SDK.
Agent skills: review installed skills and update them.
Runtype CLI reference: install the runtype CLI and look up each command group.