> 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.

# Runtype MCP server

> Build and manage Runtype products, flows, agents, and tools from any MCP client

Runtype hosts a Model Context Protocol (MCP) server that lets an AI client build and manage your Runtype account. You can create products, design and run flows, configure Surfaces, embed Persona chat widgets, and manage Agents, Records, logs, and runtime Tools. The client connects to Runtype instead of connecting Runtype to an external MCP server.

## Distinguish the MCP features

Runtype supports MCP in three directions. Use the following table to distinguish these features:

| Feature                                                                              | Direction                  | Description                                                                                      |
| ------------------------------------------------------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------ |
| **Runtype MCP server**                                                               | MCP client to Runtype      | A hosted server that your AI client uses to build and manage Runtype resources                   |
| [MCP servers](/developer-guides/integrations/mcp-servers)                            | Runtype to external        | Connect Runtype to external MCP servers so flows can call their tools, such as `mcp:server:tool` |
| [Connecting to MCP clients](/user-guide/products-surfaces/connecting-to-mcp-clients) | MCP client to your product | Expose your Runtype product as an MCP Surface for end users to call                              |

## Choose an MCP server

Choose the server that matches how your client discovers and runs tools. The two options are:

* **Standard MCP server**: Exposes one tool per operation, such as `create_flow`, `list_records`, and `execute_tool`. Choose it when your client browses a flat tool list and calls tools by name.
* **Code Mode MCP server**: Exposes a `search` and `execute` pair that runs JavaScript against the Runtype API. Choose it when your client writes code against the Runtype API instead of calling one tool per operation.

The following table lists the endpoint for each server:

| Server               | Endpoint                                  |
| -------------------- | ----------------------------------------- |
| Standard MCP server  | `https://api.runtype.com/v1/mcp/protocol` |
| Code Mode MCP server | `https://code.runtype.com/mcp`            |

Both servers send instructions when the client connects. These instructions describe the recommended call sequence.

## Connect to the server

Run `npx -y @runtypelabs/cli@latest onboard` to connect Claude Code, Cursor, Codex, Gemini CLI, OpenCode, or VS Code and install the Runtype agent skills. For automated setup details, see [Connect Runtype to coding agents](/developer-guides/integrations/connect-coding-agents). Use the instructions in this section for manual configuration.

Both servers support two authentication methods:

* **Browser sign-in**: The default. Add the server without credentials. The first connection opens a browser window where you sign in to Runtype.
* **API key authentication**: Send a Runtype API key as a bearer token. Use it when a browser is unavailable, such as with a headless coding agent or a CI job. Any Runtype API key works, including one obtained through [agent self-registration](/developer-guides/getting-started/authentication).

### Install Runtype in Claude Desktop

Claude Desktop installs Runtype as a bundled extension, so you don't edit a configuration file.

To install the extension in Claude Desktop, follow these steps:

