Integrations

Runtype MCP server

Runtype hosts an MCP server that lets an AI client — Claude Code, Cursor, Claude Desktop, or any MCP-compatible app — build and operate your Runtype account through tools. From the client you can create products, design and run flows, configure surfaces, embed Persona chat widgets, and manage agents, records, logs, and runtime tools. This is the opposite direction from connecting Runtype to external MCP servers: here, an AI client connects to Runtype.

How it differs from the other MCP features

Runtype touches MCP in three distinct ways. Don’t confuse them — each is a different server in a different direction.

FeatureDirectionWhat it is
Runtype MCP server (this page)Client → RuntypeA hosted server your AI client connects to in order to build and manage Runtype resources
MCP serversRuntype → externalConnect Runtype to external MCP servers so flows can call their tools (mcp:server:tool IDs)
Connecting to MCP clientsClient → your productExpose your own Runtype product as an MCP Surface for end users to call

Two server flavors

Runtype offers two MCP servers over the same account. Pick the one that matches how your client discovers and runs tools.

  • Standard MCP server — one tool per operation (create_flow, list_records, execute_tool, and so on). Best for clients that browse a flat tool list and call tools by name.
  • Code Mode MCP server — a search / execute pair that runs JavaScript against the Runtype API. Best for clients that prefer to write code against a discovered API surface rather than call many individual tools.

Both servers transmit a set of instructions to the client on connection that describe the recommended call sequence below.

Connecting

Using a coding agent such as Claude Code, Cursor, Codex, Gemini CLI, OpenCode, or VS Code? Run npx -y @runtypelabs/cli@latest onboard to set up this connection (plus the Runtype agent skills) in one command: see Connect Runtype to coding agents. The rest of this section covers manual configuration.

The standard server lives at https://api.runtype.com/v1/mcp/protocol and accepts two forms of authentication.

Browser OAuth is the default. Add the server with no credentials and the MCP client prompts you to sign in (or sign up) in the browser on first use:

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

API key as a bearer header works when a browser is not available, for example a headless coding agent or CI harness. Any Runtype API key works here, including a key obtained through agent self-registration:

Claude Code
$claude mcp add --transport http runtype https://api.runtype.com/v1/mcp/protocol \
>  --header "Authorization: Bearer YOUR_API_KEY"
Generic MCP config
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}

Calling MCP from the Runtype CLI

The Runtype CLI can discover and invoke either hosted server directly, without registering an MCP client or waiting for individual tool commands to be added to the CLI:

$# 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 the value with @ to read a file or use @- for stdin. --json-body accepts a complete inline arguments object, while --json preserves the complete MCP result for scripts. Calls wait up to 930 seconds by default; pass --timeout <ms> to choose another positive millisecond deadline. Run runtype auth login first or set RUNTYPE_API_KEY before using --input - or -F key=@-; the CLI does not put an interactive login prompt on a stream that contains tool arguments.

The command uses your CLI API key and follows --api-url. For local or custom deployments, RUNTYPE_MCP_URL and RUNTYPE_CODE_MCP_URL override the inferred endpoints. runtype mcp calls the Runtype protocol servers; the separate runtype tools command manages runtime tools saved in your Runtype account.

Both servers expose helper tools that return platform rules and reference material. Follow this order so the client builds against accurate schemas instead of guessing.

  1. Call get_build_instructions before any create_* mutation. It accepts a task value of build-product, generate-flow, or explain-capabilities and returns the platform rules, schemas, step types, and variable-system guidance for that task. For build-product, an optional focus parameter (commerce, embed, subagents, skills, or search, comma-separated for multiple) includes the full in-depth guide for those areas inline; without it, those guides are summarized 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 runs a semantic search over the published docs corpus and returns a synthesized answer with citations — reach for it for “how do I…” and “what is…” questions, and for get_platform_documentation when you need an exact contract.
  3. Discover tools with list_tools, then run them with execute_tool.

On the Code Mode server, the equivalent of step 3 is to call search to list API methods grouped by category, drill into a method for its signature, then call execute. Still call get_build_instructions before building or designing anything.

Discovering tools with list_tools

list_tools returns your user-defined tools by default, plus a builtinToolsAvailable summary that groups the 100+ built-in platform tools by category. This summary lets a client see what’s available without pulling every built-in at once.

  • Small categories are inlined with full id, name, and description: data_management, file_operations, image_generation, knowledge_retrieval, web_scraping, and web_search. Record CRUD, asset storage, image generation, and web search are immediately visible.
  • Larger categories stay collapsed with a count and a drill-down hint: commerce and third_party_api. For third_party_api, the top vendors are surfaced in the summary.

Every tool returned — user or built-in — carries a source field of "user" or "builtin". Pass the id value to execute_tool verbatim.

Parameters

ParameterTypeDefaultDescription
source"user" | "builtin" | "all""user"Which catalog to return
categorystring—Filter built-ins to a single category
fullbooleanfalseReturn every built-in at once (large response — use sparingly)
include_schemabooleanfalseInline each tool’s parametersSchema so execute_tool needs no separate lookup

