Runtype MCP server

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:

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 a discovered API surface.

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. Use the instructions in this article for manual configuration.

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, 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. For non-interactive authentication, 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 instead of prompting for browser sign-in.

The extension runs a small local process that connects Claude Desktop’s stdio interface to the hosted server at https://api.runtype.com/v1/mcp/protocol. The same tools, authentication methods, and call sequence apply to this connection.

The standard server is available at https://api.runtype.com/v1/mcp/protocol and supports two authentication methods.

Browser OAuth is the default. Add the server without credentials with this Claude Code command:

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

API key authentication works when a browser is unavailable, such as with a headless coding agent or CI harness. Use any Runtype API key, including one obtained through agent self-registration:

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

For another MCP client, add the server with a bearer header using this configuration:

1
{
2
  "mcpServers": {
3
    "runtype": {
4
      "url": "https://api.runtype.com/v1/mcp/protocol",
5
      "headers": {
6
        "Authorization": "Bearer YOUR_API_KEY"
7
      }
8
    }
9
  }
10
}

Replace YOUR_API_KEY with your Runtype API key.

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:

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

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, pass an optional focus value of commerce, embed, subagents, skills, or search. Separate multiple values with commas. Without focus, the server summarizes those guides as fetch-on-demand documentation topics.
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.

Compact list responses

Standard MCP 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, and list_agent_executions.

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 preserve full representations when view is omitted. Their large collection endpoints accept view=compact, including agents, agent executions, flows, prompts, records, collections, products, Skills, Tools, Schedules, and context templates.

On GET /v1/agents/{id}/executions, view also controls finalOutput. With full, each row includes finalOutput. With compact, the response omits that field and previews long strings.

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:

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 available catalog resources are:

Run platform tools with execute_tool

To run a user or platform tool, pass its id exactly as list_tools returns it. The server uses the built-in tool executor and returns the same response 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:dalle, 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.

Chain platform tools from Code Mode

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

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

1
;(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 have no standalone executor.

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:

1
;async (runtype) => {
2
  const open = await runtype.executeTool('builtin:browser:open', {
3
    url: 'https://example.com',
4
    viewport: { width: 1440, height: 900 },
5
  })
6
  const sessionId = open.result.sessionId
7
  const shot = await runtype.executeTool('builtin:browser:session-screenshot', {
8
    sessionId,
9
    format: 'png',
10
    fullPage: false,
11
  })
12
  const media = shot.result.find((p) => p?.type === 'media')
13
  const asset = await runtype.executeTool('builtin:store_asset', {
14
    content: media.data,
15
    contentType: 'image/png',
16
    visibility: 'public',
17
    filename: 'page.png',
18
  })
19
  await runtype.executeTool('builtin:browser:close', { sessionId })
20
  return asset.result
21
}

Deploy sandboxes

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

A successful deploy_sandbox call returns a previewUrl that you can open immediately to view the running result. Call destroy_sandbox after you finish to free the container.

Preview URLs are temporary. Retention sets the maximum Runtype lifetime; provider sleep, deletion, or application failure can end availability earlier. This tool does not provide managed hosting or automatic recovery.

The optional retention field accepts 10m, 1h, 24h, or unlimited. Omitting it preserves the legacy Runtype Sandbox behavior: no retention deadline. The separate Daytona SDK/CLI deploy path retains its ten-minute default. Clients do not inject a retention value when you omit it.

Explicit retention and sleep settings on both providers require the organization’s lifecycle rollout flag. Before enablement, existing Runtype Sandbox calls remain untracked and the API rejects explicit lifecycle settings. After enablement, deploys register for metering and return effectivePolicy with the resolved retention, actual expiry, and metering: "active". Metering uses the existing sleep-aware billing model; unlimited does not mean free or always awake.

For the Runtype Sandbox rollout, omit sandboxId to create a tracked preview, then use the returned ID to redeploy. Reusing an untracked legacy ID returns 409 while the rollout is enabled; adoption requires a separate migration. If the rollout is disabled again, redeploying a tracked preview also returns 409 and its established expiry still applies. Destroy remains available. These checks prevent accidental deletion of legacy resources and incorrect reports of unlimited retention.

Use sleepPolicy: { "mode": "idle", "after": "15m" } to request idle sleep; supported intervals are 5m, 15m, 30m, and 1h. The legacy Runtype Sandbox deploy path rejects mode: "never". A redeploy renews retention once; reads and activity do not. Check effectivePolicy rather than assuming a preview will remain available for the requested retention.

Deploy example templates

Browse the Runtype 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:

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.

Both tools use the same quick-start import endpoints documented in Importing products. The result matches deploying the example from the dashboard.

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:

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, 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 enabled by default. The response includes each unified step_complete.result and the final execution_complete summary. Use these results to verify which steps the flow ran. Set streamResponse to true to receive events as they happen.

Next steps

Continue with one of these guides:

• MCP servers: connect Runtype to external MCP servers as flow tools
• Connecting to MCP clients: expose your product as an MCP Surface
• Working with tools: review the full tools overview