1. Download **[Runtype for Claude Desktop](https://www.runtype.com/runtype.mcpb)**, a `.mcpb` bundle that is about 1 MB.
2. Double-click the downloaded file or drag it to **Settings > Extensions** in Claude Desktop. Confirm the installation.
3. Start a conversation and ask Claude to use Runtype, such as "list my Runtype products". The first tool call opens a browser window where you can sign in or sign up for your Runtype account.

Claude Desktop stores the sign-in, so the browser prompt appears only on first use. To authenticate without a browser, open the extension settings and paste a Runtype API key into the optional **Runtype API key** field. The extension stores the key in your operating system keychain and sends it as a bearer token.

The extension connects Claude Desktop to the standard MCP server. The same tools, authentication methods, and call sequence apply to this connection.

### Connect Claude Code

To add the standard MCP server with browser sign-in, run this command:

**`Claude Code`**

```bash title="Claude Code"
claude mcp add --transport http runtype https://api.runtype.com/v1/mcp/protocol
```

To add the standard MCP server with an API key, run this command:

**`Claude Code`**

```bash title="Claude Code"
claude mcp add --transport http runtype https://api.runtype.com/v1/mcp/protocol \
  --header "Authorization: Bearer YOUR_API_KEY"
```

Replace `YOUR_API_KEY` with your Runtype API key.

### Connect another MCP client

To add the standard MCP server to another MCP client with an API key, use this configuration:

**`Generic MCP config`**

```json title="Generic MCP config"
{
  "mcpServers": {
    "runtype": {
      "url": "https://api.runtype.com/v1/mcp/protocol",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

Replace `YOUR_API_KEY` with your Runtype API key. To use browser sign-in instead, omit the `headers` object.

### Connect to the Code Mode server

The Code Mode MCP server supports the same authentication methods as the standard MCP server. To add it to Claude Code with browser sign-in, run this command:

**`Claude Code`**

```bash title="Claude Code"
claude mcp add --transport http runtype-code https://code.runtype.com/mcp
```

To add it to another MCP client with an API key, use this configuration:

**`Generic MCP config`**

```json title="Generic MCP config"
{
  "mcpServers": {
    "runtype-code": {
      "url": "https://code.runtype.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

Replace `YOUR_API_KEY` with your Runtype API key. To use browser sign-in instead, omit the `headers` object.

### Verify the connection

To confirm that the client reaches the organization you expect, ask the client to call the `get_me` tool on the standard MCP server. The tool returns your user ID, organization ID, and email address. From a terminal, you can run `runtype mcp call get_me --json` instead.

### How browser sign-in works

When you sign in through the browser, Runtype creates an API key for your client in the organization that is active in your dashboard session. The key has the following properties:

* It's named `MCP Client (CLIENT_ID)`, where `CLIENT_ID` is the ID that your client registered.
* It has broad permissions to build and manage resources in that organization.
* It expires after 90 days. The server doesn't refresh it, so you sign in again after it expires.

To revoke a client's access, delete its key on **Settings > API**. For more information, see [Managing API keys](/user-guide/settings/managing-api-keys).

### Call MCP from the Runtype CLI

The `runtype` CLI discovers and invokes either hosted server directly. You don't need to register an MCP client or wait for individual tool commands to be added to the CLI.

Use these commands to discover, inspect, and call tools:

```bash
# Standard MCP (default)
runtype mcp tools
runtype mcp inspect create_flow
runtype mcp call list_flows -F limit=20 --json

# Code Mode MCP
runtype mcp tools --server code
runtype mcp call execute --server code -F code=@query.js --json

# Complete arguments object from a file or stdin
runtype mcp call create_flow --input arguments.json --json
cat arguments.json | runtype mcp call create_flow --input - --json
```

Use `-f key=value` for string values and `-F key=value` for JSON-typed values. With `-F`, prefix a file path with `@` or use `@-` for stdin. Use `--json-body` for a complete inline arguments object. Use `--json` to preserve the complete MCP result for scripts.

Calls wait up to 930 seconds by default. Pass `--timeout <ms>` to set another positive millisecond deadline. Replace `<ms>` with the timeout in milliseconds.

Before you use `--input -` or `-F key=@-`, run `runtype auth login` or set `RUNTYPE_API_KEY`. The CLI doesn't prompt interactively when the stream contains tool arguments.

The command uses your CLI API key and follows `--api-url`. For local or custom deployments, set `RUNTYPE_MCP_URL` or `RUNTYPE_CODE_MCP_URL` to override the inferred endpoint. The `runtype mcp` commands call the Runtype protocol servers. Use the separate `runtype tools` command to manage runtime Tools saved in your Runtype account.

## Troubleshoot the connection

The following table lists common connection errors and how to fix them:

| Symptom                                          | Cause                                                                                   | Fix                                                                           |
| ------------------------------------------------ | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `Authorization required` (HTTP 401)              | The API key is invalid, deleted, or expired. Browser sign-in keys expire after 90 days. | Reconnect the server in your client to sign in again, or replace the API key. |
| `Permission denied` (HTTP 403)                   | The API key doesn't have the permission that the tool needs.                            | Edit the key's permissions or use a key with broader permissions.             |
| `This account has no workspace organization yet` | Your account has no organization that can own the key.                                  | Sign in to the dashboard to finish setup, then retry.                         |
| `too_many_requests` (HTTP 429) during sign-in    | Your network registered too many clients in a short time.                               | Wait 60 seconds, then retry.                                                  |

For more help with keys and sign-in, see [Authentication issues](/user-guide/troubleshooting-faq/authentication-issues).

## Recommended call sequence

Follow this sequence with either server:

1. **Call `get_build_instructions` before any `create_*` mutation.** Pass a `task` value of `build-product`, `generate-flow`, or `explain-capabilities`. The tool returns platform rules, schemas, step types, and variable-system guidance for that task. For `build-product`, you can pass these optional parameters:
   * `focus`: One or more of `commerce`, `embed`, `embed-fullscreen`, `subagents`, `skills`, `search`, `retrieval`, `operational-design`, `agent-design`, and `prompt-authoring`, separated by commas. The response includes the full guide for each area. Without `focus`, the response lists those guides as topics to fetch when needed.
   * `template`: A starting hint of `support-agent`, `webhook-router`, `slack-bot`, or `data-pipeline`. To deploy a complete product instead, see [Deploy example templates](#deploy-example-templates).
2. **Use `get_platform_documentation` for deterministic lookups and `search_documentation` for prose questions.** `get_platform_documentation` serves exact schema, type-definition, tool-catalog, embed, SDK, and dashboard-link references on demand. `search_documentation` searches the published docs corpus and returns a synthesized answer with citations. Use it for "how do I..." and "what is..." questions. Use `get_platform_documentation` when you need an exact contract.
3. **Call `list_tools` to discover tools.** Run user and platform tools with `execute_tool`, or attach configured integration tool IDs to an Agent or prompt step through `tools.toolIds`.
4. **Report problems with `submit_feedback`.** When an API call fails unexpectedly, a tool behaves in a confusing way, or a doc page is wrong, call `submit_feedback` with a `category` (`api`, `mcp`, `documentation`, `sdk`, `cli`, `dashboard`, or `other`), a short `note`, and the affected `request_id` or `url`. Any API key can submit, and the call costs no credits. The tool returns a receipt ID. Runtype redacts values that look like secrets, but do not include secrets in the note. The same endpoint is available over REST as `POST /v1/agent-feedback`.
5. **Delegate multi-step work with `delegate_to_runtype`** (accounts with the delegation feature). Describe the goal and the acceptance check once; Runtype's own operator agent runs in the cloud inside your account, reads the build instructions itself, validates before it mutates, test-runs what it built, and returns a digest with ids and dashboard links. Progress streams while you wait (`wait_seconds`, up to 240). If it is still running, poll with `check_delegation`; if it asks a question (`status: input_required`), answer by calling `delegate_to_runtype` again with the same `task_id`. Destructive operations need `allow_destructive: true`. The same capability is available over REST as `POST /v1/delegate-tasks`.

> **Note**
>
> On the Code Mode server, call `search` to list API methods grouped by category. Inspect a method
> for its signature, then call `execute`. Call `get_build_instructions` before you build or design
> anything.

The standard MCP server also offers this guidance as MCP prompts, which many clients show as slash commands. The prompts are `build-product`, `generate-flow`, `explain-capabilities`, and `generate-proposal`. For one task, use either a prompt or the `get_build_instructions` tool, not both.

## What the server can do

The standard MCP server has more than 200 tools. To see the full list, call `tools/list` from your client or run `runtype mcp tools`. The following table groups common tools by area:

| Area                         | Example tools                                                                                   | More information                                                                                  |
| ---------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Products, flows, and Agents  | `create_product`, `create_flow`, `create_agent`, `validate_flow`                                | [What are Agents?](/user-guide/agents/what-are-agents)                                            |
| Test runs                    | `execute_agent`, `run_flow`, `dispatch`, `get_execution_status`                                 | [Debugging flows](/user-guide/flows/debugging-flows)                                              |
| Versions and release aliases | `publish_flow_version`, `publish_agent_version`, `activate_agent_alias`, `rollback_agent_alias` | [Agent versioning and publishing](/user-guide/agents/agent-versioning-and-publishing)             |
| Evals and batches            | `create_eval_suite`, `run_eval_suite`, `submit_batch`, `get_batch_status`                       | [What are Evals?](/user-guide/evals/what-are-evals)                                               |
| Logs and traces              | `list_logs`, `get_log_stats`, `trace_execution`, `list_runs`                                    | [Working with logs](/user-guide/logs/working-with-logs)                                           |
| Trace signals                | `create_signal_set`, `preview_signal_set`, `bind_signal_set`, `get_signal_stats`                | [Read signals out of every agent turn](/developer-guides/guides/trace-signals)                    |
| Schedules                    | `list_schedules`, `create_schedule`, `run_schedule_now`                                         | [What are Schedules?](/user-guide/schedules/what-are-schedules)                                   |
| Secrets                      | `get_secret_intake_manifest`, `check_secrets`, `create_secret`                                  | [Provide secrets without pasting them into chat](#provide-secrets-without-pasting-them-into-chat) |
| Models and provider keys     | `list_model_configs`, `set_default_model_config`, `create_provider_key`                         | [Managing AI models](/user-guide/settings/managing-ai-models)                                     |
| Conversations and messaging  | `list_conversations`, `takeover_messaging_conversation`, `send_messaging_message`               | None                                                                                              |
| Skills                       | `list_skills`, `create_skill`, `bind_skill`                                                     | [Agent Skills](/user-guide/agents/agent-skills)                                                   |
| Question sets                | `create_question_set`, `publish_question_set_version`                                           | [Judgments](/user-guide/flows/judgments)                                                          |
| Surfaces and embeds          | `create_client_token`, `generate_persona_embed_code`, `install_slack_integration`               | None                                                                                              |
| Product events               | `list_event_types`, `poll_events`, `wait_for_event`                                             | [Watch product events](#watch-product-events)                                                     |

## Compact list responses

The standard MCP server keeps discovery responses bounded. The following tools use `view: "compact"` by default: `list_products`, `list_agents`, `list_flows`, `list_tools`, `list_records`, `list_collections`, `list_skills`, `list_schedules`, `list_agent_executions`, and `list_runs`. The `list_agent_executions` tool is deprecated. To list an Agent's runs, call `list_runs` with `agent_id` instead.

Compact responses retain the normal row shape. They shorten strings longer than 100 Unicode characters and append `…`. Call the matching `get_*` tool to retrieve complete values for one resource. Pass `view: "full"` when you need complete values across a page.

REST and Code Mode responses return full values when you omit `view`. To request compact rows, pass `view=compact` to a large collection endpoint, such as the endpoints that list Agents, flows, Records, Tools, or runs. For the fields that a compact run row omits, see [List runs](/api-reference/runtype-api/runs/list-runs).

## Nested runs fold under their parent

By default, `list_runs` returns root runs only. A run that another run started, such as a subagent run or a nested flow, appears under its parent instead of as its own row. One Agent run that started three subagents is one row, not four.

The following fields and parameters control how child runs appear:

* `childCount` on each row is the number of runs that name that row as their parent. A value of `0` means the run has no children.
* `parent_execution_id` returns the child runs of one parent.
* `include_children: true` lists child runs beside their parents.
* A filter that names a resource, such as `agent_id`, `flow_id`, `conversation_id`, or `execution_id`, returns every matching run, child runs included.

## Discover tools with `list_tools`

`list_tools` returns your user-defined Tools, configured integration tools, and custom MCP server registrations by default. It also returns a `builtinToolsAvailable` summary that groups the 100+ built-in platform tools by category. The summary shows available tools without returning every built-in tool at once.

The summary groups built-in tools as follows:

* **Small categories**: The response inlines each tool's `id`, `name`, and `description` for `data_management`, `file_operations`, `image_generation`, `knowledge_retrieval`, `temporal`, `web_scraping`, and `web_search`.
* **Large categories**: The response keeps `commerce` and `third_party_api` collapsed with a count and a drill-down hint. For `third_party_api`, the summary also shows the top vendors.

Every returned tool carries a `source` field. Its value is `user`, `builtin`, `integration`, or `mcp-server`:

* Pass `user` and `builtin` IDs to `execute_tool` without changing them.
* Attach `integration` IDs to an Agent or prompt step through `tools.toolIds`. The catalog includes only integrations configured for the account.
* An `mcp-server` row is a server registration. Its tools use `mcp:<serverName>:<toolName>` references after runtime discovery.

### Parameters

Use the following table to choose `list_tools` parameters:

| Parameter        | Type                                                                                            | Default     | Description                                                                |
| ---------------- | ----------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------- |
| `source`         | `"user"` \| `"builtin"` \| `"integration"` \| `"mcp-server"` \| `"all"`                         | `"user"`    | Select the catalog to return                                               |
| `limit`          | number                                                                                          | `50`        | Limit the number of user tools. The maximum is 200.                        |
| `tool_type`      | `"flow"` \| `"custom"` \| `"external"` \| `"graphql"` \| `"mcp"` \| `"local"` \| `"mcp-server"` | Not set     | Filter user tools by type. Ignored when `source` is `"builtin"`.           |
| `active_only`    | boolean                                                                                         | Not set     | Return only active user tools.                                             |
| `category`       | string                                                                                          | Not set     | Filter built-in tools by category                                          |
| `full`           | boolean                                                                                         | `false`     | Return every built-in tool at once. This does not control string previews. |
| `view`           | `"compact"` \| `"full"`                                                                         | `"compact"` | Shorten strings to 100-character previews or preserve complete values      |
| `include_schema` | boolean                                                                                         | `false`     | Inline each tool's `parametersSchema` for execution or tool configuration  |

### Deeper catalogs

The `builtinToolsAvailable` summary also includes a `seeAlso` array of resource URIs. Fetch these resources with `resources/read` for fuller documentation than the inline summary provides.

The following table lists the catalog resources and other commonly used resources:

| Resource URI                               | Contents                     |
| ------------------------------------------ | ---------------------------- |
| `runtype://catalog/builtin-tools`          | Full built-in tool catalog   |
| `runtype://catalog/orthogonal-tools`       | Orthogonal vendor API tools  |
| `runtype://catalog/ucp-commerce`           | Commerce tools               |
| `runtype://catalog/provider-native-search` | Provider-native search tools |
| `runtype://catalog/models`                 | Available models             |
| `runtype://catalog/limits`                 | Platform limits              |
| `runtype://guide/validation-errors`        | Fixes for validation errors  |
| `runtype://catalog/persona-embed`          | Persona embed guide          |

To see every resource, call `resources/list` from your client.

## Run platform tools with `execute_tool`

To run a user or platform tool, pass its `id` exactly as `list_tools` returns it. The response has the same shape as a user Tool execution. Integration tools use `builtin:INTEGRATION:TOOL_NAME` IDs, but those IDs are attached through `tools.toolIds` rather than passed to `execute_tool`.

Platform tool IDs use one of the following forms:

* `builtin:TOOL_NAME`: For example, `builtin:firecrawl`, `builtin:gpt-image-2-5`, or `builtin:exa`. Replace `TOOL_NAME` with the built-in tool name.
* `platform:orthogonal:VENDOR:TOOL_NAME`: For example, `platform:orthogonal:apollo:people_match`. Replace `VENDOR` and `TOOL_NAME` with the returned vendor and tool values.

> **Tip**
>
> Call `list_tools` with `include_schema: true` to inline each tool's `parametersSchema`. The client
> then has the expected arguments for `execute_tool` without a second lookup.

A configurable built-in tool takes its instance settings in `tool_config`, the same settings an Agent's `toolConfigs` entry carries. The server checks `tool_config` against the tool's configuration fields. `tool_config` applies only to `builtin:` and `platform:` tools, and a user-defined Tool rejects it. For example, to run `builtin:decision_judge` against a published question set:

**`execute_tool arguments`**

```json title="execute_tool arguments"
{
  "tool_id": "builtin:decision_judge",
  "parameters": { "state": "My card was charged twice for the same order." },
  "tool_config": { "questionSetId": "qset_YOUR_QUESTION_SET_ID", "version": 1 }
}
```

Replace `qset_YOUR_QUESTION_SET_ID` with your question set's ID. A built-in result can also carry an optional `metadata` object for the caller. A judgment reports its resolved model, key source, token usage, and estimated cost in `metadata.judgment`. For the fields, see [Call a configured instance over REST](/user-guide/flows/judgments#call-a-configured-instance-over-rest).

## Chain platform tools from Code Mode

On the Code Mode server, the same catalog is reachable from inside `execute` as `runtype.executeTool(toolId, parameters, toolConfig?)`. The method also accepts an object, `runtype.executeTool({ toolId, parameters, toolConfig })`, and returns `{ toolId, toolName, result, metadata? }`.

The optional `toolConfig` carries a configurable built-in tool's instance settings. For example, to ask a published question set about some state:

```js
;async (runtype) => {
  const judged = await runtype.executeTool(
    'builtin:decision_judge',
    { state: 'My card was charged twice for the same order.' },
    { questionSetId: 'qset_YOUR_QUESTION_SET_ID', version: 1 }
  )
  return { answers: judged.result, model: judged.metadata?.judgment?.resolvedModelId }
}
```

`result` holds the answers, and `metadata.judgment` reports how the judgment ran. For the fields, see [Call a configured instance over REST](/user-guide/flows/judgments#call-a-configured-instance-over-rest).

Built-in tools don't appear in `spec.methods`. Discover them with `search`:

```js
;(spec) => spec.builtinTools.filter((t) => /asset|screenshot/i.test(t.toolId + t.name))
```

Each entry is `{ toolId, name, category }`. Provider-executed tools, such as native web search, aren't listed because they attach to a prompt step through `tools.toolIds` and can't run on their own.

Several `executeTool` calls inside one `execute` invocation run server-side, so intermediate values stay in the sandbox and never enter the model's context. Use this when one tool's output is large or binary and feeds another tool. For example, to screenshot a page and host the PNG:

```js
;async (runtype) => {
  const open = await runtype.executeTool('builtin:browser:open', {
    url: 'https://example.com',
    viewport: { width: 1440, height: 900 },
  })
  const sessionId = open.result.sessionId
  const shot = await runtype.executeTool('builtin:browser:session-screenshot', {
    sessionId,
    format: 'png',
    fullPage: false,
  })
  const media = shot.result.find((p) => p?.type === 'media')
  const asset = await runtype.executeTool('builtin:store_asset', {
    content: media.data,
    contentType: 'image/png',
    visibility: 'public',
    filename: 'page.png',
  })
  await runtype.executeTool('builtin:browser:close', { sessionId })
  return asset.result
}
```

> **Note**
>
> To chain tools the same way inside a deployed flow or Agent, set
> `config.tools.codeModeConfig.toolPool` on a prompt step or Agent. The standard MCP server's
> `execute_tool` reaches the same catalog one call per hop, and each result passes through the
> model. A media result carries a `runtype-asset://` handle,
> so the next hop takes the bytes by reference: pass the handle as `url` to `store_asset` or
> `publish_page`, or in any parameter declared `contentEncoding: "base64"`, and the bytes are never
> re-emitted by the model. Use Code Mode when the chain needs logic between hops.

## Deploy sandboxes

Use these tools to manage the lifecycle of Runtype Sandbox containers:

| Tool              | Description                                                                             |
| ----------------- | --------------------------------------------------------------------------------------- |
| `deploy_sandbox`  | Deploys code to a Runtype Sandbox container and returns its `sandboxId` and preview URL |
| `destroy_sandbox` | Tears down a sandbox by its `sandboxId`                                                 |

A successful `deploy_sandbox` call returns a `previewUrl` that you can open immediately to view the running result. To update the running code, call `deploy_sandbox` again with the returned `sandboxId`. Call `destroy_sandbox` after you finish to free the container.

Preview URLs are temporary. The container can sleep, be removed, or stop when the application fails. Use a preview to check a result, not to host an application.

## Deploy example templates

Browse the [Runtype examples](https://runtype.com/examples). Use these tools to restore a complete product in your account by its example slug. The slug matches the identifier that the dashboard deploy page uses in `/now?example=EXAMPLE_SLUG`.

The example tools are:

| Tool                          | Description                                                                                                                                                                                                                                                                             |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_example_templates`      | Lists published example templates with their slugs, titles, descriptions, capability and Surface summaries, and variable specifications. Pass `include_drafts: true` to include unpublished drafts.                                                                                     |
| `create_product_from_example` | Creates a product from exactly one of `slug`, `session`, or `url`. It resolves the document with the supplied `variables`, uses template defaults for remaining values, and assembles the product with its flows, Agents, Tools, and Surfaces. Draft slugs require `allow_draft: true`. |

`create_product_from_example` accepts these identifiers:

* `slug`: Identify a first-party example with `/now?example=EXAMPLE_SLUG` or `runtype.com/examples/EXAMPLE_SLUG`.
* `session`: Identify a shared session with `/now?session=SESSION_ID`. The server resolves it to that session's hosted FPO document.
* `url`: Provide a pasted link. Supported links include dashboard `/now` links with `example`, `session`, `templateUrl`, or `from` parameters. These links can include `templateParam:VARIABLE_KEY` values, where `VARIABLE_KEY` is a template variable key. You can also provide example pages or direct HTTPS URLs to an FPO, FPO template, or A2A agent card.

To deploy an example, call `list_example_templates` first. Then call `create_product_from_example` with the chosen identifier. If required variable values are missing, the tool creates nothing. The response includes `created: false`, the missing variable keys, and the full variable specifications. Call the tool again with a complete `variables` object.

> **Tip**
>
> After `create_product_from_example` succeeds, call `get_product_configuration` with the returned product ID. It reports pending secrets that the example needs and returns a dashboard URL where a person can fill them in securely.
>
> For a complete readiness report, call `get_product_setup` instead. It combines pending secrets with each Surface's remaining installation steps. Each step names a fulfillment method. It can be an MCP tool, a REST call from a coding harness, or a dashboard link when a browser is required. Use `get_surface_setup` to check one Surface, such as a Slack Surface that still needs OAuth installation.

Both tools use the same quick-start import endpoints documented in [Importing products](/developer-guides/guides/importing-products). The result matches deploying the example from the dashboard.

## Provide secrets without pasting them into chat

Most products need API keys or other credentials before they go live. Keep those values out of the conversation, because the client sends everything in the chat to the model. Use the following tools instead:

| Tool                         | Description                                                                                                                     |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `get_secret_intake_manifest` | Lists the secrets that need values and returns a dashboard URL where a person enters them                                       |
| `check_secrets`              | Reports which keys in a list exist, are missing, or are revoked                                                                 |
| `create_secret`              | Registers a secret. Omit `value` to create a pending secret that a person fills in through the dashboard                        |
| `submit_secret_intake`       | Submits secret values in a batch. Use it only for values from a trusted source outside the chat, such as a vault or a CI secret |

To enter the values, open the dashboard URL from `get_secret_intake_manifest` in a browser. The values that you enter there don't appear in the conversation. Flows and Agents reference a secret as `{{secret:KEY}}`. For more information, see [Managing secrets](/user-guide/settings/managing-secrets).

## Manage record collections

Eight tools manage record collections. A collection registers a record type and can include a metadata schema. Runtype validates each record write according to the collection's validation mode: `off`, `warn`, or `enforce`.

Use the following table to review the collection tools:

| Tool                          | Description                                                                                                                                                                                                                                            |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `list_collections`            | Lists collections with cursor pagination. Pass `include_count: true` to add per-collection record counts. Responses use compact string previews by default. Pass `view: "full"` for complete values.                                                   |
| `get_collection`              | Fetches a collection by slug. Pass `include_history: true` to include the schema version history.                                                                                                                                                      |
| `create_collection`           | Registers a record type as a collection. `validation_mode` defaults to `off`, so creation doesn't change existing behavior.                                                                                                                            |
| `update_collection`           | Updates display fields, the schema, or the validation mode. Breaking schema changes are rejected when the resulting mode is `enforce`. Switching to `enforce` returns an `enforceCheck` dry-run summary.                                               |
| `delete_collection`           | Deletes the registration only. Records of the type remain unchanged.                                                                                                                                                                                   |
| `infer_collection_schema`     | Samples existing records and proposes a schema with per-field confidence. It saves nothing. Persist the proposal with `update_collection`.                                                                                                             |
| `validate_collection_records` | Dry-runs existing records against the saved schema or a proposed schema. It reports how many records would fail and includes examples. It writes nothing.                                                                                              |
| `get_collection_types`        | Generates TypeScript declarations for every schematized collection. It returns one interface for each collection, a `declare module '@runtypelabs/sdk'` augmentation, and the `.d.ts` text. `client.records.from(slug)` can then type record metadata. |

Use this adoption pattern: create a collection, infer a schema, save it in `warn` mode, dry-run with `validate_collection_records`, and switch to `enforce` after existing records conform. For the full walkthrough, see [Defining a schema](/user-guide/records/defining-a-schema), which includes REST, SDK, and CLI equivalents.

After you add a schema, the `runtype://records/collections` MCP resource lists each collection's slug, display name, validation mode, and full schema. The `runtype_record_upsert`, `runtype_record_get`, and `runtype_record_list` tools include the same field information in their descriptions. The annotations list each field's name, type, and required status for every schematized collection.

## Run flows with `dispatch`

When you call `dispatch` through the MCP server, debug mode is on by default. The response includes each `step_complete.result` and the final `execution_complete` summary. Use these results to verify which steps the flow ran. To turn debug mode off, set `options.debugMode` to `false`. To receive events as they happen, set `options.streamResponse` to `true`.

For work that can take longer than the client's request timeout, pass `async: true`. The tool returns an execution ID right away. Poll it with `get_execution_status`.

To run a saved flow with input variables, use `run_flow`, which takes fewer parameters than `dispatch`. To test a conversational Agent, use `execute_agent`.

## Watch product events

The server reads your organization's product events, so a client can react when something needs attention. The event types are `runtype.execution.failed`, `runtype.approval.requested`, `runtype.schedule.run_failed`, `runtype.eval.run_completed`, `runtype.conversation.human_takeover`, `runtype.skill.proposal_created`, `runtype.task.input_required`, `runtype.task.completed`, `runtype.task.failed`, `runtype.task.cancelled`, `runtype.signal.fired`, and `runtype.signal.cluster_appeared`. A failed execution event also covers an interrupted run. To wait on a `delegate_to_runtype` task, call `wait_for_event` with `name` set to a task event and `arguments` set to `{ taskId }`, then read the result with `check_delegation`. Each call watches one event type; to wake on any task outcome, run `runtype events watch --task TASK_ID`, which reads every type. For what each event carries, see [Watch product events](/developer-guides/guides/watch-product-events).

Use the following tools to read events:

| Tool               | Description                                                                                                                                           |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_event_types` | Lists each event type with its filter arguments (`inputSchema`) and the shape of its `data` (`payloadSchema`).                                        |
| `poll_events`      | Returns the events of one type after a cursor, oldest first, and returns at once. Accepts `max_events` (up to 200) and `max_age_ms`.                  |
| `wait_for_event`   | Works like `poll_events` but holds the call open until a matching event arrives or `wait_ms` ends. `wait_ms` defaults to 50000, which is the maximum. |

Both poll tools take a `name`, a `cursor`, and an `arguments` object with the event's filters, such as `{ "agentId": "YOUR_AGENT_ID" }`. A filter that the event type doesn't accept returns an error.

To watch for events without gaps, follow these steps:

1. Call `wait_for_event` without `cursor`. The call starts from now, returns no backlog, and returns the current cursor.
2. Call `wait_for_event` again with the returned `cursor`. The call returns when a matching event arrives, or with an empty `events` list after 50 seconds.
3. Store the `cursor` from every response, including a response with no events, and pass it on the next call.
4. If `hasMore` is `true`, call again right away to read the remaining events. With `poll_events`, wait `nextPollMs` milliseconds between calls otherwise.

The log keeps events for 7 days. If `truncated` is `true`, your cursor was older than the oldest retained event, and the events in between were skipped.

A host that supports the draft MCP Events extension can call the `events/list` and `events/poll` methods instead of the tools. The server advertises the extension both as `events: {}` and as `extensions["io.modelcontextprotocol/events"]` in its capabilities. `events/poll` takes `name`, `arguments`, `cursor`, `maxEvents`, and `maxAgeMs`, and returns the same result as `poll_events`.

On the Code Mode server, call `runtype.listEventTypes()` and `runtype.pollEvents(params)` inside `execute`. `pollEvents` takes `name`, `arguments`, `cursor`, `maxEvents`, `maxAgeMs`, and `waitMs`. Omit `name` to read every event type. `waitMs` defaults to `0` and must stay under the `execute` timeout, which is 60 seconds by default.

## Next steps

Continue with one of these guides:

* [MCP servers](/developer-guides/integrations/mcp-servers): connect Runtype to external MCP servers as flow tools
* [Connecting to MCP clients](/user-guide/products-surfaces/connecting-to-mcp-clients): expose your product as an MCP Surface
* [Working with tools](/developer-guides/guides/working-with-tools): review the full tools overview
* [Connect Runtype to coding agents](/developer-guides/integrations/connect-coding-agents): set up the server automatically with the `runtype` CLI
* [Managing API keys](/user-guide/settings/managing-api-keys): create, scope, and revoke the keys that the server uses
* [Managing secrets](/user-guide/settings/managing-secrets): store the credentials that your products need
* [Deploy a sandbox preview](/developer-guides/guides/sandbox-deployments): deploy, redeploy, and destroy a sandbox preview
* [Taking over messaging conversations](/user-guide/products-surfaces/taking-over-conversations): take over a conversation from the Agent and hand it back