Deeper catalogs

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

Resource URIContents
runtype://catalog/builtin-toolsFull built-in tool catalog
runtype://catalog/orthogonal-toolsOrthogonal vendor API tools
runtype://catalog/ucp-commerceCommerce tools
runtype://catalog/provider-native-searchProvider-native search tools

Executing platform tools with execute_tool

execute_tool runs both your user tools and the built-in platform tools. For platform tools, pass the id exactly as it appears in list_tools — the server dispatches it through the built-in tool executor and returns the same response shape as a user tool execution.

Platform tool IDs come in two forms:

  • builtin:<name> — for example builtin:firecrawl, builtin:dalle, builtin:exa
  • platform:orthogonal:<vendor>:<tool> — for example platform:orthogonal:apollo:people_match

Call list_tools with include_schema: true to inline each tool’s parametersSchema. The client then knows the expected arguments for execute_tool without a second round trip.

Deploying sandboxes

Two tools manage the lifecycle of Runtype Sandbox containers, so a client can deploy generated code and get a live preview URL:

ToolWhat it does
deploy_sandboxDeploys code to a Runtype Sandbox container and returns { sandboxId, previewUrl }
destroy_sandboxTears down a sandbox by its sandboxId

Deploy returns a previewUrl you can open immediately to see the running result. Always call destroy_sandbox when you’re done to release the container.

Deploying example templates

Two tools expose Runtype’s first-party example gallery (the examples at runtype.com/examples), so a client can restore a complete, working product into the account by its example slug. The slug is the same identifier the dashboard uses on its deploy page (/now?example=<slug>).

ToolWhat it does
list_example_templatesLists the published example templates: slug, title, description, capability and surface summary, and the template’s variable specs. Pass include_drafts: true to include unpublished drafts.
create_product_from_exampleDeploys a product from exactly one of slug, session, or url, resolving the document with the supplied variables (template defaults fill the rest) and assembling the product with its flows, agents, tools, and surfaces. Draft slugs are rejected unless you pass allow_draft: true.

create_product_from_example accepts every identifier the dashboard deploy page understands:

  • slug: a first-party example (/now?example=<slug>, runtype.com/examples/<slug>)
  • session: a shared session id (/now?session=<id>), resolved to that session’s hosted FPO document
  • url: a pasted link. Dashboard /now links (including templateParam:<key> variable values), example pages, and direct https URLs to an FPO, FPO template, or A2A agent card all work.

The typical pattern is list-then-create: call list_example_templates to discover slugs and each template’s variables, then call create_product_from_example with the chosen identifier. If required variable values are missing, nothing is created; the response comes back with created: false, the missing variable keys, and the full variable specs, so you can call again with a complete variables object.

After a successful create, call get_product_configuration with the returned product ID. It reports any pending secrets the example needs and returns a dashboard URL where a human can fill them in securely.

For the full picture of what’s left to make the product live, call get_product_setup instead: it composes the pending secrets with every surface’s remaining install steps into one readiness report, and each step names the best way to satisfy it (an MCP tool to call now, a REST call from a coding harness, or a dashboard link when a browser is genuinely required). Use get_surface_setup to check a single surface, such as whether a Slack surface still needs its OAuth install.

Both tools drive the same quick-start import endpoints documented in Importing products, so the result is identical to deploying the example from the dashboard.

Managing record collections

Seven tools manage record collections: registrations of a record type that optionally carry a metadata schema, validated at every record write according to the collection’s validation mode (off, warn, or enforce).

ToolWhat it does
list_collectionsLists collections with cursor pagination; include_count: true adds per-collection record counts.
get_collectionFetches a collection by slug, with include_history: true for the schema version history.
create_collectionRegisters a record type as a collection. validation_mode defaults to off, so creation changes no existing behavior.
update_collectionUpdates display fields, the schema, or the validation mode. Breaking schema changes are rejected while the resulting mode is enforce; flipping to enforce returns an enforceCheck dry-run summary.
delete_collectionDeletes the registration only; records of the type are untouched.
infer_collection_schemaSamples existing records and proposes a schema with per-field confidence. Saves nothing; persist the proposal with update_collection.
validate_collection_recordsDry-runs existing records against the saved schema (or a proposed one) and reports how many would fail, with examples. Writes nothing; this is the preview before switching to enforce.

The typical adoption pattern is create, infer, save in warn mode, dry-run with validate_collection_records, then enforce once existing records conform. See Defining a schema for the full walkthrough, including the REST, SDK, and CLI equivalents.

Running flows with dispatch

When you run a flow through the MCP server with dispatch, debug mode is on by default, so the response includes each unified step_complete.result instead of only the final execution_complete summary. This lets the client verify exactly what the flow ran. To stream events as they happen, set streamResponse (camelCase) on the request.

Next steps